OWFgraph Tutorial

Erik Quaeghebeur

2017-02-13

OWFgraph is a graph database for the off-shore wind farm domain. It is an open-ended project that has currently sufficiently been developed to present it to the public for exploration and feedback purposes.

OWFgraph describes both physical objects and their attributes, as well as mathematical models, including computational tools, and their variables. Moreover, also procedures can be described. (Furthermore, phenomena are also allowed for, but this is currently not used.)

The above concepts, instances of which are represented as nodes in the database, can be described using labels and properties and linked by relationships to describe their connections.

This document is meant to help people use OWFgraph's web interface to explore the database. It is not meant to elaborate on the contents or uses of the database. I will revise and update this tutorial based on user feedback, so please let me know what would make this tutorial more useful to you.

Accessing the Database

You will arrive at the interface after giving the correct username and password. (Contact me in case you do not know the username or password.)

What you see will look more-or-less like the image below.

The OWFgraph web interface.

You can see that we are using Neo4j as our graph database software. At the time of writing, we are running version 3.0; we may upgrade as upgrades become available, but this should not impact this tutorial.

This is a read-only version of the database, so it will not be possible to add, update, or delete content. This means you should not worry about doing something ‘wrong’ while exploring.

Getting Familiar with Neo4j

The starting screen presents you with a link ‘Start Learning’; please click it and go over the basic graph database concepts explained in the slides until you hit the ‘Next steps’ slide. There, click ‘Intro’ to get a high level overview of the web interface. Finally, click ‘Cypher’ to learn about the query language used to interact with Neo4j database instances, i.e., to create, read (view), update, and delete content.

Once you are familiar with the graph database concepts and the web interface, you can start exploring OWFgraph. Do not worry too much about familiarity with the query language Cypher: it can be learnt while doing, when you make an effort to understand the queries you come accross. For this purpose, a nice supporting reference to have open is the Cypher Refcard — http://neo4j.com/docs/cypher-refcard/3.0/.

In case you want to know more about Neo4j, or are looking for answers, then the following on-line resources provide good starting points:

OWFgraph's Foundational Ontology

OWFgraph is not just an arbitrary collection of nodes, properties, and relationships. To provide structure that can be relied on when looking for information and doing queries, we have designed a foundational ontology. Namely, we have imposed a basic framework that people adding information need to follow. When exploring the database, it is essential to be aware of this framework, so we discuss it in the remainder of this tutorial.

The foundational ontology

provides a classification of the domain's concepts and relationships,

is small enough to be manageable, but

is large enough to be sufficiently expressive.

Node Types

There are six node types, each of which is implemented as a label. Any node in OWFgraph must have just one of these labels; they may have other labels from outside of this group.

There are four ‘physical’ types (labels). Let us start with the two more concrete ones:

Objects (Object), which represent things in the physical world;

Some objects.

Procedures (Procedure), which represent concrete series of actions that change something in the physical world.

Some procedures.

The two more abstract ones are:

Attributes (Attribute), which conceptually describe aspects of objects or procedures;

Some attributes.

Phenomena (Phenomenon), which represent physical processes that affect attributes (this type is currently not used).

The two ‘mathematical’ types (labels) are:

Variables (Variable), which describe—often quantify—attributes for use in a mathematical context; and

Property Types

author: the name or names of the people who contributed to that node and its relationships (comma-separated list of single word identifiers);

name: a descriptive name that must be unique for the node type, so which acts as a unique identifier (lower case, as short as possible);

description: one or more sentences describing the node and places it within its relationship context (sentences, may be elaborate and, e.g., contain formulas);

reference: one or more sources of information, specified as a URL or as a bibliographic reference;

note: temporary additional comments or questions.

The author, name, and description properties should in principle always be provided. However, for attributes and variables, description may be omitted if name provides enough information. (Currently also some models lack a name.)

Common properties

Variables have some specific properties:

domain: whether it is integer, real, Boolean, etc. (an identifier, one of ‘integer’, ‘real’, ‘bool’, ‘str’ or variations thereof, such as ‘positive real’);

unit: the unit of the variable (omit only if dimensionless);

value: the value of a constant.

Variable properties

Relationship Types

The relationship types allowed between nodes are specific to the node types.

There are two relationship types that are allowed between nodes of the same type:

PART_OF encodes that the begin node is a part of the end node and it is used quite diversely, e.g., in the physical sense, in a decomposition of a sum, etc.;

Some ‘part-of’ relationships.

VARIANT_OF encodes that the begin node is a variant of the end node and again it is used quite diversely, e.g., in the physical sense, but also for connecting similar variables.

Some ‘variant-of’ relationships.

Most other relationships are more node-type specific. The first we consider forms the main bridge between the physical and mathematical node types:

DESCRIBES encodes that the begin node describes some aspect of the end node and must only be used between variables and attributes or attributes and objects or procedures.

Some ‘describes’ relationships.

Attributes that describe objects or procedures directly—so not via a PART_OF-relationship—must be either ‘structure’, ‘state’, or ‘cost’. Also, in principle, the ‘cost’-type attributes only describe procedures, but if the assembly or construction procedure of an object is left implicit, it may be connected directly to that object.

The next set of relationships represent the possible connections between variables and models:

APPEARS_IN encodes that the variable appears in the model without specifying whether it is an input or an output, e.g., because it can take both roles (N.B.: variables internal to models are not normally included in OWFgraph);

INPUT_TO encodes that the variable is a required input to the model;

OUTPUT_TO encodes that the variable is an output of the model.

Some variable relationships.

The latter two relationship types are usually encountered for models that represent computational tools, rather than for, e.g., models corresponding to systems of equations. We actually use a Boolean property output on APPEARS_IN relationships to indicate the typical role of the connected variable in the context of that model (an output when it is true and an input when it is false).

Any procedure always INSTRUCTS an Object, which is typically a crew. We consider three subtypes of procedures that each have their signature relationships:

A maintenance procedure MODIFIES some Object;

A maintenance procedure.

An assembly, installation, or decomissioning procedure is related to objects that are the INPUT_TO and OUTPUT_OF the procedure;

An assembly procedure.

A measurement procedure MEASURES an attribute and a variable is the OUTPUT_OF the procedure (currently, no measurement procedures are present in OWFgraph).

Finally, although we do not have any phenomena in OWFgraph, we do have specifications for how they should be related to two other node types. Namely, for attributes:

APPEARS_IN encodes that an attribute appears in a phenomenon;

CAUSES encodes that an attribute causes a phenomenon;

AFFECTS encodes that a phenomenon affects an attribute;

and for models:

RELATES_TO encodes that a model is related to, e.g., by modeling, a phenomenon.

Given these phenomenon-specific specifications are not tried and tested, they are still prone to change.

Closing Remarks

OWFgraph describes the off-shore wind farm domain and not a generic off-shore wind farm. Nevertheless, it is useful to think about a generic or perhaps concrete off-shore wind farm when working with OWFgraph.

Every possible object is included only once in the database; variants and ‘set of’ variables are used to deal with multiplicities.

Some ‘set of’ variables and their connections.

When reasoning about variables and models, it is useful to know that all variables are instantaneous unless otherwise described. This means that models relate values. Equivalently, those variables can also be regarded as signals (functions of time) over the lifetime of a wind farm.