Utilities

In this section we will compile a list of useful utility functions, tools and examples of their usage. This functions are part of OSP-core and are used as an extension of the main API.

Pico Installs Cuds Ontologies

Our tool for installing ontologies is called pico. It is a recursive acronym that stands for Pico Installs Cuds Ontologies.

There are 3 main things that can be done with pico:

  • Install ontologies.

  • List the installed ontologies.

  • Remove installed ontologies.

There are different possible levels of log available, and they can be set via --log-level <ERROR|WARNING|INFO|DEBUG>. The default value is INFO.

Pico installs

Usage: pico install <path/to/ontology.yml>|city|cuba

Behaviour:

  • The ontology file is parsed, and the entities mapped to python objects.

  • The python classes can be imported via their namespace from osp.core.namespaces import namespace

Example:

(venv) user@PC:~$ pico install city
INFO [osp.core.ontology.installation]: Will install the following namespaces: ['city']
INFO [osp.core.ontology.yml.yml_parser]: Parsing YAML ontology file /.../osp-core/osp/core/ontology/docs/city.ontology.yml
INFO [osp.core.ontology.yml.yml_parser]: You can now use `from osp.core.namespaces import city`.
INFO [osp.core.ontology.parser]: Loaded 367 ontology triples in total
INFO [osp.core.ontology.installation]: Installation successful

Pico lists

Usage: pico list

Behaviour:

  • The installed namespaces and packages are printed out. A package can be uninstalled and can contain many namespaces. A namespace can be imported in code.

Example:

Packages:
        - qe
        - city
Namespaces:
        - xml
        - rdf
        - rdfs
        - xsd
        - cuba
        - owl
        - qe
        - city

Pico uninstalls

Usage: pico uninstall <package>|all. Note that to select all the packages, all must be quoted.

Behaviour:

  • All installed packages / namespaces are uninstalled.

  • All namespaces except the uninstalled ones are re-installed.

Example:

INFO [osp.core.ontology.installation]: Will install the following namespaces: ['qe']
INFO [osp.core.ontology.yml.yml_parser]: Parsing YAML ontology file /home/<username>/.osp_ontologies/qe.yml
INFO [osp.core.ontology.yml.yml_parser]: You can now use `from osp.core.namespaces import qe`.
INFO [osp.core.ontology.parser]: Loaded 205 ontology triples in total
INFO [osp.core.ontology.installation]: Uninstallation successful

Ontology installation folder

The installed ontologies are stored in the directory ~/.osp-ontologies by default. On Windows, ~ usually refers to the path C:\Users\<my username>.

The installation directory can be changed by setting the environment variable OSP_ONTOLOGIES_DIR. Such action would move it to $OSP_ONTOLOGIES_DIR/.osp-ontologies.

Conflicts with other “pico” installations

Some Operating Systems might have a pre-existing tool called pico. In most cases, the previous commands should work, but if any problem arises, you can use the following alternative:

python -m osp.core.pico <command>

For example:

python -m osp.core.pico install city

Tips and tricks

The following are some utility functions and shortcuts for working with cuds. For those that are present in the util package, the import is from osp.core import utils.

  • utils.get_relationships_between(a, b) returns a set with the relationships that connect a and b .

  • a.get_attributes() returns a dictionary with the name and the value of the attributes of a.

  • a.is_a(oclass) is True if the instance a is or inherits from oclass.

  • osp.core.get_entity("namespace.entity") returns the class associated with an entity in a namespace. It can be used to instantiate objects.

  • [attr.argname for attr in oclass.attributes.keys()] returns a list with the attributes of an oclass.

  • [attr.namespace for attr in oclass.attributes.keys()] returns a list with the namespace of the attributes of an oclass.

Visualisation

There are two ways of visualising information about a Cuds structure, one as a text output to the standard output (pretty print), and another one as a dot graph (cuds2dot).

