Usage

Basic description of how to use the tool.

The DCH model construction tool takes a zip file containing a set of Comma Separated Values (CSV) files describing what to create and returns a zip file containing a set of generated model files (in the form of turtle files) along with feedback of the construction process.

To use it you upload a zip file and hit the Generate Model button. Generation of models takes some time, depending on complexity, from seconds or ten's of seconds through to a minute or two. When the tool is finished the web page lets you know and automatically downloads a zip file containing the results. The results can be manually downloaded if the automatic download does not occur.

The tool is available under the Tools menu on the LHS of the DCH Web interface: Tools -> Generate Model(s).

For more info on the tool's REST API endpoints, go here.

Inputs

The provided zip file has some required components as well as some optional components.

Example input archive contents
input_archive.zip
├─ input_csvs/ (*)
│  ├─ objects.csv
│  ├─ skeleton.csv
│  ├─ point_linkage.csv
│  └─ point_list.csv
├─ input_ttls/
│  ├─ site.ttl
│  └─ building.ttl
└─ manifest.json (*)

// (*) denotes required content

Required contents:

  • at the top level in the zip file, you need to have a manifest.json text file.

  • at the top level in the zip file, you need to have a folder called input_csvs with at least one CSV file. In this example, four CSV files have been provided:

    • objects.csv for the CREATE operation

    • skeleton.csv for the RELATE operation, and

    • point_linkage.csv along with point_list.csv for the POINT_CREATE_LINK_PATTERN_MATCH operation

Optional contents:

  • you can provide some starting models (turtle files) in an input_ttls folder. In this example, both site.ttl and building.ttl have been provided as existing models for a site and building respectively. For more information about extending existing models, see the following page:

Advanced: Extending an additional model

The Manifest file

The manifest file is defined within manifest.json, and provides two inputs to the model generation tooling:

  • id_mapping: a mapping from a human-readable identifier of the model to the Universal Resource Identifiers (URIs) to use when constructing models.

  • operations: The set of operations to perform and any configuration parameters for each operation (at a minimum the specific csv file(s) to use as the input to the operation). It is possible to run operations in any order and/or to run the same operation multiple times with different input csvs/configurations). Running an operation multiple times with different input CSVs is a desirable way to prevent the input csv's form getting large and difficult to comprehend.

ID Mapping

As indicated, URIs are used in the turtle files to refer to different models. DCH URIs take the following forms:

<dch:org/[org_id]/site/[site_id]#>                        # URI for a site
<dch:org/[org_id]/site/[site_id]/building/[building_id]#> # URI for a building

To make the input CSVs for the model construction tools as simple and as readable as possible these longer URIs are not used in those files, but rather simpler model_id prefixes are used in the CSVs to identify which models things should be created in.

These prefixes always become the filenames for the output turtle files.

There are two alternate mechanisms used to set the URI that is used for each model_id used in the csv's. The first mechanism is that the manifest file can contain an id_mapping component that instructs the model construction tools how to map the model_id's used in the input csvs to the desired URIs in the output files. The alternative mechanism is based on the optional ability to provide a starting set of models (in turtle format) files to the model construction tool. When that is done, the mapping from model_id to URI can be determined from the contents of the provided turtle file(s) file. If a mapping cannot be derived from either the manifest or a provided input turtle file, then a default URI will be used, and a warning provided.

Do not provide different mappings in the Manifest file and in an input turtle files, as that will cause contention and provide undesired outputs.

It is highly recommended that the id_mapping be provided in the manifest file, as being explicit provides an extra level of quality control over potential typos or mistakes in input csvs.

Note the URI's in the turtle files you supply to DCH when uploading models do not need to be consistent with the exact site and building names of the site and buildings in DCH. The uploading process allows URIs to be remapped on upload, however supplied turtle files do require URIs starting with 'dch:' .

Operations

As indicated, there are three operations that can be performed by the model construction code. Details are in the following sections. You specify which operations to execute in which order along with configuration details in the manifest file. At least one operation must be specified.

In the manifest file the three operations are defined as:

  • CREATE

  • RELATE

  • POINT_CREATE_LINK_PATTERN_MATCH

