Introduction

This page gives some examples of running owlsim2 on the command line.

The OWLTools CLI

OWLSim is executed via the OWLTools command line interface. Any owltools command can be used.

Note that in owltools, the ordering of commands in a single line has importance - commands are executed in order.

See also CommandLineExamples for owltools.

Basic Setup

These examples assume that you have

• an ontology available, in obo or owl, on the filesystem or on the web
• a set of annotations, represented as a two column table

For example, if the ontology is MP, then the annotation file may be

MGI:101757      MP:0000929
MGI:101757      MP:0001286
MGI:101757      MP:0001688
MGI:101757      MP:0001698
...

Basic Analysis

This command will load the ontology, annotations and run a basic analysis:

owltools mp.obo --load-instances mgi2mp.txt --sim-basic -o results.out

Note that any obo or owl ontologies can be used. Annotations can also be provided in OWL as Class Assertions. The load-instances command is just a convenience for creating these. The effects would be equivalent to loading an OWL ontology:

ClassAssertion(MP_0000929 MGI_101757)
...

Properties Files

The behavior of owlsim can be configured by a properties file. If we have a file sim.properties:

minimumMaxIC = 0.05
minimumSimJ = 0.05
compare = MIM,MGI

We can say:

owltools mp.obo --load-instances mgi2mp.txt --sim-basic -p sim.properties -o results.out

Gene Labels

The output file is more readable if we include gene labels. Assume a file mgi-labels.txt:

MGI:101757      Cfl1
MGI:101758      Pet2
MGI:101759      Syt4
MGI:101760      Sfswap
...

We can add --load-labels FILE on the command line, which has the effect of making rdfs:label annotation assertions.

E.g.

owltools mp.obo --load-instances mgi2mp.txt --load-labels mgi-labels.txt --sim-basic -p sim.properties -o results.out

The same thing can be achieved with an OWL document processed some other way

Comparing attributes (ontology classes)

owltools mp.obo --load-instances mgi2mp.txt --sim-compare-atts -p sim.properties -o results.out

Basic Ontology Processing: Subsets

the OWLTools CLI has powerful facilities for performing processing of ontologies that can be used to make mini owlsim "pipelines". Say for example we want to perform an analysis that only makes use of annotations to "nervous system", we could pre-process the ontology to make a slim based on a query:

owltools mp.obo --reasoner-query -r elk MP_0003631 --make-ontology-from-results http://x.org -o -f obo mp-ns.obo

This could then be used as input.

Note that as commands are executed in order, this can all be done on the same lineL

owltools mp.obo --reasoner-query -r elk MP_0003631 --make-ontology-from-results http://x.org --load-instances mgi2mp.txt --remove-dangling-annotations --sim-basic -p sim.properties -o results.out

here we include an extra command that removes assertions to non-existent classes (ie those filtered in the previous step)

Working with multiple ontologies

Here we assume we have

• annotation of disorders to HP
• annotation of genes to MP
• bridging axioms between HP and MP

With owltools you can either work with individual ontologies, or with owl imports.

If the former, you must remember to merge the individual ontologies. E.g.

owltools mp.obo hp.obo mp_hp-align-equiv.obo --merge-support-ontologies

This has the effect of combining everything into one ontology

Again, you can combine everything into one line:

owltools mp.obo hp.obo mp_hp-align-equiv.obo --merge-support-ontologies --load-instances mgi2mp.txt --load-instances omim2hp.txt --sim-basic --set compare MGI,MIM -o test.out

Here we introduce the "--set" suboption of the --sim family of commands - this has the same effect as including a line

compare = MGI,MIM

in the .properties file

In general, it is recommended that you work with importer ontologies rather than lots of individual files

TODO: check whether the --merge-import-closure command needs to be read in

Advanced multi-ontology processing

OWLSim comes with various preprocessors that can be used to generate ontologies geared towards specific questions, or generate grouping classes.

PhenoSim

The phenosim preprocessor will generate new analysis classes such as abnormal forelimb bone shape based on a set of input ontologies, logical definitions and instance data.

owltools uberpheno-subq-importer.owl --merge-import-closure --load-instances mgi2mp.txt --load-instances omim2hp.txt --phenosim -p phenosim.properties --set compare MGI,MIM -o test.out

TODO: document

Splitting an analysis into multiple commands

The OWLSim pre-processing step can take a few hours. It will save intermediate files it creates along the way. Currently these go in /tmp/ but this will change in the future.

TODO

Semantic similarity of expression data

For this we want to create a view using the part_of relation

owltools $OBO/uberon.owl --load-instances -p BFO:0000050 gene-anatomy-pairs.txt --set-sim-property analysisRelation BFO:0000050 --sim-basic -p test-sim.properties -o results.out

This works by creating a "snomed-like" SEP view, with a subclass hierarchy:

• limb part
• hand part
• hand (note that view relation is treated reflexively by default)
• digit part

If you wish to examime the resulting view ontology, add the following to the end of the command line:

 -o file://`pwd`/uberon-part-of-view.owl

You may wish to experiment with more permissive views that use a more general grouping relation. See the next example

Semantic similarity with GO

First we create an ontology analysis-rel.obo that contains our grouping relation:

[Typedef]
id: TEST:1
name: related to
is_transitive: true

[Typedef]
id: part_of
xref: BFO:0000050
is_a: TEST:1

[Typedef]
id: regulates
xref: RO:0002211
is_a: TEST:1

Then we merge this into GO and use the "related to" relation for grouping:

owltools $OBO/go.owl analysis-rel.obo --merge-support-ontologies --load-instances -p TEST:1 gene-goterm-pairs.txt --set-sim-property analysisRelation TEST:1 --sim-basic -p test-sim.properties -o results.out