Tutorial
Here we provide a tutorial of how Ontorat can be applied for your research and ontology development:
Table of Contents:
- Explanation of signs used in Ontorat
- Ontorat execution using web input forms
- Ontorat execution using setting file
- Ontorat input
- Ontorat output
- Ontorat debugging
- Ontorat use cases
1. Explanation of signs used in Ontorat:
Ontorat relies on the pattern program using the OWL Manchester Syntax, a syntax designed for writing OWL class expressions (http://www.w3.org/TR/owl2-manchester-syntax/ ). For example, based on the Manchester Syntax, the full IRI is defined as:
fullIRI := an IRI as defined in [RFC 3987], enclosed in a pair of < (U+3C) and > (U+3E) characters
The following table list some commonly used OWL Manchester Syntax keywords:
OWL restrictions DL Symbol Manchester OWL Syntax OWL Boolean class constructors DL Symbol Manchester OWL Syntax someValuesFrom ∃ some intersectionOf ⊓ and allValuesFrom ∀ only unionOf ⊔ or hasValue ∋ value complementOf ¬ not minCardinality ≥ min cardinality = exactly maxCardinality ≤ max More information about the OWL Manchester Syntax can be found on: http://www.co-ode.org/resources/reference/manchester_syntax/.
The following table lists some syntax formats commonly used in Ontorat:
# Construct Syntax Example 1 Column content 2 Class name 3 String annotation 4 Full IRI
<{$columnA}> (Note: when column A has a full IRI)
<http://pur.obolibrary.og/obo/{$columnA}> (Note: when columnA has ontology ID)5 Annotation
'label' "{$columnA} ({$columnB})" (Note: merge columns A and B for label),6 Parent class 7 Class logical definition 8 Ontology terms used for definitions
2. Ontorat input using web input forms:
Ontorat provides a user-friendly web form for data input. The steps using the web form to generate Ontorat input include:
- Specify a target ontology in OWL format. The target ontology is used to avoid the assignment of repeated ontology identifiers (IDs). The ontology can be provided by specifying (i) a web URI that points to an ontology OWL file, or (ii) a local file location. The tutorial also provides an example ontology OWL file.
NOTE: the OWL file must be a merged OWL file and do not have any import. - Specify the data input file (an Excel file or tab-delimited text file). This file provides the input data for high throughput processing. Each column of the data file needs to be very specific. The data input file can be provided by specifying (i) a web URI that points to an ontology OWL file, or (ii) a local file location. We also provide an example Excel file and an example tab-delimited text file.
NOTE: Please do not forget to include the information of the row number that start to include the actual data after the term: Actual data starts from row. - Purpose of the new axiom generation, for example, generating new ontology classes or providing annotations.
- Annotations. The ontology design pattern is generated using the class expressions with variables. A user will need to generate a script to represent the ontology design pattern using the Manchester OWL Syntax (see the above table). An internally designed code is used to represent different columns (i.e., variables). For example, we use $columnA to represent the first column (or column A), and use $columnB to represent column B, et al. Each column represents a variable.
- Equivalent classes. The Manchester OWL Syntax is used to express an equivalent class (see the above table).
- Superclasses using the Manchester OWL Syntax. The Manchester OWL Syntax is used to express an equivalent class (see the above table).
- Terms used to define annotations, equivalent classes and superclasses. Those terms may be typed using term labels. In this section, the term labels are specified by ontology URI. This way Ontorat can map the labels with specific ontology URIs. Note that there is no need to define those annotation properties listed by Ontobee, including RDF schema annotation properties 'label', 'comment', and 'seeAlso', and IAO annotation terms 'editor preferred term', 'example of usage', 'has curation status', 'definition', 'editor note', 'definition editor', 'alternative term', and 'definition source'.)
- Term URI start content, i.e., a URI as the start of an ontology before an ontology ID, for example, http://pur.obolibrary.og/obo/ for OBO foundry library terms..
- Auto-generated term ID. Three data items are needed: prefix, number of digits, and start number. The information will be used for automatically generating unique term IDs.
3. Ontorat execution setting using Ontorat setting file:
Ontorat provides a single setting file that contains all the information of settings for an Ontorat execuation. The following is an example (Note: this includes the same content as the Example 1 setting file, with an exception of including more comments here):
[Online URL of the target OWL file (RDF/XML format)]
# Note: Local file won't be used by Ontorat for security reason. However, you can use local file using the Ontorat web form.
# Note: You can still use the setting file without the indication of the target OWL file. The setting file can be used to store the setting and can be loaded to the web form automatically on the Ontorat page.
# Note: Any notes after # are considered as comments and will be ignored by the Ontorat program.
[Online URL of the data file (Only Excel file (.xls, .xlsx) or tab-delimited text file (.txt)]
# Note: Local file won't be used by Ontorat for security reason. However, you can use local file using the Ontorat web form.
# Note: You can still use the setting file without the indication of the data input file. The setting file can be used to store the setting and can be loaded to the web form automatically on the Ontorat page.
Actual data starts from row: 2
# The data input file often includes a header row that indicates the contents of each column. So real data often starts from row #2.
[New axioms will be used to]
# Note: two options: 1. "generate new classes",
# or 2. "edit existing classes with term IDs defined in column A(or another letter)"
generate new classes
[Annotations]
# Note: Use comma to separate annotations; Quote annotation property terms using single quotes ' ' even for a single word of annotation property term.
'label' "{$columnA} ({$columnB})", # space can be added inside quotes.
'seeAlso' "{$columnB}", # anything after a space+# until the end of the line will be comments and be ignored by Ontorat program.
'seeAlso' "violinID:{$columnO}"[Equivalent classes]
# Note: Use comma to separate classes; See below for some syntax example.[Superclasses]
# Note: Use comma to separate classes
<http://pur.obolibrary.og/obo/{$columnD}>,
'vaccine immunization against microbe' some <http://pur.obolibrary.og/obo/NCBITaxon_{$columnF}>,
'vaccine immunization for host' some <http://pur.obolibrary.og/obo/NCBITaxon_{$columnH}>,
'bearer_of' some <http://pur.obolibrary.og/obo/{$columnL}>,
'is_manufactured_by' some ({$columnN})[Terms used to define anntoations, equivalent classes and superclasses]
# Note: One line per term
AnnotationProperty:
Class:
ObjectProperty:
'is_manufactured_by': <http://purl.obolibrary.org/obo/OBI_0000304>
'bearer_of': <http://purl.obolibrary.org/obo/bearer_of>
'vaccine immunization for host': <http://pur.obolibrary.og/obo/VO_0001243>
'vaccine immunization against microbe': <http://pur.obolibrary.og/obo/VO_0003355>
DataProperty:[Term URIs start with]
# Note: provide a prefix ontology URIs
http://pur.obolibrary.og/obo/[Auto-generated term ID]
# Note: Prefix like "VO_", number of digits like "7", and start from like "1".
Prefix: VO_
Number of digits: 7
Start from: 1
4. Ontorat input:
The Ontorat input data file can be in an Excel format or in a tab-delimited text format. You can include more columns (e.g., for confirmation purpose) in the input data file than what you need for Ontorat. Ontorat will automatically extract the content of any column specified in your syntax (See the above tables).
5. Ontorat output:
The Ontorat output is an OWL file. Using the Protégé ontology editor (http://protege.stanford.edu/), an Ontorat output OWL file can be directly visualized and imported (or merged) in the target ontology (e.g., VO) using the OWL import function.
6. Ontorat debugging:
If you have a problem in executing Ontorat, it means that there is some bug in the execuration. You will need to carefully examine every detail, including your input data format, script generation, needed information, etc. Ontorat will provide some warning or error message when something is wrong. To better support bebugging, you can download the output file in the Manchester Syntax format. The Ontorat error message page will provide some clue on which line(s) of the Manchester Syntax format output document has a problem. You can then trace it out. If you need help, please do not hesitate and feel free to contact the Ontorat development team for help.
7. Use cases:
Please go to the Ontorat Templates page to identify all the use cases done with Ontorat.
Explanation: This use case study aimed to use Ontorat to generate new VO terms for a list of USDA-licensed animal vaccines. The Ontorat input Excel file and text file contain the same information. The Ontorat can be used to include the following information to the annotations or logical axiom definitions: vaccine name, parent term, host, pathogen, manufacturer, VIOLIN_ID. The vaccine names are the labels of to-be-generated VO classes. Manchester OWL Syntax scripts for expressing the axioms associating the vaccine with other contents are generated and inserted to the Ontorat web forms. It is noted that besides the relations between classes, Ontorat also allows the generation of annotations using annotation properties (e.g., see_Also and term definition). The Ontorat output OWL file can be directly imported to VO.
