Usage
Basic description of how to use the tool.
Last updated
Basic description of how to use the tool.
Last updated
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).
The provided zip file has some required components as well as some optional components.
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
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:
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.
As indicated, URIs are used in the turtle files to refer to different models. DCH URIs take the following forms:
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.
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):
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:
The output zip file will contain:
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.
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).
mySiteModel|siteName
Site
myBuildingModel|buildingName
Building
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:
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.
For information regarding using the model generation tooling to update an existing model, see below:
operation
operation
operation