2.1. Checking for the existence of the subject and/or object

By default, inject will generate axioms regardless of whether the subject and object of a mapping exist in the current ontology (if they don’t exist, declaration axioms will be automatically generated).

Use the --check-subject option to instruct the command to check for the existence and status of the subject of a mapping before generating any axiom of it. If the subject does not exist or if it is obsolete, the mapping will be ignored and no axiom will be generated.

Use the --check-object to do the same, but for the object side of a mapping.

If the --invert option is also used, the checks take place after the inversion. So, using both --invert and --check-subject, for example, will first invert the mappings and then check whether the subject exists in the ontology – therefore, what will really be checked is the existence of the original object side of the mapping.

2.2. Dropping “duplicate” mappings

Use the --drop-duplicate-subjects option to drop any mapping that has the same subject ID as a previously processed mapping. With that option, if two (or more) mappings have the same subject ID (regardless of whether they point to the same object), they will be ignored.

Use the --drop-duplicate-objects option to do the same, but for the object side of mappings.

3.1. Ad-hoc options

These options are typically tailored for one particular use case and do not offer a lot of control on what is happening. There are currently three such options.

The --direct option transforms the mappings into their OWL serialisation as described in the SSSOM specification.

For example, per the SSSOM specification:

• mappings with a owl:equivalentClass predicate will be transformed into OWL equivalence axioms;
• mappings with a predicate that is an object property will be transformed into existential restriction axioms;
• mappings with a predicate that is an annotation property will be tranformed into annotation assertion axioms.

When combined with the --create option, the ontology newly created will be annotated with the metadata from the mapping set. Therefore, --create --direct allows to create a complete OWL export of a mapping set.

The --cross-species option is tailored for the specific use case of generating a bridge ontology between taxon-specific ontologies (or between a taxon-specific ontology and a taxon-neutral ontology). That option takes as an argument the IRI (possibly shortened as a CURIE) of an OWL class representing a taxon (e.g., http://purl.obolibrary.org/obo/NCBITaxon_7227) and will generate bridging axioms for mappings that use the https://w3id.org/semapv/vocab/crossSpeciesExactMatch predicate.

The --hasdbxref option generates OBO-style cross-reference annotations (oboInOwl:hasDbXref) on the subject with the shortened identifier of the object as value.

3.2. Using a SSSOM/T-OWL ruleset

Use the --ruleset option to specify the name of a SSSOM/T-OWL file describing precisely which axioms to generate from which mappings.

Refer to the description of the SSSOM/Transform language for details about the generic syntax of rules and filter expressions, and to the description of the SSSOM/T-OWL dialect for the details that are specific to the dialect used by inject.

subject==FBbt:* -> create_axiom('%subject_id SubClassOf: %object_id');

subject==FBbt:* -> create_axiom('%subject_id EquivalentTo: %object_id and (BFO:0000050 some NCBITaxon:7227)');

subject==FBbt:* -> annotate(%{subject_id}, IAO:0000589,  "%{subject_label} (Drosophila)");

subject==FBbt:* -> annotate(%{object_id}, oio:hasDbXref, "%{subject|short}");

4.1. Selectively enable or disabled tagged rules

By default, all SSSOM/Transform rules found within a ruleset will be used when processing the mapping.

Use the --include-rule option, followed by a tag, to use only the rules marked with that tag; all the other rules will be ignored. This may be useful if you have a complex ruleset where not all rules may always be needed. It may also allow you to put all your rules in the same file (where it may be easier to maintain them), knowing that you can use only the subset you need for a given task.

The option may be used several times to select more than one tag. In that case, the rules marked with either of the specified tags will be selected to run.

The --exclude-rule option does the opposite: it excludes any rule marked with the specified tag. As for its inclusive counterpart, it may be used as many times as needed to exclude more than one tag.

4.2. Write generated axiom to different files

For some applications, having all the axioms generated from the mappings in a single output file (the file specified with the --bridge-file option, as mentioned above) may not be practical.

The --dispatch-table options allows to specify a file (hereafter called the dispatch table) describing where axioms should be written depending on the tags carried by the SSSOM/Transform rules that generated them.

A minimal entry in the dispatch table looks like the following:

[tag]
file: output-file-for-tag.owl

where tag is a tag used in the SSSOM/Transform ruleset. Any axiom produced by a rule marked with that tag will be written to the indicated output file (in addition to being written to the main output file specified by the --bridge-file option, if used). The path to that file is relative to the directory containing the dispatch table itself.

Beyond the file field, the entry may also contain the following fields, which will be used to annotate the output file:

• ontology-iri,
• ontology-version,
• dc-title,
• dc-description,
• dc-creator,
• dc-contributor.

In the case of the ontology-version field, its value may contain a %date placeholder, which will be replaced by the current date in the YYYY-MM-DD format.

Both ontology-version and ontology-id can get a default value, to be used by all entries that do not have a value explicitly set for those fields. To set the default value, put it into an entry named __default (that entry does not need to have a file field). Both value may contain a %filename placeholder, which will be replaced by the basename (no directory, no extension) for each entry.

An entry may also contain one or several add-axiom field(s). Such a field must contain an expression in Manchester syntax that can be parsed into a single axiom, which will automatically be added to SSSOM-derived axioms.

Given the following ruleset (again, prefix declarations omitted):

[fbbt] subject==FBbt:* {
    [unique-label] predicate==* -> annotate(%{subject_id}, IAO:0000589, "%{subject_label} (Drosophila)");
    predicate==skos:speciesExactMatch -> create_axiom('%subject_id EquivalentTo: %object_id and (BFO:0000050 some NCBITaxon:7227)');
}

[wbbt] subject=WBbt:* {
    [unique-label] predicate==* -> annotate(%{subject_id}, IAO:0000589, "%subject_label (worm)");
    predicate==skos:speciesExactMatch -> create_axiom('%subject_id EquivalentTo: %object_id and (BFO:0000050 some NCBITaxon:6237)');
}

[xrefs] predicate==* -> annotate(%{subject_id}, oio:hasDbXref, "%{object_id|short}");

and the following dispatch table:

[fbbt]
file: fbbt-bridge.owl
ontology-iri: http://example.org/my-ontology/bridges/fbbt-bridge.owl
ontology-version: http://example.org/my-ontology/%date/bridges/fbbt-bridge.owl
dc-title: FBbt bridge

[wbbt]
file: wbbt-bridge.owl
ontology-iri: http://example.org/my-ontology/bridges/wbbt-bridge.owl
ontology-version: http://example.org/my-ontology/%date/bridges/wbbt-bridge.owl
dc-title: WBbt bridge

[xrefs]
file: mappings-as-xrefs.owl

all the axioms produced by the first two rules (both marked with the fbbt tag) would be sent to the fbbt-bridge.owl file, all axioms generated by the next two rules (marked with the wbbt tag) would be sent to the wbbt-bridge.owl file, and all axioms generated by the last rule would be sent to the mappings-as-xrefs.owl file.

If the table also contained an entry for the unique-label tag, the axioms generated by the first and third rule would also be sent to the file specified in that entry.