Metadata-Version: 2.4
Name: FAIRmaterials
Version: 0.4.2.7
Summary: Translates several CSV files with ontological terms and corresponding data into RDF triples. These RDF triples are 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. The input CSVs must be formatted with a template from a public Google Sheet; see README or vignette for more information. This is a tool used by the SDLE Research Center at Case Western Reserve University.
Author: Alexander Harding Bradley, Priyan Rajamohan, Jonathan E. Gordon, Nathaniel Hahn, Kiefer Lin, Arafath Nihar, Hayden Cadwell, Jiana Kambo, Jayvic Jimenez, Kristen J. Hernandez, Hein Htet Aung, Brian Giera, Weiqi Yu, Mohommad Redad Mehdi, Finley Holt, Quynh Tran, Gabriel Ponon, Dan Savage, Don Brown, Jarod Kaltenbaugh, Kush Havinal, Nicholas Gray, Max Ligget, Benjamin G. Pierce, Raymond Wieser, Yangxin Fan, Tommy Ciardi, Olatunde J. Akanbi, Hadiza Iawal, Will Oltjen, Maliesha Kalutotage, Antony Lino, Van Tran, Mingjian Lu, Xuanji Yu, Abhishek Daundkar, Hope Omodolor, Mirra Rasmussen, Sameera Nalin-Venkat, Tian Wang, Rounak Chawla, Liangyi Huang, Zelin Li, Leean Jo, Jeffrey M. Yarus, Mengjie Li, Kristopher O. Davis, Yinghui Wu, Pawan K. Tripathi, Laura S. Bruckman, Erika I. Barcelos, Roger H. French
Author-email: rxf131@case.edu
License: BSD-2-Clause
Requires-Python: >=3.9.18
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: rdflib>=7.0.0
Requires-Dist: pylode>=3.1.4
Requires-Dist: matplotlib>=3.6.2
Requires-Dist: numpy>=1.9.3
Requires-Dist: graphviz>=0.20.1
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# FAIRmaterials

## Python version

FAIRmaterials Python requires Python 3.10 and up.

## 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.

## 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](https://github.com/cwru-sdle/FAIRmaterials/tree/main/FAIRSheetTemplates)

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.

### Example of XRay ontology FAIR CSV sheet

Example Name Space Sheet:
![Name Space Sheet](https://github.com/cwru-sdle/FAIRmaterials/blob/main/Python/FAIRmaterials/namespacesheet.png?raw=true)

Example Ontology Information Sheet:
![Ontology Information Sheet](https://github.com/cwru-sdle/FAIRmaterials/blob/main/Python/FAIRmaterials/ontoinfosheet.png?raw=true)

Example Variable Definitions Sheet:
![Variable Definitions Sheet](https://github.com/cwru-sdle/FAIRmaterials/blob/main/Python/FAIRmaterials/vardefsheet.png?raw=true)

Example Relationship Definitions Sheet:
![Relationship Definitions Sheet](https://github.com/cwru-sdle/FAIRmaterials/blob/main/Python/FAIRmaterials/reldefsheet.png?raw=true)

Example Value Type Definitions Sheet:
![Value Type Definitions Sheet](https://github.com/cwru-sdle/FAIRmaterials/blob/main/Python/FAIRmaterials/valtypesheet.png?raw=true)

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.

## Install and load the package


Install in Python:

```{python, eval = FALSE}
pip install FAIRmaterials
```

## Running the default 'process_ontology_files' function

### PV ontology sheets


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:

![PV Module Graph Visualization](https://github.com/cwru-sdle/FAIRmaterials/blob/main/Python/FAIRmaterials/mds-pvModuleGraph.png?raw=true)

#### HTML output

The HTML output generated by the Python package for PV Module can be found [here](https://cwrusdle.bitbucket.io/PylodeHTML/mds-pvModule-pylode.html).

### XRay Sample ontology sheets




Running the package in Python:

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

![XRay Visualization With Value Types](https://github.com/cwru-sdle/FAIRmaterials/blob/main/Python/FAIRmaterials/mds-XraySampleGraph.png?raw=true)

#### HTML output

The HTML output generated by the Python package for XRay Sample can be found [here](https://cwrusdle.bitbucket.io/PylodeHTML/mds-XraySample-pylode.html).



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

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

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

![XRay Visualization With without Types](https://github.com/cwru-sdle/FAIRmaterials/blob/main/Python/FAIRmaterials/mds-XraySampleGraph-novaluetype.png?raw=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.


Adding external ontology information in Python:

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


## 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 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.

## 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