A full example manifest file that invokes all operations is below. Note the order that operations are specified in the file is the order they get executed. Also operations can be specified multiple times (with different configurations/input files). Ordering is important as some operations require things to already exist in the models (from previous operations):

{
    "manifest_version": "1.0.0",
    "id_mapping": {
        "csiro_hobart_site": "dch:org/csiro/site/csiro_hobart",
        "csiro_hobart_B001": "dch:org/csiro/site/csiro_hobart/building/building001",
        "csiro_hobart_B002": "dch:org/csiro/site/csiro_hobart/building/building002",
        "csiro_hobart_B003": "dch:org/csiro/site/csiro_hobart/building/building003",
        "csiro_hobart_B004": "dch:org/csiro/site/csiro_hobart/building/building004",
        "csiro_hobart_B005": "dch:org/csiro/site/csiro_hobart/building/building005"
    },
    "operations": [
        {
            "operation_type": "CREATE",
            "config": {
                "object_file": "csiro_hobart_objects.csv"
            }
        },
        {
            "operation_type": "RELATE",
            "config": {
                "skeleton_file": "csiro_hobart_skeleton.csv"
            }
        },
        {
            "operation_type": "POINT_CREATE_LINK_PATTERN_MATCH",
            "config": {
                "point_linkage_file": "csiro_hobart_point_linkage.csv",
                "point_list_file": "csiro_hobart_point_list.csv"
            }
        }
    ]
}

Input CSVs

The CSVs used within the input archive will differ depending on which operations are configured for the tool to run. For additional information and input CSV examples can be found within the following pages:

Outputs

The output zip file will contain:

output_archive.zip
├─ mgtool.log (*)
├─ site.ttl
├─ building.ttl
└─ mysite_point_linkage_point_create_link_pattern_match_operation_report.csv

  • one or more turtle files (.ttl files) of the generated model(s)

  • a mgtool.log file that contains information, warnings and errors encountered when processing your supplied information.

  • optionally, depending on whether any of the pattern matching operations of the model construction tool were used, some *_report.csv files that provide further details around what the tooling did when generating your models. In this case, mysite_point_linkage_point_create_link_pattern_match_operation_report.csv.

Examples

These examples are based on simple usages of the Create operation, which is described in detail in its own section. The examples here are solely focussed on how the URIs are mapped and generated.

Example 1: No URI mapping provided; defaults used

Inputs

manifest.json
{
    "manifest_version": "1.0.0",
    "operations": [
        {
            "operation_type": "CREATE",
            "config": {
                "object_file": "objects.csv"
            }
        }
    ]
}

input_csvs/objects.csv

(Csv file referred to in the manifest and provided in the input_csv's folder for the Create Operation to use).

Model_ID|Entity_Name
Class

mySiteModel|siteName

Site

myBuildingModel|buildingName

Building

650B
usage_example_1.zip
archive
Usage Example 1: Full input archive

Outputs

Zipping those up and running that through the tool cause the tool to provide default URIs as there is no id_mapping specified in the manifest file, nor any input turtle files were provided. The tool will produce two turtle output files:

mySiteModel.ttl
@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix mySiteModel: <dch:org/csiro/site/mySiteModel#> .

mySiteModel:siteName a brick:Site ;
    brick:keyValue [ brick:key "mgtool" ;
            brick:value "version: 2.0" ],
        [ brick:key "mgtool" ;
            brick:value "build date: 2024-04-08" ] .
myBuildingModel.ttl
@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix myBuildingModel: <dch:org/csiro/site/mySiteModel/building/myBuildingModel#> .

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

And the log file will include the following warnings:

WARNING | No URI was mapped to site model_id 'mySiteModel' (from manifest or input ttl files), using a default.

WARNING | No URI was mapped to building model_id 'myBuildingModel' (from manifest or input ttl files), using a default.

Note the prefixes generated for the mySiteModel and myBuildingModel - the org defaults to 'csiro' and the site and building references default to the model_id's used in the csv.

Note file names used for the output turtle files are also the model_id's used in the csv.

1KB
output_usage_example_1.zip
archive
Usage Example 1: Full output archive

For information regarding using the model generation tooling to update an existing model, see below:

Advanced: Extending an additional model
PreviousOverviewNextCREATE Operation

Last updated