RELATE Operation

The RELATE operation is used to create relationships between existing things in the models such as hasLocation, or feeds.

Manifest Configuration

The configuration in the manifest file for the Relate operation has one parameter - the name of the skeleton input csv. The tool will look in the input_csvs folder for the named csv file. It is specified as:

        {
            "operation_type": "RELATE",
            "config": {
                "skeleton_file": "skeleton.csv"
            }
        }

Skeleton

The CSV file used with the RELATE operation is referred to as the skeleton csv file.

This file works on the principle that entities within a row get related to other entities within the same row based on relationship details in the column headers. Relationships constructed in this way can represent many-to-many relationships across entities. Entities are identified in the same format as used within the CREATE operation (Model_ID|Entity_Name).

Due to the complexity of modelling a full set of relationships between entities within a site or building, consideration of breaking the skeleton CSV into multiple files is supported and recommended where possible.

Examples

Unless otherwise noted, all the examples below use the following manifest file.

manifest.json

{
  "manifest_version": "1.0.0",
  "id_mapping": {
    "bld": "dch:org/documentation/site/Relate_Eg1/building/building_eg1#"
  },
  "operations": [
    {
      "operation_type": "CREATE",
      "config": {
        "object_file": "objects.csv"
      }
    },
    {
      "operation_type": "RELATE",
      "config": {
        "skeleton_file": "skeleton.csv"
      }
    }
  ]
}

As the relate operation relates existing entities, the first operation in the manifest is a create operation (using the input_csvs/objects.csv also below). The various examples show the tool outputs as you provide different skeleton.csv files to the relate operation.

input_csvs/objects.csv

Model_ID|Entity_Name

Class

bld|test_building

Building

bld|maintenance

Room

bld|library

Library

bld|meter

Electrical_Meter

bld|fan

Fan

bld|power

Power_Sensor

bld|speed

Speed_Sensor

Example 1: Basic skeleton file

Each column header contains two required pieces of information and one optional description to aid readability. The mandatory information is the desired Brick relationship and a reference to the target column. By extending the csv with new columns and new rows there is no limit to the set of desired relationships that can be described between objects in a model.

Target column references are 'zero indexed' i.e the first column is referred to as column 0. To assist users the tool also recognises Excel-style column references, i.e. the first column can alternatively be referred to as column "A"

Inputs

skeleton.csv (table below is shown with Excel style column and row numbering, but contents of the csv header row use numeric column references):

hasPart, 1

isPartOf, 0

hasLocation, 1

hasPoint, 4

isPointOf, 3

bld|test_building

bld|maintenance

bld|meter, bld|fan

bld|meter

bld|power

bld|test_building

bld|library

bld|fan

bld|speed

Understanding this skeleton file cell by cell:

Cell A2: According to the header in the Skeleton, the column A hasPart, 1, (cell A2) is defines in the cell bld|test_building (which is a Brick Building if you look at the objects.csv file) hasPart whatever is on the same row but in the column indexed by 1. In this case, because of the zero indexing of columns, column 1 refers to column B in the above table. Cell B2 is the room "bld|maintenance. So cell A2 defines the relationship of the entity bld|test_building with a relation of brick:hasPart to the other entity bld|maintenance. In the resulting building model this would be represented as: bld:test_building brick:hasPart bld:maintenance .
Cell A3: using the same logic as Cell A2, this defines the relationship: bld|test_building brick:hasPart bld|library .
Cell B2: The header in column B is isPartOf, 0, so Cell B2 defines the relationship bld|maintenance relates to bld|test_building as an isPartOf relation. In the generated model, this will be represented as: bld|maintenance brick:isPartOf bld:test_building .
Cell B3: similarly, create relationship: bld|library brick:isPartOf bld|test_building .
Cell C2: This shows how comma-separated lists can be used in a cell to relate multiple relationships to things at once. Column Header for column C is hasLocation, 1, so cell C2 says say both the meter and the fan are in the maintenance room i.e. create both of these relationships:
- bld|meter brick:hasLocation bld|maintenance .
- bld|fan brick:hasLocation bld|maintenance .

The "target" cell of a relationship can also include a list of things.

Cell D2: Following the same pattern, the header of hasPoint, 4 asks for the triple bld|meter brick:hasPoint bld|power .
Cell D3: similarly bld|fan brick:hasPoint bld|speed .
Cell E2: this generates the reverse link bld|power brick:isPointOf bld|meter .
Cell E3: this generates the link bld|speed brick:isPointOf bld|fan .

The reverse links are not created for you in this tool. e.g. looking at cells C2 and B2, the relationships bld|maintenance brick:isLocationOf bld|meter and bld|maintenance brick:isLocationOf bld|fan are not automatically created. If these relationships are desired, the relationships need to be explicitly described in the skeleton CSV by using another column.

However, note when loading models into DCH, such reverse links are automatically created (the BRICK ontology handles it). So it is not necessary to create them, however it is wise to check if other external tools you may want to use, do correctly inference those reverse links.

Outputs

Zipping up the manifest, with a input_csvs folder containing both the objects.csv file and the skeleton.csv file and and running that through the tool will produce the following turtle output file, which contains all those triples:

bld.ttl

@prefix bld: <dch:org/documentation/site/Relate_Eg1/building/building_eg1#> .
@prefix brick: <https://brickschema.org/schema/Brick#> .

