brickschema 0.2.0a3

A library for working with the Brick ontology for buildings (brickschema.org)

Brick Ontology Python package

Documentation available at readthedocs

Installation

The brickschema package requires Python >= 3.6. It can be installed with pip:

pip install brickschema

The brickschema package offers several installation configuration options for reasoning. The default bundled OWLRL reasoner delivers correct results, but exhibits poor performance on large or complex ontologies (we have observed minutes to hours) due to its bruteforce implementation.

The Allegro reasoner has better performance and implements enough of the OWLRL profile to be useful. We execute Allegrograph in a Docker container, which requires the docker package. To install support for the Allegrograph reasoner, use

pip install brickschema[allegro]

The reasonable Reasoner offers even better performance than the Allegro reasoner, but is currently only packaged for Linux platforms. (Note: no fundamental limitations here, just some packaging complexity due to cross-compiling the .so). To install support for the reasonable Reasoner, use

pip install brickschema[reasonable]

Quickstart

Brief overview of the main features of the brickschema package:

import brickschema

# creates a new rdflib.Graph with a recent version of the Brick ontology
# preloaded.
g = brickschema.Graph(load_brick=True)
# OR use the absolute latest Brick:
# g = brickschema.Graph(load_brick_nightly=True)
# OR create from an existing model
# g = brickschema.Graph(load_brick=True).from_haystack(...)

# load in data files from your file system
g.load_file("mbuilding.ttl")
# ...or by URL (using rdflib)
g.parse("https://brickschema.org/ttl/soda_brick.ttl", format="ttl")

# perform reasoning on the graph (edits in-place)
g.expand(profile="owlrl")
g.expand(profile="tag") # infers Brick classes from Brick tags

# perform SPARQL queries on the graph
res = g.query("""SELECT ?afs ?afsp ?vav WHERE  {
    ?afs    a       brick:Air_Flow_Sensor .
    ?afsp   a       brick:Air_Flow_Setpoint .
    ?afs    brick:isPointOf ?vav .
    ?afsp   brick:isPointOf ?vav .
    ?vav    a   brick:VAV
}""")
for row in res:
    print(row)

# start a blocking web server with an interface for performing
# reasoning + querying functions
g.serve("localhost:8080")
# now visit in http://localhost:8080

Features

OWLRL Inference

brickschema makes it easier to employ OWLRL reasoning on your graphs. The package will automatically use the fastest available reasoning implementation for your system:

• reasonable (fastest, Linux-only for now): pip install brickschema[reasonable]
• Allegro (next-fastest, requires Docker): pip install brickschema[allegro]
• OWLRL (default, native Python implementation): pip install brickschema

To use OWL inference, import the OWLRLInferenceSession class (this automatically chooses the fastest reasoner; check out the inference module documentation for how to use a specific reasoner). Create a brickschema.Graph with your ontology rules and instances loaded in and apply the reasoner's session to it:

from brickschema import Graph

g = Graph(load_brick=True)
g.load_file("test.ttl")
g.expand(profile="owlrl")
print(f"Inferred graph has {len(g)} triples")

Haystack Translation

brickschema can produce a Brick model from a JSON export of a Haystack model. Then you can use this package as follows:

import json
from brickschema import Graph
g = Graph(load_brick=True).from_haystack("http://project-haystack.org/carytown#", model)
points = g.query("""SELECT ?point ?type WHERE {
    ?point rdf:type/rdfs:subClassOf* brick:Point .
    ?point rdf:type ?type
}""")
print(points)

VBIS Translation

brickschema can add VBIS tags to a Brick model easily

from brickschema import Graph
g = Graph(load_brick=True)
g.load_file("mybuilding.ttl")
g.expand(profile="vbis")

vbis_tags = g.query("""SELECT ?equip ?vbistag WHERE {
    ?equip  <https://brickschema.org/schema/1.1/Brick/alignments/vbis#hasVBISTag> ?vbistag
}""")

Web-based Interaction

brickschema now supports interacting with a Graph object in a web browser. Executing g.serve(<http address>) on a graph object from your Python script or interpreter will start a webserver listening (by default) at http://localhost:8080 . This uses Yasgui to provide a simple web interface supporting SPARQL queries and inference.

Brick model validation

The module utilizes the pySHACL package to validate a building ontology against the Brick Schema, its default constraints (shapes) and user provided shapes.

from brickschema import Graph

g = Graph(load_brick=True)
g.load_file('myBuilding.ttl')
valid, _, _ = g.validate()
print(f"Graph is valid? {valid}")

# validating using externally-defined shapes
external = Graph()
external.load_file("other_shapes.ttl")
valid, _, _ = g.validate(shape_graphs=[external])
print(f"Graph is valid? {valid}")

The module provides a command brick_validate similar to the pyshacl command. The following command is functionally equivalent to the code above.

brick_validate myBuilding.ttl -s other_shapes.ttl

Development

Brick requires Python >= 3.6. We use pre-commit hooks to automatically run code formatters and style checkers when you commit.

Use Poetry to manage packaging and dependencies. After installing poetry, install dependencies with:

# -D flag installs development dependencies
poetry install -D

Enter the development environment with the following command (this is analogous to activating a virtual environment.

poetry shell

On first setup, make sure to install the pre-commit hooks for running the formatting and linting tools:

# from within the environment; e.g. after running 'poetry shell'
pre-commit install

Run tests to make sure build is not broken

# from within the environment; e.g. after running 'poetry shell'
make test

Docs

Docs are written in reStructured Text. Make sure that you add your package requirements to docs/requirements.txt