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' 'processontologyfiles' 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:

```r install.packages("FAIRmaterials")

library(FAIRmaterials) ```

Install in Python:

{python, eval = FALSE} pip install FAIRmaterials

Running the default 'processontologyfiles' function

PV ontology sheets

Running the package in R:

```r

Process the CSV files in the PV folder

examplefolder1 <- system.file("extdata", "PV", package = "FAIRmaterials") FAIRmaterials::processontologyfiles(examplefolder1, addexternalonto_info = FALSE) ```

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

Running the package in Python:

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:

```r

Process the CSV files in the Xray folder

examplefolder2 <- system.file("extdata", "XRay", package = "FAIRmaterials") FAIRmaterials::processontologyfiles(examplefolder2, addexternalonto_info = FALSE) ```

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

Running the package in Python:

```python

Process the CSV files in the Xray folder

FAIRmaterials --folderpath /path/to/csv/files --includegraphvaluetype --includepylode_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 includegraphvaluetype 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:

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 --includegraphvaluetype flag, the valuetypes are excluded from graph. We can see how this graph differs from the PV graph above.

Removing values in Python:

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 addexternalonto_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:

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:

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 --addexternalonto_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:

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

For XRay Sample

Adding external ontology information in R:

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 ontologies. This is accomplished by providing the function a folder path that contains both the PV and XRay ontology sheets. We can also specify some of the metadata included in the outputs.

Merging ontologies in R:

r example_folder3 <- system.file("extdata", package = "FAIRmaterials") FAIRmaterials::process_ontology_files(example_folder3, add_external_onto_info = FALSE, merge_title = "MergedPVandXRay", merge_base_uri = "https://cwrusdle.bitbucket.io/OntologyFilesOwl/Ontology/", merge_version = "1.0")

This is the visualization for the two ontologies merged. This visualization from the R package will be saved in the output folder as an SVG:

Merging ontologies in Python:

python FAIRmaterials --folder_path /path/to/csv/files/ --merge_title MergedPVandXRay --merge_base_uri https://cwrusdle.bitbucket.io/OntologyFilesOwl/Ontology/ --merge_version 1.0

We are still working on adding visualization functionality for merged ontologies in Python.

Community Guideline

We welcome your ideas! If you find a bug, have an idea for a new feature, or see something that could be improved, please open an issue. Your suggestions help us make this project better for everyone. The GitHub page is only for public-facing purpose.

Acknowledgment

This work was supported by the U.S. Department of Energy’s Office of Energy Efficiency and Renewable Energy (EERE) under Solar Energy Technologies Office (SETO) Agreement Numbers DE-EE0009353 and DE-EE0009347, Department of Energy (National Nuclear Security Administration) under Award Number DE-NA0004104 and Contract number B647887, and U.S. National Science Foundation Award under Award Number 2133576.

| Authors: | Jonathan E. Gordon$^{1}$, Alexander Harding Bradley$^{1}$, Priyan Rajamohan$^{1}$, Nathaniel Hahn$^{1}$, Kiefer Lin$^{1}$, | Arafath Nihar$^{1}$, Hayden Cadwell$^{1}$, Jiana Kambo$^{1}$, Jayvic Jimenez$^{1}$, Kristen J. Hernandez$^{1}$, Hein Htet Aung$^{1}$, | Brian Giera$^{2}$, Weiqi Yu$^{1}$, Mohommad Redad Mehdi$^{1}$, Finley Holt$^{1}$, Quynh Tran$^{1}$, Gabriel Ponon$^{1}$, | Dan Savage$^{3}$, Don Brown$^{3}$, Jarod Kaltenbaugh$^{4}$, Kush Havinal$^{4}$, Nicholas Gray$^{4}$, Max Ligget$^{1}$, | Benjamin G. Pierce$^{1}$, Raymond Wieser$^{1}$, Yangxin Fan$^{1}$, Tommy Ciardi$^{1}$, Olatunde J. Akanbi$^{1}$, Hadiza Iawal$^{1}$, | Will Oltjen$^{1}$, Maliesha Kalutotage$^{1}$, Antony Lino$^{1}$, Van Tran$^{1}$, Mingjian Lu$^{1}$, Xuanji Yu$^{1}$, | Abhishek Daundkar$^{1}$, Hope Omodolor$^{1}$, Mirra Rasmussen$^{1}$, Sameera Nalin-Venkat$^{1}$, Tian Wang$^{1}$, | Rounak Chawla$^{1}$, Liangyi Huang$^{1}$, Zelin Li$^{1}$, Leean Jo$^{1}$, Jeffrey M. Yarus$^{1}$, Mengjie Li$^{4}$, | Kristopher O. Davis$^{4}$, Yinghui Wu$^{1}$, Pawan K. Tripathi$^{1}$, Laura S. Bruckman$^{1}$, Erika I. Barcelos$^{1}$, | Roger H. French$^{1}$ | | $^{1}$ Materials Data Science for Stockpile Stewardship Center of Excellence, Cleveland, OH 44106, USA | $^{2}$ Lawrence Livermore National Laboratory, Livermore, CA 94551, USA | $^{3}$ Los Alamos National Laboratory, Los Alamos, NM 87545, USA | $^{4}$ University of Central Florida, Materials Science & Engineering, Orlando, FL 32816, USA