diff --git a/README.md b/README.md index 2eb1a7a2fde822b48a4c7880e9a0631ba6e87c2e..a4afc89e4dc7e7eebef7e0fd3f400d08f46e510f 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,25 @@ # The Reaction Model Metadata Format (RMMD) -... is a YAML-based file format that is defined using a JSON schema. +... is a YAML-based file format that is designed to help researchers add meaningful and detailed metadata to their reaction models, rates constant parameters, etc.. It is similar to, and in parts based on, the [Citation File Format](https://citation-file-format.github.io/) [^CFF], but it is specific to the domain of reaction modeling. -It is essentially a YAML file ending with *.rmmd and follows a specific structure (check out the `examples/` directory). +An RMMD file is essentially a YAML file with the file ending *.rmmd that follows a specific structure or "schema" (check out the `examples/` directory). -The RMMD format should enable researchers to add meaningful and detailed metadata to their reaction models, rates constant parameters, etc.. -It should make it easier for other researchers to find reaction model data, allow them to determine its usefulness to them and enable automated data collection, e.g., for machine learning. +The goal is to enable adding metadata to any dataset containing rate parameters which can be as simple as a single CHEMKIN file. +Adding an RMMD file makes it easier for other researchers to find reaction model data, allows them to determine the data's usefulness and enables automated data collection, e.g., for machine learning. [^CFF]: published under CC-BY 4.0: Druskat, S., Spaaks, J. H., Chue Hong, N., Haines, R., Baker, J., Bliven, S., Willighagen, E., Pérez-Suárez, D., & Konovalov, O. (2021). Citation File Format (Version 1.2.0) [Computer software]. https://doi.org/10.5281/zenodo.5171937 An RMMD file contains information about species, reactions and parameters. -For each parameter(set) one can add provenance information by specifying the research acitvity that created the parameter. -This way of providing provenance information is already used in the [PRVO ontology](https://www.w3.org/TR/prov-o/) and has been applied to the problem of describing research processes, data and materials in the [Metadata4Ing ontology](https://nfdi4ing.pages.rwth-aachen.de/metadata4ing/metadata4ing/1.2.1/index.html). - -The concepts of describing the evolution of data/materials during a research activity as inputs and outputs of an activity/processing step as well as the association of an activity with tools and methods comes from the Metadata4Ing ontology. -It is much more general than this format, but also not as straightforward and easy to apply. In principle, the provenance mechanism in RMMD is compatible with Metada4Ing. - -# Content +For each parameter(set) one can add provenance information, i.e. information about where the data comes from. This can be done by specifying the acitvity that created the parameter. +This way of providing provenance information was established in the [PROV ontology](https://www.w3.org/TR/prov-o/) and has been applied to the problem of describing research processes, data and materials in the [Metadata4Ing ontology](https://nfdi4ing.pages.rwth-aachen.de/metadata4ing/metadata4ing/1.2.1/index.html). +In Metadata4Ing, a research activity is modeled as a "processing step" which has inputs and outputs. Also, a processing step (activity) can be associated with tools and methods. The Metadata4Ing ontology is much more general than this format, but also not as straightforward and easy to apply. In principle, the provenance mechanism in RMMD is compatible with Metada4Ing. +## Content <!--This is Gitlab specific syntax to generate a table of contents --> [[_TOC_]] -# Challenges With Common Publication Practices +## Challenges With Common Publication Practices In the past decades, researchers have produced a lot of reaction models[^rm-def] but often without relevant metadata. The emergence of automated tool for reaction model generation (e.g, RMG, Kinbot, ChemTraYzer, ...) lead to the production and publication of even more data. @@ -35,18 +32,20 @@ In practice this means that there are a bunch of problems other researchers can - Findability: Even if someone already determined accurate parameters for a species or reaction you are interested in, it can be hard to find that data and the associated publication, e.g., when a mechanism includes data on a reaction intermediate whose IUPAC name is not mentioned in the publication. - Many more: no data usage license, unknown uncertainties, ... -[^rm-def]: Here, a reaction model is considered the set of reactions, species and model parameters for kinetics, material transport and thermochemistry typically distributed as dataset. +[^rm-def]: Here, a reaction model is considered the set of reactions, species and model parameters for kinetics, material transport and thermochemistry typically distributed in a single file. [^fairprinciples]: [FAIR Principles](https://www.go-fair.org/fair-principles/) -## A Metadata Schema as Part of the Solution +### A Metadata Schema as Part of the Solution -Some FAIR principles can be implemented fairly <!-- ;) --> easily, e.g., by adding a data usage license to ones model and uploading the model to a platform that provides DOIs. +Some FAIR principles can be implemented fairly <!-- ;) --> easily, e.g., by adding a data usage license to one's model and uploading the model to a platform that provides DOIs. -The above named problems, however, require the model creator to add additional information specific to the domain of reaction-modeling or chemistry (["rich" metadata](https://www.go-fair.org/fair-principles/r1-metadata-richly-described-plurality-accurate-relevant-attributes/)). +The above named problems, however, require the model creator to add additional information that is specific to the domain of reaction-modeling or chemistry (["rich" metadata](https://www.go-fair.org/fair-principles/r1-metadata-richly-described-plurality-accurate-relevant-attributes/)), e.g., a canonical species identifier . For this rich metadata to be really useful to others, it needs to be machine readable which requires a standardized way of supplying this kind of data. This is where metadata schemas come into play. Since we could not find a suitable schema, e.g., on [https://fairsharing.org/](https://fairsharing.org/) or in the [Metadata Standards Catalog](https://rdamsc.bath.ac.uk/) we started developing a new one. +The RMMD format is currently in beta version. **We are looking for contributors/co-authors**: check out the [contribution guidelines](CONTRIBUTING.md). + # Creating Your Own RMMD File ## Editing RMMD files