Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@jsimonclark
jsimonclark committed Jan 29, 2024
1 parent 854d93d commit 38dd05c
Show file tree
Hide file tree
Showing 12 changed files with 791 additions and 20 deletions.
84 changes: 69 additions & 15 deletions sphinx/about.rst
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,73 @@
========
BattINFO
========
About the Battery Ontology
==========================================

The **Batt**\ ery **IN**\ ter\ **F**\ ace **O**\ ntology is a digital resource to support interoperability of battery
data.
The EMMO Battery Domain Ontology is a semantic resource for the terms and relations needed to describe things, processes, and data in the battery 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!

BattINFO consists of a list of entities representing concepts used in batteries and electrochemistry. Each entity has a
unique identifier (IRI) and is annotated with additional information, such as its preferred name ("prefLabel"),
alternative names, definition, references, etc. As users link their research resources to BattINFO entities, they are
effectively describing their resource using a common vocabulary. Resources can be datasets, documents, persons,
organizations, equipment, samples... anything linked to the common vocabulary described in BattINFO, becomes part of an
ecosystem of Findable resources.
The Battery Ontology is intended to support researchers, engineers, and developers within the electrochemical
communitiy with activities like:

Here you can find the entities described in BattINFO, classified in two domains.
- 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 guidelines <FAIR.md>`__.

* `Battery Domain <https://w3id.org/emmo/domain/battery>`__
* `Electrochemistry Domain <https://w3id.org/emmo/domain/electrochemistry>`__
* `Chemical Substance Domain <https://w3id.org/emmo/domain/chemicalsubstance>`__
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 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:

#. `Public IEC/ISO standard vocabulary <https://www.electropedia.org/>`__ The IEC is the the world’s leading organization that prepares and publishes International Standards for all electrical, electronic and related technologies.
#. `IUPAC Goldbook <https://iupac.org/what-we-do/nomenclature/>`__. IUPAC is the universally-recognized authority on chemical nomenclature and terminology.
#. Pre-eminent domain textbooks (e.g. `Bard <https://www.wiley.com/en-kr/Electrochemical+Methods:+Fundamentals+and+Applications,+2nd+Edition-p-9780471043720>`__, `Newman <https://www.wiley.com/en-no/Electrochemical+Systems,+4th+Edition-p->`__, 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 <https://www.dbpedia.org/>`__
#. `WikiData <https://www.wikidata.org/>`__
#. `Wikipedia <https://www.wikipedia.org/>`__

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 <https://github.com/emmo-repo/domain-chemical-substance>`__: provides material annotations for electrochemical (meta)data.

The import structure is summarized in the following table:

.. list-table::
:header-rows: 1

* - **Imported Ontologies**
- **Version**
* - EMMO
- 1.0.0-beta5
* - chemical-substance
- 0.2.0-alpha

The onotlogy exists in two forms: (i) the asserted source files and (ii) the pre-inferred version.

The asserted source consists of two files: - ``battery.ttl``: describes terms and object properties for the electrochemistry domain. - ``batteryquantities.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.

The pre-inferred ontology runs the reasoner on the source files and their imports and complies them into a `pre-inferred ontology file <inferred_version/battery-inferred.ttl>`__. 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:

- 957189 - `BIG-MAP <http://www.big-map.eu/>`__

License
-------

The Battery Interface Domain Ontology is released under the `Creative Commons Attribution 4.0 International <https://creativecommons.org/licenses/by/4.0/legalcode>`__ license (CC BY 4.0).
39 changes: 39 additions & 0 deletions sphinx/example_alkaline_electrochemical_cell.rst
View file
Original file line number Diff line number Diff line change
@@ -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

<div style="position: relative; padding-top: 56.25%; height: 0;">
<iframe src="https://json-ld.org/playground/#startTab=tab-table&json-ld=%7B%22%40context%22%3A%22https%3A%2F%2Fraw.githubusercontent.com%2Femmo-repo%2Fdomain-electrochemistry%2Fmaster%2Fcontext.json%22%2C%22%40type%22%3A%22ElectrochemicalCell%22%2C%22hasNegativeElectrode%22%3A%7B%22%40type%22%3A%22ZincElectrode%22%7D%2C%22hasPositiveElectrode%22%3A%7B%22%40type%22%3A%22ManganeseDioxideElectrode%22%7D%2C%22hasElectrolyte%22%3A%7B%22%40type%22%3A%22AlkalineElectrolyte%22%7D%7D" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" frameborder="0" allowfullscreen></iframe>
</div>
65 changes: 65 additions & 0 deletions sphinx/example_aqueous_electrolyte_KOH.rst
View file
Original file line number Diff line number Diff line change
@@ -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

