Update docs

Author: Tanmay2028

.cspell/custom-dictionary.txt

@@ -14,6 +14,7 @@ Downsampled
 Draxl
 ELECTRONANALYZER
 ESRFET
+ESRF
 Emminger
 Florian
 Forschungsgemeinschaft
@@ -60,7 +61,9 @@ Sandor
 Scheidgen
 Shabih
 Sherjeel
+submoduling
 Tommaso
+testdata
 UNALLOWED
 Uniquified
 Uniquifies

docs/assets/entry_definition__field.png

@@ -1,37 +1,35 @@
-# How to use the ontology service in pynxtools
+# Using ontology service in pynxtools
 
-## Overview
-
-The ontology service in `pynxtools` provides a FastAPI-based app for querying NeXus ontology integrated with ESRFET and PaNET. It enables users to retrieve ontological information, such as superclasses for NeXus Application definitions and makes datasets of different experimental techniques based on PaNET ontology findable in NOMAD.
+!!! info "This is a how-to guide for using the ontology service. If you want to learn more about how `ontology service` works in `pynxtools`, please visit the [explanation](../../learn/pynxtools/ontology-service.md) "
 
 ## Prerequisites
 
-- Python 3.8+
+- Python 3.10+
 - Install required packages:
-  - `pynxtools` and its dependencies (see [`pyproject.toml`](../../../pyproject.toml))
+  - `pynxtools` and its dependencies (see [`pyproject.toml`](https://github.com/FAIRmat-NFDI/pynxtools/blob/master/pyproject.toml))
   - `owlready2`, `pygit2`, `fastapi`, `uvicorn`
-- Ensure the NeXusOntology and definitions submodule are present in the repository, typically at [`src/pynxtools/NeXusOntology`](../../../src/pynxtools/NeXusOntology/) and [`src/pynxtools/definitions`](../../../src/pynxtools/definitions/) respectively.
+- Ensure the NeXusOntology and definitions submodules are initialized (see [Development guide](../../tutorial/contributing.md#development-installation)).
 
 ## Getting Started
 
 ### Importing and Using the Service
 
-The main entry point is the FastAPI app defined in [`pynxtools.nomad.apis.ontology_service`](../../../src/pynxtools//nomad/apis/ontology_service.py). You can import and use the service as follows:
+The main entry point is the FastAPI app defined in [`pynxtools.nomad.apis.ontology_service`](https://github.com/FAIRmat-NFDI/pynxtools/blob/ontology-service/src/pynxtools/nomad/apis/ontology_service.py). You can import and use the service as follows:
 
 ```python
 from pynxtools.nomad.apis.ontology_service import app, load_ontology, fetch_superclasses
 ```
 
 ### Minimal Working Example
 
-You can extract superclasses for a NeXus class using the ontology service's HTTP API endpoint. For example, using Python's `requests` library:
+You can extract superclasses for a NeXus class using the ontology service's HTTP API endpoint. Here's an example using Python's `requests` library:
 
 ```python
 import requests
 
 # Replace with the actual running service URL
 base_url = "http://localhost:8000/nomad-oasis/"
-class_name = "NXiv_temp"
+class_name = "NXmpes_arpes"
 response = requests.get(f"{base_url}/superclasses/{class_name}")
 if response.status_code == 200:
   superclasses = response.json().get("superclasses", [])
@@ -40,8 +38,22 @@ else:
   print(f"Error: {response.status_code} - {response.text}")
 ```
 
-This endpoint returns a JSON object with the list of superclasses for the given NeXus class name, as used internally in [pynxtools](../../../src/pynxtools/nomad/schema.py)
+This endpoint returns a JSON object with the list of superclasses for the given NeXus class name, as used internally in [pynxtools](https://github.com/FAIRmat-NFDI/pynxtools/blob/ontology-service/src/pynxtools/nomad/schema.py)
+
+## How it works in NOMAD
+
+When you upload a NeXus file to NOMAD, the ontology service is automatically triggered during data processing. Here's what happens:
+
+1. **Triggering**: During normalization, NOMAD reads the `definition__field` from NeXus entry (e.g., `NXmpes_arpes`).
+
+![Processing NeXus files in NOMAD](../../assets/ontology-service-trigger.png){ width="800" }
+![Reading definition field](../../assets/entry_definition__field.png){ width="800" }
+
+2. **Querying**: The service loads the ontology (or generates it if not already present) and retrieves all superclasses for that application definition.
+
+3. **Storing results**: The retrieved superclasses are stored in `results.eln.methods` in the NOMAD archive.
 
-### Further Reading
+![Ontology results in NOMAD](../../assets/superclasses_results.png){ width="800" }
 
-- [Learn: Understanding the ontology service in pynxtools](../../learn/pynxtools/ontology-service.md)
+!!! info "Further Reading"
+    - [Learn: Understanding the ontology service in pynxtools](../../learn/pynxtools/ontology-service.md)

docs/assets/ontology-service-trigger.png

@@ -50,6 +50,7 @@ We are offering a small guide to getting started with NeXus, `pynxtools`, and NO
 - [Running `pynxtools` tests in parallel](how-tos/pynxtools/run-tests-in-parallel.md)
 - [Using Python to create NeXus files](how-tos/pynxtools/create-nexus-files-by-python.md)
 - [Validation of NeXus files](how-tos/pynxtools/validate-nexus-files.md)
+- [Use ontology service](how-tos/pynxtools/ontology-service.md)
 
 </div>
 
@@ -68,6 +69,7 @@ We are offering a small guide to getting started with NeXus, `pynxtools`, and NO
 - [Data conversion in `pynxtools`](learn/pynxtools/dataconverter-and-readers.md)
 - [Validation of NeXus files](learn/pynxtools/nexus-validation.md)
 - [The `MultiFormatReader` as a reader superclass](learn/pynxtools/multi-format-reader.md)
+- [Introduction to ontology service](learn/pynxtools/ontology-service.md)
 
 </div>
 <div markdown="block">

docs/assets/superclasses_results.png

@@ -1,17 +1,27 @@
 # Understanding the ontology service in pynxtools
 
+!!! info "This is a learn guide for using the ontology service. If you want to learn more about how to use `ontology service` in `pynxtools`, please visit the [explanation](../../how-tos/pynxtools/ontology-service.md) "
+
 ## Introduction
 
-The ontology service in `pynxtools` addresses the need for structured, semantic search of NeXus Application definitions and their relationships to ESRFET and PaNET, within NOMAD. It enables querying, reasoning of ontologies, supporting FAIR data principles in scientific workflows.
+The ontology service in `pynxtools` provides a FastAPI-based app for querying the [NeXus ontology](https://github.com/nexusformat/NeXusOntology). This service enables users to retrieve ontological information—such as superclasses for NeXus application definitions—and makes datasets of different experimental techniques findable in NOMAD.
+
+The NeXus ontology integrates two key experimental technique ontologies:
+
+- **[PaN Experimental Technique Ontology (PaNET)](https://bioportal.bioontology.org/ontologies/PANET)**: Photon and Neutron Experimental Techniques ontology (PaNET) provides a standardized vocabulary for describing experimental techniques used at photon and neutron research facilities, enabling consistent categorization and discovery of scientific data across different institutions.
+
+- **ESRF Experimental Technique Ontology (ESRFET)**: An ontology developed by the European Synchrotron Radiation Facility (ESRF) to classify and describe experimental techniques specific to synchrotron radiation science. It complements PaNET by providing more granular terms for synchrotron-based methods.
+
+By using these ontologies, the service maps NeXus application definitions to standardized experimental technique terms, improving data interoperability and enabling semantic search capabilities within NOMAD.
 
-## How It Fits in pynxtools
+## How it fits in pynxtools
 
-This service operates within the `nomad` integration layer, exposing ontological data for NeXus Application definitions through a FastAPI interface. It works by accessing ontology files, leveraging NOMAD configuration, and processing NeXus definitions to provide semantic tools and data to users and connected systems.
+This service only operates when `pynxtools` is run within `NOMAD`, exposing ontological data for NeXus Application definitions through a FastAPI interface. It uses NOMAD's configuration to set up the API base path and plugin entry points, then processes NeXus definitions to provide semantic data to users and connected systems.
 
 ## Core Concepts
 
-- **Ontology**: A formal representation of concepts (classes), relationships, and properties, typically serialized as OWL files.
-- **Application definition**: A class or term describing an experimental technique in the NeXus (e.g., `NXiv_temp`).
+- **Ontology**: A formal representation of concepts (classes), relationships, and properties, typically serialized as [OWL](https://www.w3.org/OWL/) files.
+- **Application definition**: A class or term describing an experimental technique in the NeXus (e.g., `NXmpes_arpes`).
 - **Relation**: Connections between entities, such as superclass/subclass relationships.
 - **Inferred ontology**: An ontology file that has been processed by a reasoner to infer additional relationships and properties between classes, beyond those explicitly defined. 
 
@@ -43,7 +53,7 @@ import requests
 
 # Replace with the actual running service URL
 base_url = "http://localhost:8000/nomad-oasis/"
-class_name = "NXiv_temp"
+class_name = "NXmpes_arpes"
 response = requests.get(f"{base_url}/superclasses/{class_name}")
 if response.status_code == 200:
   superclasses = response.json().get("superclasses", [])

docs/how-tos/pynxtools/ontology-service.md

@@ -60,10 +60,11 @@ git submodule update --init --recursive --jobs=4
 
 Note that we are using the NeXus definitions as a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). The last two lines initiate the submodule and upgrade it to match the first used in pynxtools.
 
-For NeXusOntology submodule [NeXusOntology](../../src/pynxtools/NeXusOntology/) we use the sparse checkout
+In addition, for the [ontology service](../learn/pynxtools/ontology-service.md), we are submoduling the [NeXusOntology](https://github.com/FAIRmat-NFDI/NeXusOntology/tree/oscars-project). Here, it is recommended to use the sparse checkout:
+
 ```bash
 git sparse-checkout init --no-cone
-git sparse-checkout set "/*" '!ontology/NeXusOntology.owl' '!ontology/NeXusOntology_full.owl'
+git sparse-checkout set "/*" '!ontology/NeXusOntology.owl' '!ontology/NeXusOntology_full.owl' '!ontology/NeXusOntology_full_testdata.owl'
 ```
 
 Next, we install the package in editable mode (together with its dependencies):

docs/index.md

@@ -25,6 +25,7 @@ nav:
       - how-tos/pynxtools/run-tests-in-parallel.md
       - how-tos/pynxtools/create-nexus-files-by-python.md
       - how-tos/pynxtools/validate-nexus-files.md
+      - how-tos/pynxtools/ontology-service.md
   - Learn:
     - NeXus:
       - learn/nexus/nexus-primer.md
@@ -34,6 +35,7 @@ nav:
       - learn/pynxtools/dataconverter-and-readers.md
       - learn/pynxtools/nexus-validation.md
       - learn/pynxtools/multi-format-reader.md
+      - learn/pynxtools/ontology-service.md
   - Reference:
     - reference/definitions.md
     - reference/cli-api.md