CLI Guide

This guide provides an in-depth introduction to the CLI and some caveats that are important to note to take advantage of all the features CEMENTO offers. If you just want to convert files, go to Quick Start.

Command Line Interface

Once the package is installed, you will have access to a cemento CLI command for converting files. This CLI interface allows you to convert .ttl files into draw.io diagrams and vice versa. To do so:

# converting from .ttl to drawio
(.venv) $ cemento ttl_drawio your_triples.ttl your_output_diagram.drawio

# converting from .drawio to .ttl
(.venv) $ cemento drawio_ttl your_output_diagram.drawio your_triples.ttl

It is that simple. In case you do need help, the CLI already comes with useful help pages. Just use the --help flag on the command or any of its subcommands:

(.venv) $ cemento --help
(.venv) $ cemento drawio_ttl --help
(.venv) $ cemento ttl_drawio --help

Term Matching

When converting from draw.io to .ttl, your draw.io diagrams can have classes, instances, or predicates that can correspond with those in a reference ontology like CCO or PMDCO. To avoid redundancy, CEMENTO automatically matches them for you. This section describes how it does so, but only from the perspective of CLI use. If you want to learn more about diagram drawing, please refer to the Drawing Basics Section.

Acceptable Format for Term Matching

A term in a diagram is only matched if it is on a shape or an arrow label. They can have the following format:

<prefix>:<abbrev-term>

# for example
cco:ICE

Where, <prefix> is the prefix the reference ontologies used to refer to that term. <abbrev-term> can either be the last part of the term URI, its label, or one of its alternate labels (rdfs:label or skos:altLabel).

For example, CCO’s Information Content Entity has a URI of https://www.commoncoreontologies.org/ont00000958 so you can write cco:ont00000958 (with the last part of the term URI), cco:Information Content Entity (with the rdfs:label value), or cco:ICE (with a known skos:altLabel value).

Your terms do not have to be the exact copy of the IRI or the label of the term you want to match. CEMENTO automatically adds the aliases of the referenced terms to its search-pool in addition to conducting fuzzy-search to get matches. Hence, you can use symbols like spaces, underscores, or dashes if you wish. A word of caution with camel case or pascal case though. They are usually standard but they are harder to match. Use them with discretion.

Beware, shorter terms are also harder to match, and only aliases inside the reference ontologies will be used. For example, cco:ICE will match to “Information Content Entity” in the CCO ontology. In contrast cco:Information CE will not match because it is not a known skos:altLabel or rdfs:label of the term.

Terms that are replaced will have the skos:exactMatch relationship to the term they reference. Since the term is replaced, this will be a self-referential triple added just for annotation.

Default Reference Ontologies

By default, the program compiles with the versions of the reference ontologies it needs to do term matching. Specifically, it comes bundled with the following ontologies.

• Common Core Ontologies

• OWL Schema

• RDF Schema

• RDFS Schema

These ontology files are used by CEMENTO for referencing terms and predicates. The package has built-in copies of the reference files in the .ttl format. As you can imagine, the default reference ontology is CCO, which is the preferred mid-level ontology by the SDLE center. The next section details how you can add your own reference ontologies.

Adding or Replacing Reference Ontologies

The cemento ttl_drawio command has an argument called --onto-ref-folder-path which you can point to a folder containing .ttl files that contain the terms you want to reference. For example, you can download a .ttl file from the official CCO repo page and place it here to reference all CCO terms. Under the hood, this referencing is additive, which means you can add as many .ttl as you want to reference. By default, cemento will already come bundled with this folder, but it will currently only reference CCO.

CAUTION: Repeated references are overwritten in the order the files are read by python (usually alphabetical order). If your reference files conflict with one another, please be advised and resolve those conflicts first by deleting the terms or modifying them in the .ttl files.

Replacing Default Ontologies

The schemas for RDF, XML, and RDFS contain the terms that all ontologies ought to understand by default. Thus, a lot of assumptions were made surrounding their standard use during the development of the package. You can, however, also specify a folder of choice through the --defaults-folder-path option for cemento ttl_drawio. Replace it at your own risk.

Custom Terms and Prefixes

Creating new terms is just as easy as adding them. However, using custom namespaces is a different matter. Any term that doesn’t come with a prefix gets assigned our default namespace mds.

In order to use custom prefixes, you need to create a prefix.json file that looks like the following:

NOTE: This exact file is available when you pull the repository and can be found in examples/prefixes.json.

{
    "cco": "https://www.commoncoreontologies.org/",
    "mds": "https://cwrusdle.bitbucket.io/mds/",
    "owl": "http://www.w3.org/2002/07/owl#",
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
    "ncit": "http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#",
    "skos": "http://www.w3.org/2004/02/skos/core#",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "obo": "http://purl.obolibrary.org/obo/",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "qudt": "http://qudt.org/schema/qudt/",
    "pmdco": "https://w3id.org/pmd/co/",
    "pmd": "https://w3id.org/pmd/co/",
    "dcterms": "http://purl.org/dc/terms/",
    "unit": "http://qudt.org/vocab/unit/",
    "afe": "http://purl.allotrope.org/ontologies/equipment#",
    "afm": "http://purl.allotrope.org/ontologies/material#",
    "afq": "http://purl.allotrope.org/ontologies/quality#",
    "afr": "http://purl.allotrope.org/ontologies/result#"
}

This file is just a python dictionary enclosed as a json object. Add yours by following the format (copy-paste a line, for example) and inserting it at the bottom of this file. Make sure your prefix is reasonably unique (i.e. don’t copy one that is already in this file).

After you are happy with your file, go ahead and set the --prefix_file_path when running cemento cemento drawio_ttl and point it to the path to your file. It should now read your custom prefixes and add the right namespace for your terms.