Merge branch 'main' into 86-add-absorbance

.github/workflows/qc.yml

@@ -19,7 +19,7 @@ jobs:
   ontology_qc:
     # The type of runner that the job will run on
     runs-on: ubuntu-latest
-    container: obolibrary/odkfull:v1.4
+    container: obolibrary/odkfull:v1.4.3
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:

.gitignore

@@ -41,3 +41,5 @@ pyproject.toml
 poetry.lock
 .idea/*
 src/templates/.~lock.vibso_classes.tsv\#
+docs/images/.$VIBSO_T-Box_graph_views.drawio.bkp
+*.dtmp

README.md

@@ -1,5 +1,5 @@
 [![License: CC-BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-green.svg)](https://creativecommons.org/licenses/by/4.0/) 
-![Build Status](https://github.com/NFDI4Chem/VibrationSpectroscopyOntology/workflows/CI/badge.svg)
+[![CI](https://github.com/NFDI4Chem/VibrationalSpectroscopyOntology/actions/workflows/qc.yml/badge.svg)](https://github.com/NFDI4Chem/VibrationalSpectroscopyOntology/actions/workflows/qc.yml)
 # Vibrational Spectroscopy Ontology
 
 _Work In Progress - NOT READY FOR PRODUCTION!_

docs/contributing.md

@@ -7,6 +7,5 @@ There are different ways in which you can help:
 
 * [Open up a new issue](https://github.com/NFDI4Chem/VibrationalSpectroscopyOntology/issues/new/choose): For any kind of contributions we rely on the GitHub infrastructure for documentation. Thus, it is always preferred that you use one of our issue templates to let us know what needs to be done and how you might plan on contributing, before working on a pull request (PR). (However, feel free to do a quick PR patch for any typos off course.)
     * Use [this template](https://github.com/NFDI4Chem/VibrationalSpectroscopyOntology/issues/new?assignees=&labels=&template=bug_report.md&title=) to file bugs within the ontology or its CI/CD pipeline,
-    * [this one](https://github.com/NFDI4Chem/VibrationalSpectroscopyOntology/issues/new?assignees=&labels=New+Term+Request&template=new-term-request-issue-template.md&title=%5BNTR%5D) to make a new term request,
+    * [this one](https://github.com/NFDI4Chem/VibrationalSpectroscopyOntology/issues/new?assignees=&labels=New+Term+Request&template=new-term-request-issue-template.md&title=%5BNTR%5D) to make a new term request (but please read the [How to add new terms to VIBSO section](ntr_workflow.md)  first),
     * or [this one](https://github.com/NFDI4Chem/VibrationalSpectroscopyOntology/issues/new?assignees=&labels=documentation&template=documentation-related-issue.md&title=%5BDocs%5D) to help us improve this documentation and ask questions about VIBSO.
-* [Add new terms to VIBSO](ntr_workflow.md).

docs/design_patterns.md

@@ -1,22 +1,55 @@
 # Design Patterns & Decisions
 
-**This page is still a stub and will be updated regularly in the iterative development of VIBSO to document modeling decisions and design patterns.**
+**This page will be updated regularly in the iterative development of VIBSO to document modeling decisions and design patterns.**
 
-Following best practices in ontology development, we will reuse well established design patterns whenever possible.
+Following best practices in ontology development, we will reuse established design patterns whenever possible. Since most ontologies we reuse are OBO Foundry based, we also reuse their design patterns to be logically sound and interoperable. Some of these patterns are provided in the logical definitions of the reused classes in form of asserted `rdfs:subclassOf` or `rdfs:equivalentTo` axioms. Others are only implicitly provided in the textual definitions of the reused terms and the domain and range restrictions of suitable OBO relations.
 
-## Planned Process Pattern
- OBI's way of modeling [data and values](https://github.com/obi-ontology/obi/wiki/Data-and-Values) is a very prominent pattern in many OBO ontologies and thus one we also use. Please read their documentation in order to understand how we model values and data. Here is an illustrative example graphic from that documentation:  ![measurement process pattern example](images/data_john_mass.png) Using this OBI pattern allows us to differentiate data values of qualities (aka attributes) of a material entity, such as the spectroscope or sample, into data values that represent settings and those that represent measurements. From a data repository use case perspective, we might not need this fine-grained approach and defining qualities/attributes and their value specifications might suffice. Yet in order to allow the integration of VIBSO in Electronic Lab Notebooks, such a differentiation will most likely be very useful.
+## VIBSO TBox
 
-Lars Vogt and Tobias Kuhn demonstrate the use of this pattern within a grander research context as follows (cited from their preprint [DOI:10.13140/RG.2.2.13742.59203](http://doi.org/10.13140/RG.2.2.13742.59203), p.8):
-![measurement process pattern example](images/Fig4_10.13140_RG.2.2.13742.59203.png)
+Here you can see VIBSO's current terminology box that focuses on vibrational Raman spectroscopy and which also shows how VIBSO depends on reusing existing ontology classes, relations and design patterns.
 
- > Figure 3: A detailed machine-actionable representation of the metadata relating to a weight measurement datum documented as an RDF ABox graph. The representation takes the form of an ABox semantic graph following the RDF syntax. The graph documents a mass measurement process using a balance. It relates an instance of mass measurement assay (OBI:0000445) with instances of various other classes from different ontologies, specifying who conducted the measurement, where and when it took place, following which protocol and using which device (i.e., balance). The graph furthermore specifies the particular material entity that served as subject and thus as input of the measurement process (i.e., ‘objectX’), and it specifies the data that is the output of the observation, which is contained in a particular weight measurement assertion.
+![Raman spectroscopy terminology box](images/VIBSO_Raman_Tbox.png)
 
+This TBox is supposed to be updated iteratively whenever a new term is being discussed for inclusion. We hope that it might be easier for domain experts to define technical terms in this ontological framework by adding them here first.
 
-## Vibrational Raman Spectroscopy
+A higher resolution HTML version with links to the used terms in the NFDI4Chem Terminology Service can be found [here](images/VIBSO_TBox_graph_views.html).
 
-Here you can see the first draft of VIBSO's terminology box that focuses on vibrational Raman spectroscopy and which also shows how VIBSO depend on reusing existing ontology classes, relations and design patterns. The initially identified needed terms, depicted here with a red border, were derived from a Raman spectrometer output.
+The source file to edit the TBox with the [draw.io](https://draw.io) app is [here](images/VIBSO_T-Box_graph_views.drawio).
 
-![Raman spectroscopy terminology box](images/VIBSO_Raman_Tbox.png)
+## Assay Pattern
+As the scope of VIBSO covers the definitions of various types of vibrational spectroscopy assays and their specific research information outputs, we need to reuse the class `assay` from the Ontology for Biomedical Investigations (OBI). It is defined as:
+
+     A planned process that has the objective to produce information about a material entity (the evaluant) by examining it.
+
+Along with this textual definition, the logical axioms asserted on this class constitute a core design pattern of OBO based ontologies, which can be represented graphically like this:
+
+![OBI_asserted_assay_pattern](images/OBI_asserted_assay_pattern.png)
+
+## Assay Pattern with Device Settings
+Since we also want to say what kind of devices were used in VIBSO specific assays and how these were set, we extend the assay pattern by importing these classes and relations:
+
+![OBI_asserted_assay_pattern](images/OBO_setting_pattern.png)
+
+## Assay Pattern with Data Transformation, Investigation and Sampling
+To zoom out a bit further, this is the pattern proposed to be able to also express:
+
+* who performed an assay,
+* what kind of data transformations where performed on the data output of an assay,
+* what kind of sampling process was done before the assay,
+* and in which grander investigation process the assay is a part of.
+
+![OBI_asserted_assay_pattern](images/OBO_Investigation_Assay_Pattern.png)
+
+-----
+
+## Measurement Example KG of the Assay Pattern
+Lars Vogt and Tobias Kuhn demonstrate the use of the OBO assay pattern within a grander research context as follows (cited from their preprint [DOI:10.13140/RG.2.2.13742.59203](http://doi.org/10.13140/RG.2.2.13742.59203), p.8):
+![measurement process pattern example](images/Fig4_10.13140_RG.2.2.13742.59203.png)
+
+ > Figure 3: A detailed machine-actionable representation of the metadata relating to a weight measurement datum documented as an RDF ABox graph. The representation takes the form of an ABox semantic graph following the RDF syntax. The graph documents a mass measurement process using a balance. It relates an instance of mass measurement assay (OBI:0000445) with instances of various other classes from different ontologies, specifying who conducted the measurement, where and when it took place, following which protocol and using which device (i.e., balance). The graph furthermore specifies the particular material entity that served as subject and thus as input of the measurement process (i.e., ‘objectX’), and it specifies the data that is the output of the observation, which is contained in a particular weight measurement assertion.
 
-What is needed next are iterative reviews of this draft by domain experts to expand it and to ensure that the [competency questions](competency_questions.md) of VIBSO can be answered. 
+## Quality & Quantity Pattern
+![measurement process pattern example](images/data_john_mass.png)
+ Since we are reusing OBO ontologies and their patterns, we also try to reuse OBI's way of modeling [data and values](https://github.com/obi-ontology/obi/wiki/Data-and-Values). Please read their documentation for more background.
+ Using this OBI pattern allows us to differentiate data values of qualities (aka attributes) of a material entity, such as the spectroscope or sample, into data values that represent settings and those that represent measurements. From a data repository use case perspective, we might not need this fine-grained approach and defining qualities/attributes and their value specifications might suffice. Yet in order to allow the integration of VIBSO in Electronic Lab Notebooks, such a differentiation will most likely be very useful.
+Although this pattern seems to work in many OBO use cases, we need to see, if we have to adjust it for our needs. Other ontologies like QUDT or SIO use slightly different patterns to model qualities and their quantitative representations.

docs/development_approach.md

@@ -29,9 +29,11 @@ In both TSV templates there are the following columns:
 * **term replaced by**: This column should be used to provide the term that replaces a deprecated term. This is important to ensure backwards compatibility.
 
 In the **vibso_classes.tsv**, there is also the column:
+
 * **super class**: This column is to be used to provide the parent of the owl:Class that is being defined. It is fine to use the label of the parent class here instead of its IRI or CURIE, as long as the class is already an [imported term](ntr_workflow.md#importing terms).
 
 In the **vibso_classes.tsv**, there are also the columns:
+
 * **super property**: This column is to be used to provide the parent of the `owl:ObjectProperty` or `owl:DatatypeProperty` that is being defined, via its label.
 * **inverse property**: This column can be used to define the inverse of an `owl:ObjectProperty`, via its label. 
 * **domain**: This column can be used to restrict an `owl:ObjectProperty` in terms of being allowed to be used only on a certain subject.