diff --git a/sphinx/about.rst b/sphinx/about.rst index 4de894c..c2a0a0c 100644 --- a/sphinx/about.rst +++ b/sphinx/about.rst @@ -1,92 +1,48 @@ -Battery Domain Ontology -======================= - -.. raw:: html - - - -The Battery Domain Ontology is a specialized domain within the -Elementary Multiperspective Materials Ontology -`(EMMO) `__, that encompasses -essential terms and relationships for battery systems, materials, -methods, and data. Its primary objective is to enable the creation of -linked and FAIR (Findable, Accessible, Interoperable, and Reusable) -data, thereby fostering advancements in research and innovation within -the realm of battery. This ontology serves as a foundational resource -for harmonizing battery knowledge representation, enhancing data -interoperability, and accelerating progress in battery research and -development. - -A reference documentation is available in -`html `__ and -`pdf `__ -formats. - -Persistent Identifiers -~~~~~~~~~~~~~~~~~~~~~~ - -This ontology assigns persistent machine-readable identifiers to -concepts from the battery domain. These identifiers facilitate data -exchange and interoperability among various tools and systems. It -includes annotations to other sources of information including -`DBPedia `__ and -`Wikidata `__. +About the Electrochemistry Ontology (ECHO) +========================================== +.. |DOI| image:: https://zenodo.org/badge/570454941.svg + :target: https://zenodo.org/badge/latestdoi/570454941 -Standardized Nomenclature -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ontology builds on standardized nomenclature for battery, relying on -recognized authorities including -`IUPAC `__ and the -`IEC `__. IUPAC is the -universally-recognized authority on chemical nomenclature and -terminology, and IEC is the the world’s leading organization that -prepares and publishes International Standards for all electrical, -electronic and related technologies. This consistency in naming -conventions enhances collaboration and data sharing. - -Key Features ------------- - -- Seamless integration with the EMMO ontology. -- Provides persistent machine-readable identifiers for battery systems, - devices, methods, datasets, and quantities. -- Standardized nomenclature for battery entities. -- Facilitates data exchange and interoperability within the EMMO - ecosystem. - -Usage ------ - -Researchers, domain experts, and developers within the battery -communities can utilize the ontology for various purposes, including: - -- Incorporating consistent and standardized information into their - modeling and simulation activities. -- Enhancing data interoperability between modeling tools, databases, - and platforms. -- Supporting research projects that require precise and standardized - battery knowledge representation. -- Building applications, databases, or knowledge graphs that leverage - EMMO and require battery information. +The EMMO Electrochemistry Domain Ontology (ECHO) is a semantic resource for the terms and relations needed to describe things, processes, and data in the electrochemistry domain. It can be used to **generate linked data** for the Semantic Web, **comply with the FAIR data guidelines**, support **interoperaility of data** among different systems, and more! + +ECHO is intended to support researchers, engineers, and developers within the electrochemical +communitiy with activities like: + +- Incorporating consistent and standardized information into their modeling and simulation activities. +- Enhancing data interoperability between modeling tools, databases, and platforms. +- Supporting research projects that require precise and standardized electrochemical knowledge representation. +- Building applications, databases, or knowledge graphs that leverage EMMO and require electrochemical information. - Generating linked data in the semantic web. -- Complying with FAIR data mandates (FAIR Guidelines available - `here `__) +- Complying with `FAIR data guidelines `__. -Structure and Integration with EMMO ------------------------------------ +Key features of the ontology +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Persistent machine-readable identifiers +--------------------------------------- + +This ontology assigns persistent machine-readable identifiers (called URIs or IRIs) to concepts from the electrochemistry domain. These identifiers can be resolved to point to human-readable documentation for the term or machine-readable ontology files. Persistent and unique identifiers facilitate data exchange and interoperability among various tools and systems by ensuring consistent nomenclature and providing access to context about the term. + +Standardized Nomenclature +------------------------- -The Battery Domain Ontology is an official domain on the EMMO. The -asserted source consists of two files: - ``battery.ttl``: describes -terms and object properties for the battery domain. - -``batteryquantities.ttl``: describes the physical quantities related to -the battery domain. It is encapsulated to allow it to be imported by -other EMMO domains without needing to import the entire ontology. +The ontology builds on standardized nomenclature for electrochemistry, relying on recognized authorities. This consistency in nomenclature enhances collaboration and data sharing. In order of precedence, this includes: -The battery domain also imports other EMMO domains: - `Chemical -Substance Domain -Ontology `__: -provides material annotations for battery (meta)data. +#. `Public IEC/ISO standard vocabulary `__ The IEC is the the world’s leading organization that prepares and publishes International Standards for all electrical, electronic and related technologies. +#. `IUPAC Goldbook `__. IUPAC is the universally-recognized authority on chemical nomenclature and terminology. +#. Pre-eminent domain textbooks (e.g. `Bard `__, `Newman `__, etc.) +#. Discussions with leading figures in electrochemical research + +Through a set of term annotations, the ontology also provides links to equivalent terms in other digital knowledge bases, including: + +#. `DBpedia `__ +#. `WikiData `__ +#. `Wikipedia `__ + +Structure and Integration with EMMO +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Electrochemistry Ontology is an official domain of the EMMO. This allows users to benefit from a well-developed and logically consistent framework as well as interoperability with other EMMO domains. For example, the Electrochemistry Ontology also imports other EMMO domains: - `Chemical Substance Domain Ontology `__: provides material annotations for electrochemical (meta)data. The import structure is summarized in the following table: @@ -99,94 +55,21 @@ The import structure is summarized in the following table: - 1.0.0-beta5 * - chemical-substance - 0.2.0-alpha - * - electrochmistry - - 0.7.0-alpha - -For simplicity, we complie the source files and other imports into a -`pre-inferred ontology `__. This -is the result of running the asserted source files through a semantic -reasoner and includes both asserted and inferred properties in a clear -graph. - -Getting Started ---------------- - -Prerequisites -~~~~~~~~~~~~~ - -Before you begin, we recommend that you install the following tools. -They are not all required, but greatly simplify the process of working -with ontologies: -- `Protégé `__ (a graphical ontology - editor) +The onotlogy exists in two forms: (i) the asserted source files and (ii) the pre-inferred version. - - Installation instructions are available - `here `__. +The asserted source consists of two files: - ``electrochemistry.ttl``: describes terms and object properties for the electrochemistry domain. - ``electrochemicalquantities.ttl``: describes the quantities related to the electrochemistry domain. It is encapsulated to allow it to be imported by other EMMO domains without needing to import the entire ontology. -- `EMMOntoPy `__ (python - package for working with EMMO ontologies) - - - Installation instructions are available - `here `__. - -- `RDFLib `__ (optional, - python package for working with RDF graphs) - - - Installation instructions are available - `here `__. - -- `VS Studio Code `__ (optional, a code - editor with extensions for RDF formats like TTL and JSON-LD) - - - Installation instructions are available - `here `__. - -Quick Start -~~~~~~~~~~~ - -To quickly explore and make use of the ontology, first download the -pre-inferred version `pre-inferred -ontology `__. You can then simply -open the file in Protégé and explore its content or load the ontology -into python using EMMOntoPy. - -In `EMMOntoPy `__, you can -choose to import the ontology from your local downloaded copy or -directly from the web. Commands for both options are given below: - -.. code:: python - - from ontopy import get_ontology - - # Loading from local repository - battery = get_ontology('/path/to/domain-battery/battery-inferred.ttl').load(url_from_catalog=True) - - # Loading from web - battery = get_ontology('https://raw.githubusercontent.com/emmo-repo/domain-battery/master/inferred_version/battery-inferred.ttl').load() - -Contributing ------------- - -We welcome contributions from the community to enhance and expand the ontology. If you have suggestions, improvements, -or additional chemical substance information to contribute, please refer to our :ref:`contributing -guidelins`. +The pre-inferred ontology runs the reasoner on the source files and their imports and complies them into a `pre-inferred ontology file `__. This provides a simpler reference for users of the ontology and removes the barrier of needed to run the reasoner themselves. Acknowledgements ~~~~~~~~~~~~~~~~ -This project has received support from European Union research and -innovation programs, under grant agreement numbers: +This project has received support from European Union research and innovation programs, under grant agreement numbers: - 957189 - `BIG-MAP `__ License ------- -The Battery Interface Domain Ontology is released under the `Creative -Commons Attribution 4.0 -International `__ -license (CC BY 4.0). - -.. |DOI| image:: https://zenodo.org/badge/570454101.svg - :target: https://zenodo.org/badge/latestdoi/570454101 +The Battery Interface Domain Ontology is released under the `Creative Commons Attribution 4.0 International `__ license (CC BY 4.0). diff --git a/sphinx/example_alkaline_electrochemical_cell.rst b/sphinx/example_alkaline_electrochemical_cell.rst new file mode 100644 index 0000000..68067ac --- /dev/null +++ b/sphinx/example_alkaline_electrochemical_cell.rst @@ -0,0 +1,39 @@ +Alkaline Electrochemical Cell +============================= + +This example, let's describe an instance of a simple alkaline electrochemical cell. + +.. hint:: + + In this ontology, an ``ElectrochemicalCell`` is simply a combination of components in a holistic arrangement (i.e. two electrodes in contact with an electrolyte). Adding a case and terminals to make it a functional device makes it a ``BatteryCell`` described in the battery domain ontology. + +The JSON-LD description of the material is given below: + +.. tab-set:: + + .. tab-item:: JSON + + .. code-block:: json + :linenos: + + { + "@context": "https://raw.githubusercontent.com/emmo-repo/domain-electrochemistry/master/context.json", + "@type": "ElectrochemicalCell", + "hasNegativeElectrode": { + "@type": "ZincElectrode" + }, + "hasPositiveElectrode": { + "@type": "ManganeseDioxideElectrode" + }, + "hasElectrolyte": { + "@type": "AlkalineElectrolyte" + } + } + + .. tab-item:: JSON-LD Playground + + .. raw:: html + +
+ +
\ No newline at end of file diff --git a/sphinx/example_aqueous_electrolyte_KOH.rst b/sphinx/example_aqueous_electrolyte_KOH.rst new file mode 100644 index 0000000..07e5d22 --- /dev/null +++ b/sphinx/example_aqueous_electrolyte_KOH.rst @@ -0,0 +1,65 @@ +Aqueous KOH Electrolyte +======================= + +This example, let's describe an instance of some aqueous potassium hydroxide (KOH) electrolyte with some properties. The JSON-LD description of the material is given below: + +.. tab-set:: + + .. tab-item:: JSON + + .. code-block:: json + :linenos: + + { + "@context": "https://raw.githubusercontent.com/emmo-repo/domain-electrochemistry/master/context.json", + "@type": "Electrolyte", + "hasSolvent": { + "@type": "Water" + }, + "hasSolute": { + "@type": "PotassiumHydroxide", + "hasProperty": { + "@type": ["AmountConcentration", "ModelledProperty"], + "hasNumericalPart": { + "@type": "Real", + "hasNumericalValue": 7 + }, + "hasMeasurementUnit": "emmo:MolePerLitre" + } + }, + "hasProperty": [ + { + "@type": ["Density", "MeasuredProperty"], + "hasNumericalPart": { + "@type": "Real", + "hasNumericalValue": 1.289 + }, + "hasMeasurementUnit": "emmo:KilogramPerLitre" + }, + { + "@type": ["IonicConductivity", "MeasuredProperty"], + "hasNumericalPart": { + "@type": "Real", + "hasNumericalValue": 65 + }, + "hasMeasurementUnit": "emmo:SiemensPerCentiMetre" + } + ] + } + + .. tab-item:: JSON-LD Playground + + .. raw:: html + +
+ +
+ +This example highlights a few things: + +#. **EMMO distinguishes properties according to how they were determined.** In this example, a ``ConventionalProperty`` is a property whose value is assigned by convention (e.g. from a technical specification sheet, handbook, etc.). EMMO also provides terms for ``MeasuredProperty`` for properties which were actually determined by some measurement and ``ModelledProperty`` for properties that were obtained from some model. + +#. **EMMO has a specific way of expressing quantitative properties.** As shown in the example, a quantitative property has a ``@type`` that describes what kind of property it is, ``hasNumericalPart`` describes the value, and ``hasMeasurementUnit`` defines the unit. Please adhere to this format when expressing quantities in your linked data. + +#. **We can re-use terms from common vocabularies like schema.org.** One of the core principles of linked data is to re-use existing vocabularies when possible. The schema.org vocabulary was developed to support internet search engines and contains terms for things that people often search for (e.g. people, organizations, products, etc.) In this case, we can re-use schema.org terms to describe the manufacturer and product. + diff --git a/sphinx/example_cyclic_voltammetry.rst b/sphinx/example_cyclic_voltammetry.rst new file mode 100644 index 0000000..8b3e5cf --- /dev/null +++ b/sphinx/example_cyclic_voltammetry.rst @@ -0,0 +1,90 @@ +Cyclic Voltammetry Data +======================= + +This example, let's describe an instance of some data resulting from a cyclic voltammetry measurement. The JSON-LD description of the material is given below: + +.. tab-set:: + + .. tab-item:: Raw Data + + Here is a sample of the raw data. The full dataset is available `here `__. + + .. code-block:: text + + Potential vs. Li, I, Current density + 3.23298835754395, -2.4205593945E-5, -1.82364020204592E-5 + 3.23400592803955, 4.0393830738E-5, 3.04325577863671E-5 + 3.23596382141113, 8.0873372277E-5, 6.09296897628194E-5 + 3.23801350593567, 1.02431497847E-4, 7.71714992220444E-5 + 3.23996043205261, 1.18972335809E-4, 8.96333033618521E-5 + 3.24193286895752, 1.32529418259E-4, 9.98471574959202E-5 + 3.24395799636841, 1.43424495793E-4, 1.0805546729429E-4 + ... + + .. tab-item:: JSON + + .. code-block:: json + :linenos: + + { + "@context": "https://raw.githubusercontent.com/emmo-repo/domain-electrochemistry/master/context.json", + "@type": "MeasurementResult", + "csvw:url": "https://archive.big-map.eu/records/24mdd-z2x02/files/LNO%20CV.csv", + "dc:title": "Example Cyclic Voltammetry Data", + "dcat:keyword": ["cyclic voltammetry", "LNO", "battery"], + "dc:license": "BIG-MAP Archive License", + "dc:modified": {"@value": "2024-01-29", "@type": "xsd:date"}, + "dc:creator": { + "@id": "https://orcid.org/0000-0002-9401-1362", + "schema:name": "Christian Wolke" + }, + "dc:contributor": { + "@id": "https://orcid.org/0000-0002-8758-6109", + "schema:name": "Simon Clark" + }, + "@reverse": { + "hasOutput": { + "@type": "CyclicVoltammetry" + } + }, + "csvw:tableSchema": { + "csvw:columns": [{ + "csvw:name": "potential", + "csvw:titles": "Potential vs. Li", + "csvw:propertyUrl": "ElectricPotential", + "hasMeasurementUnit": "emmo:MilliVolt", + "csvw:datatype": "number", + "csvw:required": true + }, { + "csvw:name": "current", + "csvw:titles": "I", + "csvw:propertyUrl": "ElectricCurrent", + "hasMeasurementUnit": "emmo:MilliAmpere", + "csvw:datatype": "number" + }, { + "csvw:name": "current density", + "csvw:titles": "Current density", + "csvw:propertyUrl": "ElectricCurrentDensity", + "hasMeasurementUnit": "emmo:MilliAmperePerSquareCentiMetre", + "csvw:datatype": "number" + }], + "csvw:primaryKey": "potential" + } + } + + .. tab-item:: JSON-LD Playground + + .. raw:: html + +
+ +
+ +This example highlights a few things: + +#. **EMMO distinguishes properties according to how they were determined.** In this example, a ``ConventionalProperty`` is a property whose value is assigned by convention (e.g. from a technical specification sheet, handbook, etc.). EMMO also provides terms for ``MeasuredProperty`` for properties which were actually determined by some measurement and ``ModelledProperty`` for properties that were obtained from some model. + +#. **EMMO has a specific way of expressing quantitative properties.** As shown in the example, a quantitative property has a ``@type`` that describes what kind of property it is, ``hasNumericalPart`` describes the value, and ``hasMeasurementUnit`` defines the unit. Please adhere to this format when expressing quantities in your linked data. + +#. **We can re-use terms from common vocabularies like schema.org.** One of the core principles of linked data is to re-use existing vocabularies when possible. The schema.org vocabulary was developed to support internet search engines and contains terms for things that people often search for (e.g. people, organizations, products, etc.) In this case, we can re-use schema.org terms to describe the manufacturer and product. + diff --git a/sphinx/example_eis_nyquist.rst b/sphinx/example_eis_nyquist.rst new file mode 100644 index 0000000..fe215fc --- /dev/null +++ b/sphinx/example_eis_nyquist.rst @@ -0,0 +1,87 @@ +Cyclic Voltammetry Data +======================= + +This example, let's describe an instance of some data describing an Nyquist plot from an EIS measurement. The JSON-LD description of the material is given below: + +.. tab-set:: + + .. tab-item:: Raw Data + + Here is a sample of the raw data. The full dataset is available `here `__. + + .. code-block:: text + + Z_real (Ohm), Z_imag (Ohm) + 0.697447795823666, 0.0594427244582042 + 0.703016241299304, 0.02786377708978327 + 0.7122969837587008, 0.0018575851393187737 + 0.7178654292343388, -0.022291021671826727 + 0.7290023201856148, -0.05015479876161011 + 0.7549883990719257, -0.07987616099071215 + 0.7735498839907193, -0.10030959752321988 + 0.8013921113689095, -0.11888544891640884 + 0.8348027842227379, -0.13003095975232204 + ... + + .. tab-item:: JSON + + .. code-block:: json + :linenos: + + { + "@context": "https://raw.githubusercontent.com/emmo-repo/domain-electrochemistry/master/context.json", + "@type": "MeasurementResult", + "csvw:url": "https://archive.big-map.eu/records/24mdd-z2x02/files/LNO%20CV.csv", + "dc:title": "Example EIS Nyquist Plot Data", + "dcat:keyword": ["EIS", "Nyquist"], + "dc:license": "BIG-MAP Archive License", + "dc:modified": {"@value": "2024-01-29", "@type": "xsd:date"}, + "dc:source": "http://dx.doi.org/10.1149/2.0321816jes", + "dc:contributor": { + "@id": "https://orcid.org/0000-0002-8758-6109", + "schema:name": "Simon Clark" + }, + "@reverse": { + "hasOutput": { + "@type": "ElectrochemicalImpedanceSpectroscopy" + } + }, + "csvw:tableSchema": { + "csvw:columns": [{ + "csvw:name": "real", + "csvw:titles": "Z_real (Ohm)", + "csvw:propertyUrl": { + "@type": ["ElectricImpedance", "Real"] + }, + "hasMeasurementUnit": "emmo:Ohm", + "csvw:datatype": "number", + "csvw:required": true + }, { + "csvw:name": "imaginary", + "csvw:titles": "Z_imag (Ohm)", + "csvw:propertyUrl": { + "@type": ["ElectricImpedance", "Imaginary"] + }, + "hasMeasurementUnit": "emmo:Ohm", + "csvw:datatype": "number" + }], + "csvw:primaryKey": "real" + } + } + + .. tab-item:: JSON-LD Playground + + .. raw:: html + +
+ +
+ +This example highlights a few things: + +#. **EMMO distinguishes properties according to how they were determined.** In this example, a ``ConventionalProperty`` is a property whose value is assigned by convention (e.g. from a technical specification sheet, handbook, etc.). EMMO also provides terms for ``MeasuredProperty`` for properties which were actually determined by some measurement and ``ModelledProperty`` for properties that were obtained from some model. + +#. **EMMO has a specific way of expressing quantitative properties.** As shown in the example, a quantitative property has a ``@type`` that describes what kind of property it is, ``hasNumericalPart`` describes the value, and ``hasMeasurementUnit`` defines the unit. Please adhere to this format when expressing quantities in your linked data. + +#. **We can re-use terms from common vocabularies like schema.org.** One of the core principles of linked data is to re-use existing vocabularies when possible. The schema.org vocabulary was developed to support internet search engines and contains terms for things that people often search for (e.g. people, organizations, products, etc.) In this case, we can re-use schema.org terms to describe the manufacturer and product. + diff --git a/sphinx/example_zinc_electrode.rst b/sphinx/example_zinc_electrode.rst new file mode 100644 index 0000000..f34a0c1 --- /dev/null +++ b/sphinx/example_zinc_electrode.rst @@ -0,0 +1,78 @@ +Zinc Electrode +============== + +This example, let's describe an instance of some electrode made by a specific person at a research institute using zinc foil. The electrode has properties that were determined from a combination of a specification sheet and actual measurements. The JSON-LD description of the material is given below: + +.. tab-set:: + + .. tab-item:: JSON + + .. code-block:: json + :linenos: + + { + "@context": "https://raw.githubusercontent.com/emmo-repo/domain-electrochemistry/master/context.json", + "@type": "Electrode", + "schema:manufacturer": { + "@id": "https://www.wikidata.org/wiki/Q3041255", + "schema:name": "SINTEF" + }, + "schema:creator": { + "@id": "https://orcid.org/0000-0002-8758-6109", + "schema:name": "Simon Clark" + }, + "hasActiveMaterial": { + "@type": ["Zinc", "Foil"] + }, + "hasProperty": [ + { + "@type": ["SpecificCapacity", "MeasuredProperty"], + "hasNumericalPart": { + "@type": "Real", + "hasNumericalValue": 800 + }, + "hasMeasurementUnit": "emmo:MilliAmpereHourPerGram" + }, + { + "@type": ["Thickness", "ConventionalProperty"], + "hasNumericalPart": { + "@type": "Real", + "hasNumericalValue": 250 + }, + "hasMeasurementUnit": "emmo:MicroMetre" + }, + { + "@type": ["Diameter", "MeasuredProperty"], + "hasNumericalPart": { + "@type": "Real", + "hasNumericalValue": 2 + }, + "hasMeasurementUnit": "emmo:CentiMetre" + }, + { + "@type": ["Mass", "MeasuredProperty"], + "hasNumericalPart": { + "@type": "Real", + "hasNumericalValue": 2.5 + }, + "hasMeasurementUnit": "emmo:Gram" + } + ] + } + + .. tab-item:: JSON-LD Playground + + .. raw:: html + +
+ +
+ +This example highlights a few things: + +#. **EMMO distinguishes properties according to how they were determined.** In this example, a ``ConventionalProperty`` is a property whose value is assigned by convention (e.g. from a technical specification sheet, handbook, etc.). EMMO also provides terms for ``MeasuredProperty`` for properties which were actually determined by some measurement and ``ModelledProperty`` for properties that were obtained from some model. + +#. **EMMO has a specific way of expressing quantitative properties.** As shown in the example, a quantitative property has a ``@type`` that describes what kind of property it is, ``hasNumericalPart`` describes the value, and ``hasMeasurementUnit`` defines the unit. Please adhere to this format when expressing quantities in your linked data. + +#. **We can re-use terms from common vocabularies like schema.org.** One of the core principles of linked data is to re-use existing vocabularies when possible. The schema.org vocabulary was developed to support internet search engines and contains terms for things that people often search for (e.g. people, organizations, products, etc.) In this case, we can re-use schema.org terms to describe the manufacturer and product. + diff --git a/sphinx/example_zinc_powder.rst b/sphinx/example_zinc_powder.rst new file mode 100644 index 0000000..cfa7d1d --- /dev/null +++ b/sphinx/example_zinc_powder.rst @@ -0,0 +1,49 @@ +Zinc Powder +=========== + +This example, let's describe an instance of some zinc powder with a set of properties defined in the specification sheet from the manufacturer. The JSON-LD description of the material is given below: + +.. tab-set:: + + .. tab-item:: JSON + + .. code-block:: json + :linenos: + + { + "@context": "https://raw.githubusercontent.com/emmo-repo/domain-electrochemistry/master/context.json", + "@type": ["Zinc", "Powder"], + "schema:manufacturer": { + "@id": "https://www.wikidata.org/wiki/Q680841", + "schema:name": "Sigma-Aldrich" + }, + "schema:productID": "324930", + "schema:url": "https://www.sigmaaldrich.com/NO/en/product/aldrich/324930", + "hasProperty": [ + { + "@type": ["D95ParticleSize", "ConventionalProperty"], + "hasNumericalPart": { + "@type": "Real", + "hasNumericalValue": 150 + }, + "hasMeasurementUnit": "emmo:MicroMetre", + "dc:source": "https://www.sigmaaldrich.com/NO/en/product/aldrich/324930" + } + ] + } + + .. tab-item:: JSON-LD Playground + + .. raw:: html + +
+ +
+ +This example highlights a few things: + +#. **EMMO distinguishes properties according to how they were determined.** In this example, a ``ConventionalProperty`` is a property whose value is assigned by convention (e.g. from a technical specification sheet, handbook, etc.). EMMO also provides terms for ``MeasuredProperty`` for properties which were actually determined by some measurement and ``ModelledProperty`` for properties that were obtained from some model. + +#. **EMMO has a specific way of expressing quantitative properties.** As shown in the example, a quantitative property has a ``@type`` that describes what kind of property it is, ``hasNumericalPart`` describes the value, and ``hasMeasurementUnit`` defines the unit. Please adhere to this format when expressing quantities in your linked data. + +#. **We can re-use terms from common vocabularies like schema.org.** One of the core principles of linked data is to re-use existing vocabularies when possible. The schema.org vocabulary was developed to support internet search engines and contains terms for things that people often search for (e.g. people, organizations, products, etc.) In this case, we can re-use schema.org terms to describe the manufacturer and product. \ No newline at end of file diff --git a/sphinx/examples.rst b/sphinx/examples.rst new file mode 100644 index 0000000..ebdea2e --- /dev/null +++ b/sphinx/examples.rst @@ -0,0 +1,52 @@ +Examples +======== + +Here are some examples to help you get started. You are free to re-use or modify them as needed to fit your needs. + +.. grid:: + + .. grid-item-card:: + :link: example_zinc_powder.html + + :octicon:`ruby;1em;sd-text-info` Zinc Powder + ^^^^^^^^^^^ + A zinc powder material from a manufacturer with properties defined in a specification sheet. + + .. grid-item-card:: + :link: example_zinc_electrode.html + + :octicon:`plus;1em;sd-text-info` Zinc Electrode + ^^^^^^^^^^^ + A zinc foil electrode manufactured by a person at a research institute with a mix of properties from a specification sheet and measured. + +.. grid:: + + .. grid-item-card:: + :link: example_aqueous_electrolyte_KOH.html + + :octicon:`plus-circle;1em;sd-text-info` Aqueous KOH Electrolyte + ^^^^^^^^ + An aqueous potassium hydroxide electrolyte with some properties. + + .. grid-item-card:: + :link: example_alkaline_electrochemical_cell.html + + :octicon:`zap;1em;sd-text-info` Alkaline Electrochemical Cell + ^^^^^^^^^^ + An alkaline electrochemical cell. + +.. grid:: + + .. grid-item-card:: + :link: example_cyclic_voltammetry.html + + :octicon:`pulse;1em;sd-text-info` Cyclic Voltammetry Data + ^^^^^^^^ + Raw data from a cyclic voltammetry measurement. + + .. grid-item-card:: + :link: example_eis_nyquist.html + + :octicon:`graph;1em;sd-text-info` EIS Nyquist Plot Data + ^^^^^^^^^^ + Processed data from an EIS Nyquist plot. \ No newline at end of file diff --git a/sphinx/faq.rst b/sphinx/faq.rst new file mode 100644 index 0000000..28c8e2a --- /dev/null +++ b/sphinx/faq.rst @@ -0,0 +1,42 @@ +FAQ Page +======== + +.. raw:: html + +
+
+ What is the Electrochemistry Ontology? +
+

