POINT_CREATE_LINK_PATTERN_MATCH Operation

This operation uses a set of rules to determine which existing objects (locations/equipment etc) to link the Points in the data pool to.

Locations and equipment, to link the Points to, must already exist in models, either through a previous Create operation or via a supplied input turtle file.

This operation does not make any assessment of the classes and properties of the Points in the data pool, rather it identifies what to link them to. See Point Classifier UI for details of point classification.

Manifest Configuration

The configuration in the manifest file for the Point create link pattern match operation has two parameters - the name of two or more input CSVs - a list of point_list.csv files and a point_linkage.csv file. The tool will look in the input_csvs folder for the named csv files. It is specified as:

{
    "operation_type": "POINT_CREATE_LINK_PATTERN_MATCH",
    "config": {
        "point_linkage_file": "point_linkage.csv",
        "point_list_files": ["point_list.csv"]
    }
}

The Points list CSV(s) is/are a list of Point identifiers to include within the model. This may be generated by gathering all point identifiers from a datapool.

The Point linkage CSV is a two-column csv. Column 1 is a list of the names of existing entities within your model that you want to associate Points with and column 2 is the text pattern (or patterns) that are to be used to match point IDs from the points list to those equipment/locations.

Whilst it is not a requirement, to aid readability, the first column of the Point linkage CSV can be a duplicate of the first column of the objects.csv file. Row ordering in the Point linkage CSV is important (unlike with the objects.csv file), so sometimes this is not possible (see example 3 below).

Points List

The Points list CSV contains no header row and the first column is a list of candidate Point identifiers the generation tool will use when attempting to link these points to existing equipment or locations. Row ordering in this file is not important.

Point Linkage

The Point linkage CSV contains two columns with a header row:

  • Model_ID|Entity_Name: The first column is a list of entity identifiers for locations and equipment from the objects CSV that points may get linked to. These identifiers have the same format that is used in both the CREATE and RELATE operations.

  • Point_Expression: this column contains one or more comma-separated text patterns used to find Point identifiers declared in the points list CSV. Row order in this file is important, as explained below in examples 3a & 3b. Regular Expressions are not supported, however these patterns can include file-system style wildcards (?,*). Patterns starting with a ! character denote that a Point may be linked to multiple entities another valid rule is found to apply.

Creating and Linking Points

This operation takes an existing model, with locations and equipment etc already declared in it, and:

  1. Creates a 'Points list' from the list of point_list.csv

  2. Runs through the rows of the point_linkage.csv, and, for each row (which consists of a 'named entity', and 'patterns'):

    1. Finds all the 'Point IDs in the 'Points list' that match the 'patterns', and for each of them:

      1. links the Point from the data pool to the 'named thing' by adding a brick:isPointOf relationship to that Point declaration. (Note the 'named thing' must already exist, it will not get created, and if it does not exist, the point declaration will not be created.)

      2. usually (but not always - based on a flag in the 'patterns') remove that Point ID from the 'Points list' so it is not available to be subsequently matched by latter rows/patterns in the point_linkage.csv.

Outputs

As per the other operations the tool produces a log file that contains information about how the operation went. Also, to provide feedback on the pattern matching results, the tool produces a point_linkage_point_create_link_pattern_match_operation_report.csv report. This report gives details of which rule in the linkage file (pattern or line) matched with which Point IDs. This documentation does not describe the contents of this report, but it should be consulted to validate expected results or debug potential issues.

Notes on examples

Unless otherwise noted, all the examples below use the following manifest file. Also, as the POINT_CREATE_LINK_PATTERN_MATCH operation links points to existing things, the first operations in the manifest are a CREATE operation (using the objects.csv below) and a RELATE operation (using skeleton.csv below). In addition, to simplify the examples the same points_list.csv file is used for all. The various examples show the results you get as you provide different point_linkage.csv files to the Point create link pattern match operation.

manifest.json

{
  "manifest_version": "1.0.0",
  "id_mapping": {
    "bld": "dch:org/documentation/site/Link_Eg1/building/building_eg1#",
    "DATA": "dch:org/documentation/datapool/data#"
  },
  "operations": [
    {
      "operation_type": "CREATE",
      "config": {
        "object_file": "objects.csv"
      }
    },
    {
      "operation_type": "RELATE",
      "config": {
        "skeleton_file": "skeleton.csv"
      }
    },
    {
      "operation_type": "POINT_CREATE_LINK_PATTERN_MATCH",
      "config": {
        "point_linkage_file": "point_linkage.csv",
        "point_list_files": ["point_list.csv"]
      }
    }
  ]
}

The data pool URI path can be found in the Data Source page. Navigate to your data source on DCH and replace "data" in the manifest with the Datapool ID. The general format of the Datapool ID is managed_datapool_${name_of_datasource}_${uid}.

objects.csv

Model_ID|Entity_Name
Class

bld|Example_building

Building

bld|Level1

Floor

bld|F1

HVAC_Zone

bld|OafF1

Fresh_Air_Fan

bld|AHU_F1_SupplyFan

Supply_Fan

bld|AHU_F1_CHWCoil

Cooling_Coil

bld|AHU_F1_HHWCoil

Heating_Coil

bld|AHU_F1_ReturnDamper

Return_Damper

bld|AHU_F1_OutsideDamper

Outside_Damper

bld|AHU_F1_Filter

Filter

bld|AHU_F1_ClgVlv

Cooling_Valve

bld|AHU_F1_HtgVlv

Heating_Valve

bld|AHU_F1

Air_Handler_Unit

bld|CHWP1

Chilled_Water_Pump

bld|Chiller1

Chiller

bld|HHWP1

Hot_Water_Pump

bld|Boiler1

Boiler

