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

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

2KB

Link_Eg1.zip

archive

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

2KB

generated-Link_Eg1.zip

archive

LINK Example: Full output archive

Example 2

Example 2: typical pattern matching

---

This example shows how to create and link multiple Points to one piece of equipment using the pattern matching features. This produces the same TTL file as Example 1; all input files are the same as Example 1, except the point_linkage.csv file.

Inputs

point_linkage.csv

Model_ID|Entity_Name	Point_Expression
bld|Example_building	bom
bld|Level1
bld|F1
bld|AHU_F1	AhuF1_Tmp, AhuF1_RmSp
bld|OafF1	OafF1
bld|AHU_F1_SupplyFan
bld|AHU_F1_CHWCoil
bld|AHU_F1_HHWCoil
bld|AHU_F1_ReturnDamper	AhuF1_RaDmp
bld|AHU_F1_OutsideDamper	AhuF1_OaDmp, AhuF1_OatMaxSp, AhuF1_OatMinSp, AhuF1_PosMinOa, AhuF1_vOAT
bld|AHU_F1_Filter	AhuF1_FilDpStp, AhuF1_FiltDpr
bld|AHU_F1_ClgVlv	AhuF1_ClgVlv
bld|AHU_F1_HtgVlv	AhuF1_HtgVlv
bld|CHWP1	Chwp
bld|Chiller1
bld|HHWP1	Hhwp
bld|Boiler1

2KB

Link_Eg2.zip

archive

LINK Example 3: Full input archive

---

Outputs

A better example of this is to look at the bld|OafF1 row. We now only have one pattern specified in the point_linkage.csv file - "OafF1". When processing the bld|OafF1 row the tool still looks at all Point IDs for ones that contain the "OafF1" pattern, it finds three so it creates and links up three Points, like with the previous example, where the three Points were individually specified.

2KB

generated-Link_Eg2.zip

archive

LINK Example 3: Full output archive

Example 3

Example 3a: Ordering and linking points to multiple equipment and locations

---

This example shows how to link a created Point to multiple pieces of equipment or locations by keeping the point in the Points list for reuse/subsequent matching.

Firstly, for Example 3a please consider the following linkage csv, which is the same as Examples 1 & 2 except we've tried to add the temperature sensor as a Point of the floor level 1 (as well as to the AHU like it has been in the previous examples).

Inputs

point_linkage.csv

Model_ID|Entity_Name	Point_Expression
bld|Example_building	bom
bld|Level1	AhuF1_Tmp
bld|F1
bld|AHU_F1	AhuF1_Tmp, AhuF1_RmSp
bld|OafF1	OafF1
bld|AHU_F1_SupplyFan
bld|AHU_F1_CHWCoil
bld|AHU_F1_HHWCoil
bld|AHU_F1_ReturnDamper	AhuF1_RaDmp
bld|AHU_F1_OutsideDamper	AhuF1_OaDmp, AhuF1_OatMaxSp, AhuF1_OatMinSp, AhuF1_PosMinOa, AhuF1_vOAT
bld|AHU_F1_Filter	AhuF1_FilDpStp, AhuF1_FiltDpr
bld|AHU_F1_ClgVlv	AhuF1_ClgVlv
bld|AHU_F1_HtgVlv	AhuF1_HtgVlv
bld|CHWP1	Chwp
bld|Chiller1
bld|HHWP1	Hhwp
bld|Boiler1

2KB

Link_Eg3a.zip

archive

LINK Example 3a: Full input archive

---

Outputs

You may find the result unexpected. The point is made a Point of the room but it is no longer a Point of the AHU. e.g.:

bld:Level1 a brick:Floor ;
    brick:hasPoint DATA:Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_Tmp .

This behaviour is deliberate to add flexibility to the Point linkage operation. Once a point ID is matched and used by a rule (a row in the Point linkage CSV file) it is no longer available to be matched by subsequent rules. This assists in making complex sets of matching rules. However to cater for the use case above where we do want the Point to be linked to both Level 1 and the AHU we introduce a flag that we can add to the pattern which indicates to leave this Point as a candidate in the list of Points so it is available to be matched by subsequent rules. This flag is an exclamation point (!) and is used as a prefix in the pattern.

2KB

generated-Link_Eg3a.zip

archive

LINK Example 3a: Full output archive

---

Example 3b: Utilising the multiple-match flag

Inputs

point_linkage.csv

Model_ID|Entity_Name	Point_Expression
bld|Example_building	bom
bld|Level1	!AhuF1_Tmp
bld|F1
bld|AHU_F1	AhuF1_Tmp, AhuF1_RmSp
bld|OafF1	OafF1
bld|AHU_F1_SupplyFan
bld|AHU_F1_CHWCoil
bld|AHU_F1_HHWCoil
bld|AHU_F1_ReturnDamper	AhuF1_RaDmp
bld|AHU_F1_OutsideDamper	AhuF1_OaDmp, AhuF1_OatMaxSp, AhuF1_OatMinSp, AhuF1_PosMinOa, AhuF1_vOAT
bld|AHU_F1_Filter	AhuF1_FilDpStp, AhuF1_FiltDpr
bld|AHU_F1_ClgVlv	AhuF1_ClgVlv
bld|AHU_F1_HtgVlv	AhuF1_HtgVlv
bld|CHWP1	Chwp
bld|Chiller1
bld|HHWP1	Hhwp
bld|Boiler1

2KB

Link_Eg3b.zip

archive

LINK Example 3b: Full input archive

---

Outputs

In this case you can see the tool links the Point to both the AHU and the floor:

bld:Level1 a brick:Floor ;
    brick:hasPoint DATA:Example_building.AHU_F1.Hvac_Bldg101_Lvl1_AhuF1_Tmp .

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 .

2KB

generated-Link_Eg3b.zip

archive

LINK Example 3b: Full output archive

Example 4

Example 4: wildcard use

---

This example highlights the use of a further functions of the tool. Even though it has not been utilised in the previous examples the patterns specified in the Point linkage CSV can use traditional file system wild cards * and ?.

The following Point linkage CSV utilises these features. Note the ordering of this line (the last rule in the CSV) is important.

Inputs

point_linkage.csv

Model_ID|Entity_Name	Point_Expression
bld|Example_building	bom
bld|Level1	!AhuF1_Tmp
bld|F1
bld|AHU_F1	AhuF1_Tmp, AhuF1_RmSp
bld|OafF1	OafF1
bld|AHU_F1_SupplyFan
bld|AHU_F1_CHWCoil
bld|AHU_F1_HHWCoil
bld|AHU_F1_ReturnDamper	AhuF1_RaDmp
bld|AHU_F1_OutsideDamper	AhuF1_OaDmp, AhuF1_Oat*Sp, AhuF1_PosMinOa, AhuF1_vOAT
bld|AHU_F1_Filter	AhuF1_FilDpStp, AhuF1_FiltDpr
bld|AHU_F1_ClgVlv	AhuF1_ClgVlv
bld|AHU_F1_HtgVlv	AhuF1_HtgVlv
bld|CHWP1	Chwp
bld|Chiller1
bld|HHWP1	Hhwp
bld|Boiler1

2KB

Link_Eg4.zip

archive

LINK Example 4: Full input archive

---

Outputs

You can see the Outside Air Temperature (OAT) max and min set-points are still found and linked as per the previous examples.

2KB

generated-Link_Eg4.zip

archive

LINK Example 4: Full output archive