Merge pull request #63 from emmo-repo/dev

update README

FAIR.md

@@ -0,0 +1,3 @@
+# Guidelines for generating FAIR data
+
+TBC

README.md

@@ -5,46 +5,94 @@
 # Electrochemistry Domain Ontology
 
 <!-- [![CI tests](https://github.com/emmo-repo/domain-electrochemistry/workflows/CI%20tests/badge.svg)](https://github.com/emmo-repo/domain-electrochemistry/actions/) -->
-The Electrochemistry Domain Ontology, a specialized domain within the Elementary Multiperspective Materials Ontology [(EMMO)][1], encompasses essential terms and relationships for electrochemical 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 electrochemistry. This ontology serves as a foundational resource for harmonizing electrochemical knowledge representation, enhancing data interoperability, and accelerating progress in electrochemical research and development.
+The Electrochemistry Domain Ontology is a specialized domain within the Elementary Multiperspective Materials Ontology [(EMMO)][1], that encompasses essential terms and relationships for electrochemical 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 electrochemistry. This ontology serves as a foundational resource for harmonizing electrochemical knowledge representation, enhancing data interoperability, and accelerating progress in electrochemical research and development.
 
 A reference documentation is available in [html](https://emmo-repo.github.io/domain-electrochemistry/index.html) and [pdf](https://emmo-repo.github.io/domain-electrochemistry/electrochemistry.pdf) formats.
 
-## Integration with EMMO
+### Persistent Identifiers
 
-The Electrochemistry Domain Ontology is an official domain on the EMMO. It consists of two files:
+This ontology assigns persistent machine-readable identifiers to concepts from the electrochemistry 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/). 
+
+### Standardized Nomenclature
+
+The ontology builds on standardized nomenclature for electrochemistry, 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 electorchemical systems, devices, methods, datasets, and quantities.
+- Standardized nomenclature for electrochemical entities.
+- Facilitates data exchange and interoperability within the EMMO ecosystem.
+
+## Usage
+
+Researchers, domain experts, and developers within the electrochemical 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 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))
+
+## Structure and Integration with EMMO
+
+The Electrochemistry Domain Ontology is an official domain on the EMMO. The asserted source consists of two files:
 - `electrochemistry.ttl`: describes terms and object properties for the electrochemistry domain.
 - `electrochemicalquantities.ttl`: describes the physical 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 electrochemistry domain also imports:
-- the [Chemical Substance Domain Ontology](https://github.com/emmo-repo/domain-chemical-substance): provides material annotations for electrochemical (meta)data.
+The electrochemistry domain also imports other EMMO domains:
+- [Chemical Substance Domain Ontology](https://github.com/emmo-repo/domain-chemical-substance): provides material annotations for electrochemical (meta)data.
 
-## Obtaining the ontology
+The import structure is summarized in the following table:
+| Imported Ontologies | Version           |
+| ------------------- | ----------------- |
+| EMMO                | 1.0.0-beta5       |
+| chemical-substance  | 0.2.0-alpha       |
 
-The correct path to the inferred verion `emmo-inferred` is specified in the catalog file, [`catalog-v001.xml`](catalog-v001.xml).
+For simplicity, we complie the source files and other imports into a [pre-inferred ontology](inferred_version/electrochemistry-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. 
 
-The domain ontology is obtained with:
+## Getting Started
 
-```console
-git clone https://github.com/emmo-repo/domain-electrochemistry.git
-```
+### 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)
+  - Installation instructions are available [here](https://protege.stanford.edu/software.php#desktop-protege).
+
+- [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).
 
-When opening electrochemistry.ttl in Protégé, the correct versions of EMMO and other ontology dependencies will be downloaded and imported.
+- [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).
 
-In [EMMOntoPy](https://github.com/emmo-repo/EMMOntoPy), correct import is obtained with:
+### Quick Start
+
+To quickly explore and make use of the ontology, first download the pre-inferred version [pre-inferred ontology](inferred_version/electrochemistry-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:
 
 ```python
 from ontopy import get_ontology
 
 # Loading from local repository
-electrochemistry = get_ontology('/path/to/domain-electrochemistry/electrochemistry.ttl').load(url_from_catalog=True)
+electrochemistry = get_ontology('/path/to/domain-electrochemistry/electrochemistry-inferred.ttl').load(url_from_catalog=True)
 
 # Loading from web
-electrochemistry = get_ontology('https://raw.githubusercontent.com/emmo-repo/domain-electrochemistry/master/electrochemistry.ttl').load()
+electrochemistry = get_ontology('https://raw.githubusercontent.com/emmo-repo/domain-electrochemistry/master/inferred_version/electrochemistry-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 [Contribution Guidelines](CONTRIBUTING.md).
+
 ### Acknowledgements
 
-<img src="documentation/images/flag_of_europe.png" alt="EU-Flag" width="100">
+<img src="docs/assets/images/flag_of_europe.png" alt="EU-Flag" width="100">
 
 This project has received support from European Union research and innovation programs, under grant agreement numbers: