FAIRmaterials

What is FAIRmaterials and what does it do?

'FAIRmaterials' is a bilingual package in R and Python that translates several CSV files from the template (described below) with ontological terms and corresponding data into RDF triples. These RDF triples are then stored in OWL and JSON-LD files, facilitating data accessibility, interoperability, and knowledge unification. The triples are also visualized in a graph saved as an SVG or as a PNG with the Python package. The Python package has a fourth output too. It generates documentation for the output ontology as an HTML.

Put the sheets, created from the template (described below), for one or more ontologies in a folder and the 'FAIRmaterials' 'process_ontology_files' or 'FAIRSheetParser' function will output a JSON-LD, turtle/OWL, SVG/PNG visualization, and HTML documentation into the input folder for all the input ontologies merged. Note that a folder containing only files for one ontology will give results for just that ontology and specifying a base uri is required for merging ontologies. The package can handle subdirectories by producing separate unmerged outputs for each subdirectory and a merged output from all files in the input path. This tool, developed for use by the SDLE Research Center at Case Western Reserve University, facilitates the creation and visualization of material science ontologies.

Statement of need

Protege is currently the most widely-used open-source tool for ontology creation and development. Its main capabilities include manually creating and editing ontological terms and relationships, visualizing ontologies, checking the logical consistency of ontologies, and querying ontologies for specific information. Unfortunately, the complexity of the interface is a barrier for those who have little experience with ontology creation. Another well-known software is Owlready2, a package for manipulating ontologies in Python. This package allows for manipulation of classes, instances, and annotations, as well as reasoning using a HermiT reasoner [@HermiT]. However, like Protege, Owlready2 is complex to use, requiring users to have extensive knowledge about OWL and Description Logics. This complexity prevents many researchers from creating and integrating ontologies with their own datasets entirely. Therefore, there is a need for a tool that can create ontologies with an interface that is easily understandable and provides ample documentation on how to use it. FAIRmaterials seeks to lower the barrier of entry for scientists entering the world of ontology development and evolution. The package provides a baseline CSV ontology template with built-in and easy-to-follow instructions on how to design an ontology which can be found here.

How to use the FAIR CSV template

To prepare your CSV file, ensure your CSV file contains the appropriate ontological terms and corresponding data using this template: FAIR CSV Template

The template has documention on its use. The descriptions under the column names provide instructions for how to fill out each column. Once the Name Space, Value Type Definitions, Relationship Definitions, Variable Definitions, and Ontology Info sheets are filled out, 'FAIRmaterials' is ready to use. The visualizations generated by this package are helpful to visualize an ontology to ensure satisfaction with the information in the sheets.

Location of worked example for XRD Sample Ontology

The location of the XRD worked example can be found here.

Example of XRay ontology FAIR CSV sheet

Example Name Space Sheet:

Example Ontology Information Sheet:

Example Variable Definitions Sheet:

Example Relationship Definitions Sheet:

Example Value Type Definitions Sheet:

The descriptions under the column names provide instructions for how to fill out each column. Once the Name Space, Value Type Definitions, Relationship Definitions, Variable Definitions, and Ontology Info sheets are filled out, 'FAIRmaterials' is ready to use. The visualizations generated by this package are helpful to visualize an ontology to ensure satisfaction with the information in the sheets.

Location of worked example for PV Module Ontology

The location of the PV Module worked example can be found here.

Python and R Version

FAIRmaterials Python requires Python 3.10 and up and FAIRmaterials R requires R 3.1.1 and up.

Install and load the package

Install in R:

install.packages("FAIRmaterials")

library(FAIRmaterials)

Install in Python:

pip install FAIRmaterials

Running the default 'process_ontology_files' function

PV ontology sheets

Running the package in R:

# Process the CSV files in the PV folder
example_folder1 <- system.file("extdata", "PV", package = "FAIRmaterials")
FAIRmaterials::process_ontology_files(example_folder1, add_external_onto_info = FALSE)

This visualization from the R package will be saved in the output folder as an SVG:

Running the package in Python:

FAIRmaterials --folder_path /path/to/csv/files --include_graph_valuetype --include_pylode_docs

This visualization from the Python package will be saved in the output folder as an PNG:

HTML output

The HTML output generated by the Python package for PV Module can be found here.

XRay Sample ontology sheets

Running the package in R:

# Process the CSV files in the Xray folder
example_folder2 <- system.file("extdata", "XRay", package = "FAIRmaterials")
FAIRmaterials::process_ontology_files(example_folder2, add_external_onto_info = FALSE)

This visualization from the R package will be saved in the output folder as an SVG:

Running the package in Python:

# Process the CSV files in the Xray folder
FAIRmaterials --folder_path /path/to/csv/files --include_graph_valuetype --include_pylode_docs

This visualization from the Python package will be saved in the output folder as an PNG:

HTML output

The HTML output generated by the Python package for XRay Sample can be found here.

Removing values from visualization in R

By setting include_graph_valuetype argument to FALSE the valuetypes are excluded from graph. We can see how this graph differs from the PV graph above.

Removing values in R:

FAIRmaterials::process_ontology_files(example_folder1, include_graph_valuetype = FALSE, add_external_onto_info = FALSE)

Removing values from visualization in Python

By removing the --include_graph_valuetype flag, the valuetypes are excluded from graph. We can see how this graph differs from the PV graph above.

Removing values in Python:

FAIRmaterials --folder_path /path/to/csv/files

This visualization from the Python package will be saved in the output folder as a PNG:

Attempting to add external ontology information in R

Now we set the add_external_onto_info argument to TRUE. The package attempts to find additional information for every term in the XRay Sample and PV Module data and update the output.

For PV Module

Adding external ontology information in R:

FAIRmaterials::process_ontology_files(example_folder1, include_graph_valuetype = TRUE, add_external_onto_info = TRUE)

For XRay Sample

Adding external ontology information in R:

FAIRmaterials::process_ontology_files(example_folder2, include_graph_valuetype = TRUE, add_external_onto_info = TRUE)

Attempting to add external ontology information in Python

Now we include the --add_external_onto_info flag when using the package. The package attempts to find additional information for every term in the XRay Sample and PV Module data and update the output.

For PV Module

Adding external ontology information in Python:

FAIRmaterials --folder_path /path/to/csv/files --include_graph_valuetype --add_external_onto_info

For XRay Sample

Adding external ontology information in R:

FAIRmaterials::process_ontology_files(example_folder2, include_graph_valuetype = TRUE, add_external_onto_info = TRUE)

Merging two ontologies and specifying some of the metadata

Lastly we will merge the PV and XRay on