<div style="position: relative; padding-top: 56.25%; height: 0;">
<iframe src="https://json-ld.org/playground/#startTab=tab-table&json-ld=%7B%22%40context%22%3A%22https%3A%2F%2Fraw.githubusercontent.com%2Femmo-repo%2Fdomain-electrochemistry%2Fmaster%2Fcontext.json%22%2C%22%40type%22%3A%22Electrolyte%22%2C%22hasSolvent%22%3A%7B%22%40type%22%3A%22Water%22%7D%2C%22hasSolute%22%3A%7B%22%40type%22%3A%22PotassiumHydroxide%22%2C%22hasProperty%22%3A%7B%22%40type%22%3A%5B%22AmountConcentration%22%2C%22ModelledProperty%22%5D%2C%22hasNumericalPart%22%3A%7B%22%40type%22%3A%22Real%22%2C%22hasNumericalValue%22%3A7%7D%2C%22hasMeasurementUnit%22%3A%22emmo%3AMolePerLitre%22%7D%7D%2C%22hasProperty%22%3A%5B%7B%22%40type%22%3A%5B%22Density%22%2C%22MeasuredProperty%22%5D%2C%22hasNumericalPart%22%3A%7B%22%40type%22%3A%22Real%22%2C%22hasNumericalValue%22%3A1.289%7D%2C%22hasMeasurementUnit%22%3A%22emmo%3AKilogramPerLitre%22%7D%2C%7B%22%40type%22%3A%5B%22IonicConductivity%22%2C%22MeasuredProperty%22%5D%2C%22hasNumericalPart%22%3A%7B%22%40type%22%3A%22Real%22%2C%22hasNumericalValue%22%3A65%7D%2C%22hasMeasurementUnit%22%3A%22emmo%3ASiemensPerCentiMetre%22%7D%5D%7D" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" frameborder="0" allowfullscreen></iframe>
</div>

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.

90 changes: 90 additions & 0 deletions sphinx/example_cyclic_voltammetry.rst
View file
Original file line number Diff line number Diff line change
@@ -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 <https://raw.githubusercontent.com/emmo-repo/domain-electrochemistry/master/sphinx/assets/data/example-cyclic-voltammetry.csv>`__.

.. 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

<div style="position: relative; padding-top: 56.25%; height: 0;">
<iframe src="https://json-ld.org/playground/#startTab=tab-canonized&json-ld=%7B%22%40context%22%3A%22https%3A%2F%2Fraw.githubusercontent.com%2Femmo-repo%2Fdomain-electrochemistry%2Fmaster%2Fcontext.json%22%2C%22%40type%22%3A%22MeasurementResult%22%2C%22dc%3Atitle%22%3A%22Example%20Cyclic%20Voltammetry%20Data%22%2C%22dcat%3Akeyword%22%3A%5B%22cyclic%20voltammetry%22%2C%22LNO%22%2C%22battery%22%5D%2C%22dc%3Alicense%22%3A%22BIG-MAP%20Archive%20License%22%2C%22dc%3Amodified%22%3A%7B%22%40value%22%3A%222024-01-29%22%2C%22%40type%22%3A%22xsd%3Adate%22%7D%2C%22dc%3Acreator%22%3A%7B%22%40id%22%3A%22https%3A%2F%2Forcid.org%2F0000-0002-9401-1362%22%2C%22schema%3Aname%22%3A%22Christian%20Wolke%22%7D%2C%22dc%3Acontributor%22%3A%7B%22%40id%22%3A%22https%3A%2F%2Forcid.org%2F0000-0002-8758-6109%22%2C%22schema%3Aname%22%3A%22Simon%20Clark%22%7D%2C%22%40reverse%22%3A%7B%22hasOutput%22%3A%7B%22%40type%22%3A%22CyclicVoltammetry%22%7D%7D%2C%22csvw%3AtableSchema%22%3A%7B%22csvw%3Acolumns%22%3A%5B%7B%22csvw%3Aname%22%3A%22potential%22%2C%22csvw%3Atitles%22%3A%22Potential%20vs.%20Li%22%2C%22csvw%3ApropertyUrl%22%3A%22ElectricPotential%22%2C%22hasMeasurementUnit%22%3A%22emmo%3AMilliVolt%22%2C%22csvw%3Adatatype%22%3A%22number%22%2C%22csvw%3Arequired%22%3Atrue%7D%2C%7B%22csvw%3Aname%22%3A%22current%22%2C%22csvw%3Atitles%22%3A%22I%22%2C%22csvw%3ApropertyUrl%22%3A%22ElectricCurrent%22%2C%22hasMeasurementUnit%22%3A%22emmo%3AMilliAmpere%22%2C%22csvw%3Adatatype%22%3A%22number%22%7D%2C%7B%22csvw%3Aname%22%3A%22current%20density%22%2C%22csvw%3Atitles%22%3A%22Current%20density%22%2C%22csvw%3ApropertyUrl%22%3A%22ElectricCurrentDensity%22%2C%22hasMeasurementUnit%22%3A%22emmo%3AMilliAmperePerSquareCentiMetre%22%2C%22csvw%3Adatatype%22%3A%22number%22%7D%5D%2C%22csvw%3AprimaryKey%22%3A%22potential%22%7D%7D" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" frameborder="0" allowfullscreen></iframe>
</div>

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.

Loading

0 comments on commit 38dd05c

Please sign in to comment.