Introduction to telicent-ies-tool

telicent-ies-tool is an open source Python library for creating RDF using IES4 ontology. telicent-ies-tool. It simplifies the process of creation by abstracting much of the ontology’s complexity into straightforward classes and methods.

Installation

pip install telicent-ies-tool

Usage

Setup

The IES Tool provides a central factory class, IESTool, instantiations of which provide a container for the RDF graph you will be generating. A default instance of this tool is automatically created as the IES_TOOL constant, which can be imported directly.

import ies_tool.ies_tool as ies

You must initialize a separate IESTool instance for each RDF graph you intend to work with.

ies_tool = ies.IESTool()

Instantiating IES4 classes

The library includes base Python classes representing all major IES4 classes. These are known as base classes-the hierarchy of which is shown below:

The Base Class Hierarchy

RdfsResource
│
├── RdfsClass
│   ├── ClassOfElement
│   └── ClassOfClassOfElement
│
├── Thing
│   ├── Element
│   │   ├── Entity
│   │   │   ├── Asset
│   │   │   │   ├── AmountOfMoney
│   │   │   │   └── Device
│   │   │   ├── Account
│   │   │   │   └── CommunicationsAccount
│   │   │   ├── Location
│   │   │   │   ├── Country
│   │   │   │   └── GeoPoint
│   │   │   └── ResponsibleActor
│   │   │       ├── Person
│   │   │       ├── Organisation
│   │   │       └── Post
│   │   ├── State
│   │   │   ├── DeviceState
│   │   │   ├── AssetState
│   │   │   ├── AccountState
│   │   │   ├── CommunicationsAccountState
│   │   │   ├── BoundingState
│   │   │   │   ├── BirthState
│   │   │   │   └── DeathState
│   │   │   └── EventParticipant
│   │   ├── Event
│   │   │   ├── Communication
│   │   │   └── PartyInCommunication
│   │   └── ParticularPeriod
│   ├── Representation
│   │   ├── Identifier
│   │   ├── Name
│   │   ├── WorkOfDocumentation
│   │   └── MeasureValue
│   ├── Measure
│   └── NamingScheme

Each of these classes can be instantiated using the typical Pythonic approach - e.g.

anne = Person(tool=ies_tool, given_name="Anne", surname="Smith")

One of the key benefits of using telicent-ies-tool, as demonstrated here, is its ability to automatically generate the n number of triples required for specific IES4 patterns using simple, easy-to-understand methods. For example, the code snippet above produces the following triples:

# Resultant graph using turtle syntax
data:2adfe3f51fb9483fa99a2664576d6dfd_000001 a ies:Person ;
    ies:hasName data:2adfe3f51fb9483fa99a2664576d6dfd_000001_GIVENNAME_001,
        data:2adfe3f51fb9483fa99a2664576d6dfd_000001_SURNAME_001 .

data:2adfe3f51fb9483fa99a2664576d6dfd_000001_GIVENNAME_001 a ies:GivenName ;
    ies:representationValue "Anne"^^xsd:string .

data:2adfe3f51fb9483fa99a2664576d6dfd_000001_SURNAME_001 a ies:Surname ;
    ies:representationValue "Smith"^^xsd:string .

Moreover, the triples created by the tool are validated both against the RDF spec. and the IES4 spec. Note telicent-ies-tool, unless otherwise specified, will create random URIs. If we wanted the above person to have a specific URI, then we would make use of the uri argument. Note, the string used for this argument must include the full non-prefix’d namespace.

anne = Person(tool=ies_tool, given_name="Anne", surname="Smith", 
                uri="http://example.com/rdf/testdata#person_022")

…which would update the graph to look like this:

# Resultant graph using turtle syntax
data:person_022 a ies:Person ;
    ies:hasName ies:person_022_GIVENNAME_001,
        ies:person_022_SURNAME_001 .

data:person_022_GIVENNAME_001 a ies:GivenName ;
    ies:representationValue "Anne"^^xsd:string .

data:person_022_SURNAME_001 a ies:Surname ;
    ies:representationValue "Smith"^^xsd:string .

Class-specific methods

All classes have methods associated to them which allow you to add further relationships and details to the objects that you instantiate. E.g. for a Person, we can add further information using methods like add_identifier(), add_state(), in_location(), works_for(), etc. These methods are inherited inline with the IES4 hierarchy. Below are some of the most useful methods available for each base class.

Method	Explanation	Base class
`add_identifier()`	Adds an identifier to the node	`Thing()`
`add_name()`	Adds an IES name to the node	`Thing()`
`create_state()`	Creates a state of this node	`Element()`
`in_location()`	Places the Element in a Location	`Element()`
`put_in_period()`	Puts an item in a particular period	`Element()`
`starts_in()`	Asserts an item started in a particular period	`Element()`
`ends_in()`	Asserts an item ended in a particular period	`Element()`
`add_given_name()`	Adds a GivenName to a Person	`Person()`
`add_surname()`	Adds a Surname to a Person	`Person()`
`add_birth()`	Adds birth state to a Person	`Person()`
`add_death()`	Adds death state to a Person	`Person()`
`add_participant()`	Adds a participant to the Event	`Event()`

Where there is no method for a certain IES4 class you want to instantiate, use the instantiate() method on a IESTool object. For example:

account_1 = ies_tool.instantiate(classes=['http://ies.data.gov.uk/ontology/ies4#FinancialAccount'])

In order for your object to include the appropriate methods for the class you are instantiating, an optional base_class argument is provided with this method. If this is not provided, telicent-ies-tool will attempt to infer it. In the above snippet, the account_1 object is inferred to be an Account object and is returned as such. This includes all the methods associate to the Account class. Generally it is advised that you specify this parameter like below:

account_1 = ies_tool.instantiate(classes=['http://ies.data.gov.uk/ontology/ies4#FinancialAccount'], base_class=ies.Account)

At times you may also need to add specific triples to the graph which are not supported by any of the built-in methods. The add_related_object() method is available on all objects and is useful to relate one object to another specific predicate.

anne.add_related_object("http://ies.data.gov.uk/ontology/ies4#hasAccessTo", account_1)

You can also use the add_triple() method, found on a IESTool object to specify a full triple by providing all three constitutes of a triple. For example:

ies_tool.add_triple(
    subject= anne.uri,
    predicate="http://example.com/my-ontology#sisterOf",
    object= john.uri
)

A optional four boolean parameter, is_literal, is available if the object of your triple is required to be a literal.

Namespaces and prefixes

By default, http://example.com/rdf/testdata# is used as the default namespace for all things added to your graph. This can be changed like so:

ies_tool.add_prefix("data:", "http://example.com/rdf/testdata#")

If you intend to output your graph using an RDF serialization that supports prefixes, it’s worth noting that the default namespace uses a blank prefix (:) by default. You can change this, as well as add new prefixes using add_prefix(). For example:

ies_tool.add_prefix("data:", "http://example.com/rdf/testdata#")

Serializing to RDF

To return RDF as a string in your chosen serialization format, use get_rdf().

my_rdf_string = ies_tool.get_rdf(format="turtle")

To save RDF locally, use save_rdf().

ies_tool.save_rdf("path/to/my/file.ttl", rdf_format="ttl")

Source code and more details

The telicent-ies-tool source code and documentation can be found here