Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
jsimonclark committed Jan 29, 2024
1 parent 84cad8c commit 022461a
Show file tree
Hide file tree
Showing 12 changed files with 752 additions and 173 deletions.
207 changes: 45 additions & 162 deletions sphinx/about.rst
Original file line number Diff line number Diff line change
@@ -1,92 +1,48 @@
Battery Domain Ontology
=======================

.. raw:: html

<!-- [![CI tests](https://github.com/emmo-repo/domain-battery/workflows/CI%20tests/badge.svg)](https://github.com/emmo-repo/domain-battery/actions/) -->

The Battery Domain Ontology is a specialized domain within the
Elementary Multiperspective Materials Ontology
`(EMMO) <https://github.com/emmo-repo/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 <https://emmo-repo.github.io/domain-battery/index.html>`__ and
`pdf <https://emmo-repo.github.io/domain-battery/battery.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 <https://www.dbpedia.org/>`__ and
`Wikidata <https://www.wikidata.org/>`__.
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 <https://iupac.org/what-we-do/nomenclature/>`__ and the
`IEC <https://www.electropedia.org/>`__. 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 <FAIR.md>`__)
- Complying with `FAIR data guidelines <FAIR.md>`__.

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

Expand All @@ -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 <inferred_version/battery-inferred.ttl>`__. 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é <https://protege.stanford.edu/>`__ (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 <https://protege.stanford.edu/software.php#desktop-protege>`__.
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 <https://github.com/emmo-repo/EMMOntoPy>`__ (python
package for working with EMMO ontologies)

- Installation instructions are available
`here <https://github.com/emmo-repo/EMMOntoPy#installation>`__.

- `RDFLib <https://rdflib.readthedocs.io/en/stable/>`__ (optional,
python package for working with RDF graphs)

- Installation instructions are available
`here <https://rdflib.readthedocs.io/en/stable/gettingstarted.html>`__.

- `VS Studio Code <https://code.visualstudio.com/>`__ (optional, a code
editor with extensions for RDF formats like TTL and JSON-LD)

- Installation instructions are available
`here <https://code.visualstudio.com/download>`__.

Quick Start
~~~~~~~~~~~

To quickly explore and make use of the ontology, first download the
pre-inferred version `pre-inferred
ontology <inferred_version/battery-inferred.ttl>`__. You can then simply
open the file in Protégé and explore its content or load the ontology
into python using EMMOntoPy.

In `EMMOntoPy <https://github.com/emmo-repo/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<contribute:Contributing to the 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/electrochemistry-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:
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).

.. |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 <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
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
Alkaline Electrochemical Cell

Check warning on line 1 in sphinx/example_alkaline_electrochemical_cell.rst

View workflow job for this annotation

GitHub Actions / updatepages

document isn't included in any toctree
=============================

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
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
Aqueous KOH Electrolyte

Check warning on line 1 in sphinx/example_aqueous_electrolyte_KOH.rst

View workflow job for this annotation

GitHub Actions / updatepages

document isn't included in any toctree
=======================

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.

Loading

0 comments on commit 022461a

Please sign in to comment.