Reference

The User Guide is aimed at software developers that want to use OnToCode in their projects.

If you are unfamiliar with OnToCode, we recommend you to go through the Quick Guide to get a rough overview of how it works, before you continue reading.

OnToCode uses Owlready2 to load and work with ontologies as well as to query them. Classes of this library are part of OnToCode’s API, so you might need to consult its documentation as well.

The following sections document the behavior of OnToCode’s classes and their interactions. The classes are described in an order that minimizes forward references.

Ontology Locators

Ontology locators tell OnToCode where to find ontologies. OnToCode uses Owlready2 to load ontologies and therefore supports loading OWL 2.0 ontologies in the following formats:

• NTriples
• OWL/XML
• RDF/XML

Ontologies can be loaded from the file system (see FileSystemOntologyLocator) or via URL (see URLOntologyLocator).

An ontology locator is created by calling the constructor of a ontology locator class.

Ontologies are loaded by instantiations for the ontology locators passed to their constructors. Each instantiation loads ontologies into its own owlready2.namespace.World object.

class ontocode.ontology.FileSystemOntologyLocator(path, iri)

Specifies an ontology location in file system.

Parameters:

• path (str) – path to directory containing the file that describes the ontology with IRI iri (Not the path to a file).
• iri (str) – IRI of the ontology

class ontocode.ontology.URLOntologyLocator(url)

Specifies an ontology location on the Web.

Parameters:url (str) – URL of the ontology

Queries

OnToCode’s queries specify SPARQL-queries that are run by instantiations against loaded ontologies. A query returns a list of dictionaries with variable names as keys and Owlready2 objects as values.

class ontocode.query.Query(query)

Represents a SPARQL-query.

Parameters:query (str) – a SPARQL-query

Result Processors

Result processors convert the output of queries, a list of dictionaries with variable names as keys and Owlready2 objects as values, into the form expected by templates.

A template instantiation is given a list of result processors, a result processor chain. The first element of that chain is applied to the result of the template instantiation´s query result and subsequent elements of the chain are then applied to the output of their predecessor.

A result processor is a callable with two parameters, input_ and world. input_ is the query result or the output of their predecessor, while world is the owlready2.namespace.World object that the query was run against.

It is the responsibility of the user, that a result processor chain is setup, so that the output of a result processor meets the expectations of its successor or, for the final result processor, of the template for its input value.

Built-In Result Processors

This module provides three result processors for commonly required transformation tasks and a base class for result processors of a commonly encountered transformation scheme.

class ontocode.result_processor.AbstractMapElementsProcessor

AbstractMapElementsProcessor is an abstract base class for result processors that expect a list of dictionaries as their input_ parameter and, when called, apply a function, process_value(), to every value of those dictionaries.

__call__(input_, world)

Apply process_value() to every value of dictionaries in input_.

Parameters:input (list) – a list of dictionaries Returns:input_ with process_value() applied to every value Return type:a list of dictionaries

process_value(value, world)

Returns a new value derived from value and world.

Parameters:

• value – some value
• world (owlready2.namespace.World) – the world object, that is the source of the currently processed query result

class ontocode.result_processor.ObjectNameProcessor

Bases: ontocode.result_processor.AbstractMapElementsProcessor

Replaces Owlready2 objects with their names.

class ontocode.result_processor.NoNameError

Bases: ValueError

Raised when ObjectNameProcessor encounters an object without name.

class ontocode.result_processor.ObjectLabelProcessor

Bases: ontocode.result_processor.AbstractMapElementsProcessor

Replaces Owlready2 objects with their English (‘en’) labels.

class ontocode.result_processor.NoLabelError

Bases: ValueError

Raised when ObjectLabelProcessor encounters an object without an English (‘en’) label.

ontocode.result_processor.list_of_dicts_to_dict_of_lists(input_, _world)

Converts a list of dicts to a dict of lists.

Assumes that all dicts in the list of dicts have the same set of keys.

Parameters:input (list) – a list dictionaries Returns:a dictionary of lists Return type:dict

Template Inputs

Template inputs aggregate queries and result processors. A template input object produces input for a template instantiation by executing its Query and passing it through its chain of result processors.

class ontocode.template_input.TemplateInput(query, result_processors)

Constitutes a template input consisting of a ontocode.query.Query and corresponding result processors.

Parameters:

• query (ontocode.query.Query) – a query
• result_processors (list) – a list of result processors

Templates

Instances of ontocode.template.Template´s subclasses represent templates that are instantiated by the arguments provided by template inputs.

class ontocode.template.Template

Abstract base class for templates.

render(*args, **kwargs)