bld:fan a brick:Fan ;
    brick:hasLocation bld:maintenance ;
    brick:hasPoint bld:speed .

bld:library a brick:Library ;
    brick:isPartOf bld:test_building .

bld:meter a brick:Electrical_Meter ;
    brick:hasLocation bld:maintenance ;
    brick:hasPoint bld:power .

bld:power a brick:Power_Sensor ;
    brick:isPointOf bld:meter .

bld:speed a brick:Speed_Sensor ;
    brick:isPointOf bld:fan .

bld:test_building a brick:Building ;
    brick:hasPart bld:library,
        bld:maintenance ;
    brick:keyValue [ brick:key "mgtool" ;
            brick:value "build date: 2024-04-08" ],
        [ brick:key "mgtool" ;
            brick:value "version: 2.0" ] .

bld:maintenance a brick:Room ;
    brick:isPartOf bld:test_building .

Example 4: Commenting out columns

As the skeleton CSVs can become complex the model generation tooling offers a way of commenting out/omitting columns. Starting a description in a column header with a # character means that the relationships for that column won't be made. Important to note though, is that relationships in other columns that reference things in the column will still be made.

Inputs

skeleton.csv

#, hasPart, B

the_rooms, isPartOf, A

the_equipment, hasLocation, B

hasPoint, E

#the_points, isPointOf, D

bld|test_building

bld|maintenance

bld|meter,bld|fan

bld|meter

bld|power

bld|test_building

bld|library

bld|fan

bld|speed

Outputs

The tool produces the following model output file, which contains fewer relationships than in the previous examples:

bld.ttl

@prefix bld: <dch:org/documentation/site/Relate_Eg4/building/building_eg4#> .
@prefix brick: <https://brickschema.org/schema/Brick#> .

bld:fan a brick:Fan ;
    brick:hasLocation bld:maintenance ;
    brick:hasPoint bld:speed .

bld:library a brick:Library ;
    brick:isPartOf bld:test_building .

bld:meter a brick:Electrical_Meter ;
    brick:hasLocation bld:maintenance ;
    brick:hasPoint bld:power .

bld:power a brick:Power_Sensor .

bld:speed a brick:Speed_Sensor .

bld:maintenance a brick:Room ;
    brick:isPartOf bld:test_building .

bld:test_building a brick:Building ;
    brick:keyValue [ brick:key "mgtool" ;
            brick:value "build date: 2024-04-08" ],
        [ brick:key "mgtool" ;
            brick:value "version: 2.0" ] .

Specifically note the building no longer has hasPart relationships to the rooms as the hasPart column is commented, but the rooms are still part of the building - i.e references to things in commented columns are still made, but the relationships from things in the commented columns are not made. Similarly the points no longer have the isPointOf relationships to the equipment but the equipment still has the hasPoint relationships to the points.

Example 5: Splitting the skeleton csv up for readability

As the skeleton files can become both very wide and very long they can be difficult to comprehend. It is highly recommended you split up the skeleton files into multiple files to help with comprehension. e.g., you may have one skeleton file that describes the hasPart relationships between all the locations, and another that covers the same relationship for equipment and another for the feeds relationship, etc.

This example splits the skeleton csv up into three separate files. How to split files up is an arbitrary choice but in this instance one csv declares the relationships between locations and other locations, one csv declares the relationships between equipment and locations and one that declares the relationships concerning points. To produce the full model the Relate operation needs to be run three times, once with each skeleton csv file i.e. declared three times in the manifest:

Inputs

manifest.json

{
  "manifest_version": "1.0.0",
  "id_mapping": {
    "bld": "dch:org/documentation/site/Relate_Eg5/building/building_eg5#"
  },
  "operations": [
    {
      "operation_type": "CREATE",
      "config": {
        "object_file": "objects.csv"
      }
    },
    {
      "operation_type": "RELATE",
      "config": {
        "skeleton_file": "skeleton_locations.csv"
      }
    },
    {
      "operation_type": "RELATE",
      "config": {
        "skeleton_file": "skeleton_equipment.csv"
      }
    },
    {
      "operation_type": "RELATE",
      "config": {
        "skeleton_file": "skeleton_points.csv"
      }
    }
  ]
}

input_csvs/skeleton_locations.csv

hasPart, B

isPartOf, A

bld|test_building

bld|maintenance

bld|test_building

bld|library

input_csvs/skeleton_equipment.csv

#, isLocationOf, B

hasLocation, A

bld|maintenance

bld|meter, bld|fan

input_csvs/skeleton_points.csv

hasPoint, B

isPointOf, A

bld|meter

bld|power

bld|fan

bld|speed

Outputs

The tool results in the same outputs as examples 1-3, demonstrating that splitting the skeleton CSV into multiple files is an effective way to divide your model without impacting on the quality of the model.

Note the commented column A in skeleton_equipment.csv is to make the output identical to the previous examples. It is not required, and if omitted the output Turtle file will include the extra reverse isLocationOf triple.

PreviousCREATE Operation NextPOINT_CREATE_LINK_PATTERN_MATCH Operation

Last updated 1 year ago

RELATE Operation

Manifest Configuration

Skeleton

Examples

Example 1: Basic skeleton file

Inputs

Outputs

Example 2: Alphabetic column references

Inputs

Example 3: Optional column descriptors

Inputs

Outputs

Example 4: Commenting out columns

Inputs

Outputs

Example 5: Splitting the skeleton csv up for readability

Inputs