+ A resource for creating semantic linked data related to electrochemical materials, components, cells, and testing data. It is part of the EMMO universe. +

+
+
+ +
+ What do I use the Electrochemistry Ontology for? +
+

+ This ontology is used mostly for generating linked data in the Semantic Web and complying with the FAIR data guidelines (although it can also do much more!). It provides machine-readable persistent identifiers for terms and semantic relations that help describe how things are related to each other. Terms and elucidations are derived from authoritative sources like the IEC and IUPAC, so you can be sure that your data & metadata are properly annotated. +

+
+
+ +
+ How do I use the Electrochemistry Ontology? +
+

+ Most people use the ontology is to annotate the terms in (meta)data schemas. A common and simple way to use the ontology is as a vocabulary in JSON-LD files. Check out our Examples to see how to do it. You can also visit the JSON-LD Playground for more detailed information. +

+
+
+
+ Why shoud I use the Electrochemistry Ontology? +
+

+ Get more value from your data and comply with the FAIR guidelines. +

+
+
+
+ diff --git a/sphinx/getstarted.rst b/sphinx/getstarted.rst new file mode 100644 index 0000000..ae27d56 --- /dev/null +++ b/sphinx/getstarted.rst @@ -0,0 +1,115 @@ +Get Started +================================ + +This ontology is used mostly for generating linked data and complying with the FAIR data guidelines (although it can also do much more!). It provides machine-readable persistent identifiers for terms and semantic relations that help describe what things are and how they are related to each other. + +An easy way to get started is to use the ontology vocabulary to create semantic linked data using JSON-LD files. We recommend you follow this step-by-step guide to understand the background and **make your first piece of linked data in just 5 easy steps!** + +Step 1: Install Protégé +~~~~~~~~~~~~~~~~~~~~~~~ + +`Protégé `__ is a graphical ontology editor developed by Stanford University. It is free and one of the most widely used tools for ontology development. You can read more about it in the tools section. + +Step 2: Download the pre-inferred version of the ontology +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ontologies within the EMMO universe import many different modules to try to re-use knowledge and terms from other domains. We then run a tool called a "reasoner" to make logical inferrences about how terms from different domains are connected, and lump them into one ontology. + +We make it easy for you by providing a pre-inferred version in advance. You can `download it from the GitHub repository `__ or access it at anytime using this URL: + +https://raw.githubusercontent.com/emmo-repo/domain-electrochemistry/master/electrochemistry-inferred.ttl + +Step 3: Open and explore the ontology file in Protégé +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Within Protégé, you can explore the class hierarchy that contains all the "things" that are included in the ontology, as well as the object properties that describe how those things are related to each other. There are a few things to notice: + +#. **Each item has a unique, persistent, and machine readable identifier called an IRI.** An IRI (Internationalized Reference Identifier) is the official identifier for that term. It is the anchor to which all other information is linked. In the EMMO universe, IRIs usually contain some Universal Unique Identifier (UUID) character sequence that ensures their uniqueness. For example, the IRI for ElectrochemicalCell is: + + https://w3id.org/emmo/domain/electrochemistry#electrochemistry_6f2c88c9_5c04_4953_a298_032cc3ab9b77 + + Clicking the link will take you to human-readable documentation. But if the request comes from an application or if you add a trailing slash / character to the IRI, then it will take you to a machine-readable turtle file. + + As you can see, the use of UUIDs in the IRIs make it difficult for humans to read and understand. But fear not! Each term also comes with a set of human readable labels called prefLabel and altLabel. + +#. **Each item has one human-readable preferred label and can have many alternative labels.** The EMMO universe uses the SKOS terminology for labelling items. The main label for the term is called its prefLabel (short for preferred label) and is often expressed in the source files as skos:prefLabel. But sometimes, there can be multiple labels for the same thing. In that case we use skos:altLabel to list possible alternative labels. + +#. **Each item has an elucidation, describing the meaning of the term.** The elucidation is a short human-readable text that describes the conceptualization for the term. It should give some insight into what the term means and how it can be used. + +#. **Many terms have links to other sources of information.** For many terms, there are other authoritative sources of information available that can provide more context about its meaning. To account for that, we include annotations that point to places like the IEC Vocabulary, IUPAC Goldbook, DBpedia, WikiData, or Wikipedia where humans or machines can go to retrieve more information. + +Step 4: Explore the JSON-LD context file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +JSON-LD is one of the easiest and most common file formats for creating linked data. JSON-LD uses the same key-value pair structure of traditional JSON, but adds a few keywords to support semantic linked data. One of these is the @context keyword, which points to a dictionary that pairs human readable term labels with machine readable IRIs. For convenience, we provide a JSON-LD context file that is generated from the pre-inferred version of the ontology that pairs prefLabels with IRIs. You can find the `context file on the GitHub repository `__ or access it anytime using this URL: + +https://raw.githubusercontent.com/emmo-repo/domain-electrochemistry/master/context.json + +Step 5: Make your own linked data! +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Now you can make your own piece of linked data using ontology terms and JSON-LD. Let's make a linked data description of a simple electrochemical cell consisting of a zinc negative electrode, a manganese dioxide positive electrode, and an alkaline electrolyte. This is expressed in JSON-LD as: + +.. tab-set:: + + .. tab-item:: JSON + + .. code-block:: json + :linenos: + + { + "@context": "https://raw.githubusercontent.com/emmo-repo/domain-electrochemistry/master/context.json", + "@type": "ElectrochemicalCell", + "hasNegativeElectrode": { + "@type": "ZincElectrode" + }, + "hasPositiveElectrode": { + "@type": "ManganeseDioxideElectrode" + }, + "hasElectrolyte": { + "@type": "AlkalineElectrolyte" + } + } + + .. tab-item:: JSON-LD Playground + + .. raw:: html + +
+ +
+ + +First, we use the ``@context`` keyword to establish the context for machines to process the file by pointing to our pre-inferred context file on GitHub. + +Then, we use the keyword ``@type`` to describe what type of thing we are describing, in this case an ``ElectrochemicalCell``. When a machine processes this file, it is going to check in the context and retrieve the IRI that is associated to the label ``ElectrochemicalCell``. + +Next, we use object properties that are defined in the ontology like ``hasNegativeElectrode``, ``hasPositiveElectrode``, and ``hasElectrolyte`` to define links to other things. In this example, we say that our electrochemical cell has a ngeative electrode, and that electrode is of the type ``ZincElectrode``. + +Finally, you can use the `JSON-LD Playground `__ to see how machines can process the linked data file. + +And that's it! You did it! Check out our examples to see some more advanced topics. + +We've provided some recommendations for tools and examples that you are free to re-use or modify for your own needs. + +.. grid:: + + .. grid-item-card:: + :link: tools.html + + :octicon:`tools;1em;sd-text-info` Tools + ^^^^^^^^^^^ + The right tool for the right job. Here are some tools that can help you work with ontologies, knowledge graphs, and linked data. + + .. grid-item-card:: + :link: resources.html + + :octicon:`book;1em;sd-text-info` Resources + ^^^^^^^^^^^ + Here are some other resources and best practices for creating linked data on the web. + + .. grid-item-card:: + :link: examples.html + + :octicon:`pencil;1em;sd-text-info` Examples + ^^^^^^^^ + Here are some examples that demonstrate basic usage of the ontology diff --git a/sphinx/index.rst b/sphinx/index.rst index be17e30..190f560 100644 --- a/sphinx/index.rst +++ b/sphinx/index.rst @@ -1,25 +1,62 @@ + .. toctree:: :includehidden: :hidden: - + + Get Started + Examples + Class Index About - Class Index - Resources - Contribute - + FAQ + +Battery Ontology +================================ + +Welcome to the **EMMO Battery Domain Ontology**, a semantic resource with essential terms and relationships to describe battery cells, materials, methods, and data. **Here's a simple example:** + +.. tab-set:: + + .. tab-item:: JSON + + .. code-block:: json + :linenos: + + { + "@context": "https://raw.githubusercontent.com/emmo-repo/domain-electrochemistry/master/context.json", + "@type": "ElectrochemicalCell", + "hasNegativeElectrode": { + "@type": "ZincElectrode" + }, + "hasPositiveElectrode": { + "@type": "ManganeseDioxideElectrode" + }, + "hasElectrolyte": { + "@type": "AlkalineElectrolyte" + } + } - + .. tab-item:: JSON-LD Playground + + .. raw:: html + +
+ +
+ + +Check out these resources to get started! +----------------------------------------- .. grid:: .. grid-item-card:: - :link: about.html + :link: getstarted.html - :octicon:`rocket;1em;sd-text-info` Quick Start + :octicon:`rocket;1em;sd-text-info` Get Started ^^^^^^^^^^^ Let's go! Here is some information to help you get started .. grid-item-card:: - :link: battery.html + :link: electrochemistry.html :octicon:`book;1em;sd-text-info` Class Index ^^^^^^^^^^^ @@ -27,10 +64,16 @@ .. grid:: + .. grid-item-card:: + :link: examples.html + + :octicon:`pencil;1em;sd-text-info` Examples + ^^^^^^^^ + Here are some examples that demonstrate basic usage of the ontology + .. grid-item-card:: :link: contribute.html :octicon:`thumbsup;1em;sd-text-info` Contribute ^^^^^^^^^^ - Help us develop the ontology by following these guidelines - + Help us develop the ontology by following these guidelines \ No newline at end of file diff --git a/sphinx/tools.rst b/sphinx/tools.rst new file mode 100644 index 0000000..b1520a1 --- /dev/null +++ b/sphinx/tools.rst @@ -0,0 +1,36 @@ +Ontology Tools +============== + +Working with ontologies and linked data does not have to be complicated. You could do most things in a text editor like Notepad, if you were so inclined. But having the right tools for the job can make your work easier and more effective. Below are some recommended tools that can help. + +.. grid:: + + .. grid-item-card:: + :link: https://protege.stanford.edu/ + + Protégé + ^^^^^^^^^^^ + A graphical ontology editor from Stanford Univeristy. It is useful for exploring the terms and connections in the ontology and performing reasoning. Advanced users can also use it to make edits to the source files. If you use only one tool for ontology development, this is the one you want. + + .. grid-item-card:: + :link: https://rdflib.readthedocs.io/en/stable/ + + RDFLib + ^^^^^^^^^^^ + A python library for working with ontologies and knowledge graphs. RDFLib is useful for integrating semantic data in python codes. It includes a simple triplestore with a SPARQL endpoint for running queries, as well as options to serialize data into RDF supported formats like JSON-LD, Turtle, etc. + +.. grid:: + + .. grid-item-card:: + :link: https://code.visualstudio.com/ + + Visual Studio Code + ^^^^^^^^ + A handy code editor and developer environment. It includes extensions for working with RDF data like JSON-LD and Turtle. It is useful for anyone working with the source files or creating instances of linked data. + + .. grid-item-card:: + :link: contribute.html + + EMMOntoPy + ^^^^^^^^^^ + A custom python package for working with EMMO-based ontologies. Built on `OWLReady2 `__, EMMOntoPy provides tools for loading, editing, analyzing, and exporting ontology data within the EMMO Universe. \ No newline at end of file