Render the template.

Parameters:

• *args – *args as passed to an Instantiation´s execute() method
• **kwargs – combination of **kwargs as passed to an Instantiation´s execute() method and the arguments generated by the template inputs of that Instantiation. For more information consulte the section on Instantiations.

Jinja2 Template

OnToCode optionally provides one implementation of ontocode.template.Template: ontocode.jinja2_template.Jinja2Template. This class provides interoperability with the Jinja2 template library.

Note that ontocode.jinja2_template.Jinja2Template is only available, when the jinja2 package is on the python path.

class ontocode.jinja2_template.Jinja2Template(template)

Bases: ontocode.template.Template

Template class for Jinja2 templates.

classmethod from_environment(environment, name)

Creates a Jinja2Template object with the underlying Jinja2 template created from a named template in a jinja2.Environment.

Parameters:

• environment (jinja2.Environment) – a Jinja2 environment
• name (str) – a string designating a template in environment

Return type:

Jinja2Template

classmethod from_file(path)

Creates a Jinja2Template object with the underlying Jinja2 template created from the constants of a file.

Parameters:path (str) – path to a file containing a Jinja2 template Return type:Jinja2Template

classmethod from_string(string)

Creates a Jinja2Template object with the underlying Jinja2 template created from a string.

Parameters:string (str) – Jinja2 template as string Return type:Jinja2Template

render(*args, **kwargs)

Passes *args and **kwargs unchanged to the underlying Jinja2 template.

Instantiations

Instantiations tie everything together. An Instantiation aggregates a list of ontology locators, a template, and list, as well as optionally a single instance, of template inputs.

Calling one of their execution methods will cause it to load the ontologies specified by the ontology locators, let the template inputs generate arguments for the template and pass the results to its template.

A Instantiation object can instantiate its template multiple times for a single execution. This is controlled by the second template input argument to Instantiation´s constructor: per_row_input.

Template inputs passed as arguments to per_row_input are expected to return a list of dictionaries, while all template inputs in lists passed as arguments to at_once_inputs are expected to return dictionaries. The number of elements in the list generated by the per_row_input argument determines the number of template instantiations.

When execute() is called (directly or via execute_and_write_to_file()) with arguments *args and **kwargs, the template inputs passed to at_once_inputs are called to generate a set of dictionaries and, if not None, the argument passed to per_row_input is called to generate a list of dictionaries.

Now two cases have to be distinguished: per_row_input is None or generated an empty list and per_row_input generated a non-empty list.

In the former case, the template is instantiated once. *arg is passed right through from execute(). The argument to **kwargs is a merge of **kwargs as passed to execute() with the dictionaries generated by the argument to at_once_inputs, where execute()´s **kwargs take precedence over the generated dictionaries and the precedence order within the dictionaries is determined by their order as part of the list passed to at_once_inputs.

In the latter case, the template is instantiated once for each dictionary generated by the argument to per_row_input. The arguments to the template are constructed similarly to the previous case. The only difference is, that for each invocation a different dictionary of those generated by the argument to per_row_input is merged with the other dictionaries to produce the **kwargs argument. In the precedence order, it is located between the **kwargs as passed to execute() and the dictionaries generated by the argument to at_once_inputs.

class ontocode.instantiation.Instantiation(ontology_locators, template, at_once_inputs, per_row_input=None)

Instantiation of a template based on data queried from ontologies.

Parameters:

• ontology_locators (list) – a list of ontology locators
• template (ontocode.template.Template) – a template
• at_once_inputs (list) – a list of TemplateInputs
• per_row_input (ontocode.template_input.TemplateInput) – a template input

execute(*args, **kwargs)

Executes the instantiation and returns a list of the results.

The Instantiations module documentation describes the instantiation process.

execute_and_write_to_file(path, *args, **kwargs)

Executes the instantiation and writes result to file.

Raises an ontocode.instantiation.TemplateInputArgumentError, if a non-null value for per_row_input was passed into the constructor of this Instantiation instance.

The Instantiations module documentation describes the instantiation process.

Parameters:path (str) – path to target file

execute_and_write_to_files(path_function, *args, **kwargs)

Executes the instantiation and writes result to files.

The Instantiations module documentation describes the instantiation process.

Parameters:path_function (generator) – a function that takes the same arguments as the instances template and returns a path for the corresponding template invocation

exception ontocode.instantiation.TemplateInputArgumentError

Raised when execute_and_write_to_file() is called on an Instantiation´s instance that was created with a non-null per_row_input argument.

exception ontocode.instantiation.TemplateInputResultError

Raised when a template input´s result is of the wrong type.