Another useful dot graph visualisation tool called ontology2dot is available for ontology YML files.

Warning

The graphic visualisation tools that generate a dot file require Graphviz to be installed in the system.

Pretty print

Location: from osp.core.utils import pretty_print.

Usage: pretty_print(cuds_object)

Behaviour:

  • The UUID, oclass and attributes of the given object are printed.

  • All the related objects are also printed in a recursive fashion.

  • The relationship to the contained objects is stated.

Example:

>>> pretty_print(emmo_town)
Cuds object named <EMMO town>:
  uuid: 06b01f5a-e8c1-44a5-962d-ea0c726e97d0
  type: city.City
  superclasses: city.City, city.PopulatedPlace, city.GeographicalPlace, cuba.Entity
  values: coordinates: [42 42]
  description: 
    To Be Determined

   |_Relationship city.hasInhabitant:
   | -  city.Citizen cuds object named <Emanuele Ghedini>:
   | .  uuid: f1bd9143-6472-4b24-94b5-1c5fc4c6e5b6
   | .  age: 25
   | -  city.Citizen cuds object named <Adham Hashibon>:
   | .  uuid: 3b774c96-1a0c-403b-b0d0-05d6cd38c52c
   | .  age: 25
   | -  city.Citizen cuds object named <Jesper Friis>:
   | .  uuid: 40d2335c-a335-4d07-b142-fb2b9b7581a7
   | .  age: 25
   | -  city.Citizen cuds object named <Gerhard Goldbeck>:
   | .  uuid: a5b9282a-ec10-462d-9aa1-9671d8bbe236
   | .  age: 25
   | -  city.Citizen cuds object named <Georg Schmitz>:
   | .  uuid: c7c87209-660f-4a54-9c37-7e50c3164bc9
   | .  age: 25
   | -  city.Citizen cuds object named <Anne de Baas>:
   |    uuid: d74cfbae-9699-4998-a1e2-8f495a874ced
   |    age: 25
   |_Relationship city.hasPart:
     -  city.Neighborhood cuds object named <Ontology>:
     .  uuid: 26c4767d-c0ea-4abb-b7b7-7e8702de5de3
     .  coordinates: [0 0]
     .   |_Relationship city.hasPart:
     .     -  city.Street cuds object named <Relationships>:
     .     .  uuid: 23b0ba0d-1601-4824-b6c7-7eb3fdc05a91
     .     .  coordinates: [0 0]
     .     -  city.Street cuds object named <Entities>:
     .        uuid: b69d40d0-b919-4df8-8334-b898e4beda83
     .        coordinates: [0 0]
     -  city.Neighborhood cuds object named <User cases>:
        uuid: 79a214f6-4eb1-4a3b-8908-306129583da1
        coordinates: [0 0]

Cuds2Dot

Location: from osp.core.utils import Cuds2dot.

Usage: Cuds2dot(cuds_object).render()

Behaviour:

  • Each entity is represented by a node.

  • The relationships are the edges connecting them.

  • The attributes, uuid and oclass are written inside the nodes.

Example:

>>> Cuds2dot(emmo_town).render()

_images/cuds2dot.png

Ontology2Dot

Location: console entry point osp.core.tools.ontology2dot.

Usage: ontology2dot

Behaviour:

  • Each ontology entity is represented by a box.

  • Attributes and their default values are stated.

  • Inheritance of entities is shown via is_a.

  • The inverse of each relationship is also represented.

Example:

ontology2dot osp/core/ontology/yml/ontology.city.yml

_images/ontology2dot.png

Serialization JSON schema of CUDS objects

When you serialize a CUDS object using the serialize() method in the utils module, you will get a json document as a result. The method will traverse the hierarchical datastructure using Depth First Traversal. Therefore, its result is a json array composed of several flat CUDS objects.

This array can later be deserialized using the opposite deserialize.

The serialization is done via JSON-LD, with the schema used for the OSP API in Marketplace.