fairgenomes / fairgenomes-semantic-model

FAIR Genomes semantic metadata model. The core is a YAML file, which is transformed into all other desired output formats.

FAIR Genomes semantic schema

Explore

Discover the full schema at the interactive overview.

Source

The source of the schema is located at fair-genomes.yml. The reference lookup lists are available at lookups.

Outputs

Representations of the schema for specific systems/users are generated from the schema. The following outputs are available:

Electronic Data Capture (EDC) systems

• MOLGENIS EMX1 database setup at molgenis-emx.
• PALGA Codebook at palga-codebook.
• ART-DECOR at art-decor. The ART-DECOR XML is uploaded to NICTIZ made available for iCRF Generator. FAIR Genomes interoperable case report forms can be created by iCRF Generator in these EDC formats:
  • Castor - Step
  • Castor - Report
  • Castor - Survey
  • REDCap
  • OpenClinica 3

Resource Description Framework (RDF)

• Application ontology at ontology.
• Resources for new terms at resource.

Documentation

• Interactive overview at markdown. View it here.
• Typesetted LaTeX/PDF at latex and pdf. View it here.
• LODE page at lode. View it here.

Demo

Please try the public demo at give us feedback.

Other links

• Persistent namespace is provided by W3ID, linking to ontology and resources.
• Find us on FAIRSharing.
• Available on BioPortal.

Technical notes

Using an international list of institutes

The Research Organization Registry (https://ror.org/) provides a unique identifier for every research organization in the world. The 2021-09-23 ROR Data release (see https://zenodo.org/communities/ror-data) has been transformed in a FAIR Genomes compatible lookup list. This list, available at InstitutesROR.txt, can be used to supplement or replace the default Institutes.txt. The ROR institute data is currently not generated into apps because everything would become much bigger and slower than necessary under most circumstances.

FAIR Genomes YAML format

The YAML format used to contain the FAIR Genomes schema is documented at YamlFormat.md.

RDF formats

The FAIR Genomes application ontology TTL files can be converted to other RDF serialization formats including OWL-XML, RDF-XML, RDF-JSON, JSON-LD, N-Triples, TriG, TriX, Thrift, Manchester syntax and Functional syntax using Ontology Converter.

For example, conversion to OWL-XML can be accomplished by running:

java -jar ont-converter.jar -i /path/to/fairgenomes-semantic-model/generated/ontology/fair-genomes.ttl -if TURTLE -o fair-genomes.owl -of OWL_XML

Please be aware that the original TTL format is highly efficient. Other RDF formats typically consume more disk space. Conversions using the FAIR Genomes TTL of 25-02-2021 as a reference results in the following relative file size differences:

Format	Difference
TTL	0% (reference)
OWL-XML	+660%
RDF-XML	+107%
RDF-JSON	+176%
JSON-LD	+13%
N-Triples	+357%
TriG	-1%
TriX	+696%
Thrift	+284%
Manchester	+435%
Functional	+300%

ART-DECOR validation

The ART-DECOR XML is validated using Saxon, requiring these resources:

http://art-decor.org/ADAR/rv/DECOR.sch
https://github.com/Schematron/stf/blob/master/iso-schematron-xslt2/iso_svrl_for_xslt2.xsl
https://github.com/Schematron/stf/blob/master/iso-schematron-xslt2/iso_schematron_skeleton_for_saxon.xsl

The Schematron must first be converted to XSLT:

java -jar saxon-he-10.3.jar -o:DECOR.xsl -s:DECOR.sch iso_svrl_for_xslt2.xsl

The XML can then be validated as follows:

java -jar saxon-he-10.3.jar -o:warnings.xml -s:/path/to/fairgenomes-semantic-model/generated/art-decor/fair-genomes_en-US.xml DECOR.xsl

Finally, warnings.xml is inspected for any errors or warnings.

Release SOP

1. Set correct date, version number and release type in YAML file.
2. Generate outputs (by running Main.java).
3. Validate implementations:
   • Run ART-DECOR XML validation
   • Run MOLGENIS setup script
   • Import application ontology into GraphDB
   • Check Markdown rendering
4. Update PDF (run toPDF.sh in generated/latex).
5. Update version in sys_StaticContent.tsv.
6. Update version in pom.xml.
7. Update Docker prepare at misc/molgenis/docker based on setup.sh.
8. Create a new Excel file at misc/excel.
9. Make commits and push to fork.
10. Pull request and merge with main (i.e. fairgenomes organization).
11. Create updated LODE page by following the link to TTL file in main repo.
12. Commit LODE page to fork, then again PR and merge with main.
13. Create Github release on main.
14. Prepare for further development: increment version in fair-genomes.yml and set to SNAPSHOT. Also update pom.xml and sys_StaticContent.tsv.
15. Update to new SNAPSHOT version in outputs by running Main.java.
16. Use Ontology Converter to convert to OWL and publish new version on BioPortal.
17. Reset demo server and import new app.

MOLGENIS-EMX2

To upload to molgenis-emx2, make a zip of the generated/molgenis-emx2 and upload.