skeleton.csv

Building, hasPart, B
HVAC Zone, isFedBy, C
Air Handler Unit, feeds, B
Fresh Air Fan, feeds, A
Air Handler Unit, hasLocation, A
Supply Fan, isPartOf, E
Cooling Coil, isPartOf, E
Heating Coil, isPartOf, E
Return Damper, isPartOf, E
Outside Damper, isPartOf, E
Filter, isPartOf, E
Cooling Valve, isPartOf, E
Heating Valve, isPartOf, E
Chilled Water Pump, feeds, P
Hot Water Pump, feeds, Q
Cooling Valve, feeds, R
Heating Valve, feeds, S
Cooling Coil, feeds, T
Heating Coil, feeds, U
Chiller, feeds, N
Boiler, feeds, O

bld|Example_building

bld|AHU_F1

bld|AHU_F1_SupplyFan

bld|AHU_F1_CHWCoil

bld|AHU_F1_HHWCoil

bld|AHU_F1_ReturnDamper

bld|AHU_F1_OutsideDamper

bld|AHU_F1_Filter

bld|AHU_F1_ClgVlv

bld|AHU_F1_HtgVlv

bld|CHWP1

bld|HHWP1

bld|AHU_F1_ClgVlv

bld|AHU_F1_HtgVlv

bld|AHU_F1_CHWCoil

bld|AHU_F1_HHWCoil

bld|Chiller1

bld|Boiler1

bld|Example_building

bld|OafF1

bld|Example_building

bld|OafF1

bld|Example_building

bld|F1

bld|AHU_F1

points_list.csv

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_AhrPbAct.In

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_AhrPbAct.Out

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_AhrPbAct.Reset

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_ClgVlv

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_EcoEnb

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_Enb

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_FilDpStp

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_FiltDpr

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_HtgVlv

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_MaSatStp

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_MaxDmdEn

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_MinSatStp

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_OaDmp

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_OatMaxSp

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_OatMinSp

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_OccClgSp

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_OccDb

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_OccHtgSp

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_Pb

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_PosMinOa

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_RaDmp

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_RmSp

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_Sat

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_Sts

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_Tmp

dch:org/documentation/datapool/data#Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_vOAT

dch:org/documentation/datapool/data#Example_building.ChilledWaterSystem_CHW.Chw_Bldg101_Lvl1_Chwp_ChwpAlm

dch:org/documentation/datapool/data#Example_building.ChilledWaterSystem_CHW.Chw_Bldg101_Lvl1_Chwp_Enb

dch:org/documentation/datapool/data#Example_building.HeatingHotWaterSystem_HHW.Hhw_Bldg101_Lvl1_Hhwp_Enb

dch:org/documentation/datapool/data#Example_building.HeatingHotWaterSystem_HHW.Hhw_Bldg101_Lvl1_Hhwp_Sts

dch:org/documentation/datapool/data#bom_gov_au.94870.air.air_temp

Example 1: Basic full point ID matching


It is possible to use the full Point IDs as the patterns in the point linkage file. This does not leverage the pattern matching power of the tool but does provide a way to directly specify which Points should be created and linked up. This gives a base example of such usage.

Inputs

point_linkage.csv

Model_ID|Entity_Name
Point_Expression

bld|Example_building

bom_gov_au.94870.air.air_temp

bld|Level1

bld|F1

bld|AHU_F1

Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_Tmp, Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_RmSp

bld|OafF1

Example_building.AHUCommon_Lvl1.Hvac_Bldg307_Lvl1_OafF1_Enb, Example_building.AHUCommon_Lvl1.Hvac_Bldg307_Lvl1_OafF1_HiSpd, Example_building.AHUCommon_Lvl1.Hvac_Bldg307_Lvl1_OafF1_Sts

bld|AHU_F1_SupplyFan

bld|AHU_F1_CHWCoil

bld|AHU_F1_HHWCoil

bld|AHU_F1_ReturnDamper

Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_RaDmp

bld|AHU_F1_OutsideDamper

Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_OaDmp, Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_OatMaxSp, Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_OatMinSp, Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_vOAT, Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_PosMinOa

bld|AHU_F1_Filter

Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_FilDpStp, Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_FiltDpr

bld|AHU_F1_ClgVlv

Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_ClgVlv

bld|AHU_F1_HtgVlv

Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_HtgVlv

bld|CHWP1

Example_building.ChilledWaterSystem_CHW.Chw_Bldg101_LvlB_Chwp_ChwpAlm, Example_building.ChilledWaterSystem_CHW.Chw_Bldg101_LvlB_Chwp_Enb

bld|Chiller1

bld|HHWP1

Example_building.HeatingHotWaterSystem_HHW.Hhw_Bldg101_LvlB_Hhwp_Enb, Example_building.HeatingHotWaterSystem_HHW.Hhw_Bldg101_LvlB_Hhwp_Sts

bld|Boiler1

LINK Example: Full input archive

Outputs

The full turtle output is in the above for download. Below is a section of the TTL file created to highlight how basic usage of the operation.

Considering the bld|AHU_F1 row of the linkage file, you can see that there are two Point IDs listed (comma separated) in the Point_Expression column. These Point IDs match exactly Point IDs provided in the point_list.csv file. When the operation executes this line of the linkage.csv produces the following triples in the turtle output file:

bld:AHU_F1 a brick:Air_Handler_Unit ;
    brick:hasLocation bld:Example_building ;
    brick:hasPoint DATA:Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_RmSp,
        DATA:Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_Tmp .

Notes:

  • You can see that the points themselves are not declared or classified yet. However, the TTL can still refer to them using the data pool URI (DATA)

  • Each created Point is linked to the target entity brick:isPointOf bld:AHU_F1

LINK Example: Full output archive

Last updated