XML meta-data
In this section of the manual we discuss the meta-data component of the PLANit default output. The meta-data structure is the same for the available output types, but the contents can differ.
There is ever only one meta-data file per PLANit run per time period, while there can be multiple CSV output files per run per time period (for example one per iteration).
The meta-data XML file contains general information on the PLANit run, supplemented with column meta-data relating to the CSV result files it references.
File name convention
Each XML meta-data file, is auto-generated. All file names use underscores instead of spaces. It adopts the following naming convention for its file name by default:
Link_RunId_<#runId>_<name>_Time_Period_<#timePeriod>.xml
with
<#runId>, the unique number of the simulation run conducted since creating a PLANit project, typically 0,<name>, name of the scenario being executed,<#timePeriod>, the time period reference number (external id) of the simulation run.
In case the user provided a name of the scenario that contains spaces. PLANit will convert these spaces to underscores.
An example of a potential meta-data link (segment) result file might be: Link_RunId_0_test_scenario_Time_Period_1.xml, where the description is “test_scenario”, and we are looking at the results for time period 1, for run 0, regarding Link outputs.
Let us now discuss the contents and structure of the meta-data XML file
The
<name>is taken from the XMLNameRoot set by the user (or the default when not set), via the PLANit Default Output Formatter.
<metadata>
The root element of the meta-data XML file is always <metadata>.
This root element can contain the following sub-elements:
| XML Element Name | Compulsory | Maximum occurrences | Description |
|---|---|---|---|
timestamp> |
YES | 1 | Time stamp of when the file was generated |
version> |
YES | 1 | PLANit version used |
description> |
YES | 1 | Description of the PLANit run |
outputconfiguration> |
YES | 1 | Configuration information regarding PLANit run |
simulation> |
YES | 1 | Information regarding related CSV output files |
columns> |
YES | 1 | Configuration information regarding CSV columns |
The description can currently be set via the output formatter, in future versions this will be moved elsewhere.
<> <timestamp>
Simple element that contains the time stamp of when the file was generated.
| type | Unit | Compulsory | Default value | Description |
|---|---|---|---|---|
string |
xs:datetime |
YES | N/A | Time stamp |
<> <version>
Simple element that contains the PLANit version used to generate the results
| type | Unit | Compulsory | Default value | Description |
|---|---|---|---|---|
string |
None |
YES | N/A | PLANit version |
<> <description>
Simple element that contains the description of the conducted PLANit run
| type | Unit | Compulsory | Default value | Description |
|---|---|---|---|---|
string |
None |
YES | N/A | PLANit run description |
<> <outputconfiguration>
General information on the simulation run and the components that it used. With respect to the components, the values that are provided for each of the simple elements correspond to the (short) name of their implementation. In addition, each meta-data XML file can correspond to many CSV output files, when there exist multiple time periods that were run under the same configuration. These are listed under the time periods element.
This element has the following simple elements:
| XML Simple Element Name | type | Unit | Compulsory | Default value | Description |
|---|---|---|---|---|---|
<assignment> |
string |
None |
YES | N/A | Assignment type used |
<physicalcost> |
string |
None |
YES | N/A | Physical cost type used |
<virtualcost> |
string |
None |
YES | N/A | Virtual cost type used |
This element has the following sub-elements:
| XML Element Name | Compulsory | Maximum occurrences | Description |
|---|---|---|---|
<timeperiod> |
YES | unbounded | A time period for which results are made available |
<><> <timeperiod>
A time period for which results are available.
This element has the following simple elements:
| XML Simple Element Name | type | Unit | Compulsory | Default value | Description |
|---|---|---|---|---|---|
<id> |
string |
None |
YES | N/A | (External) Id of the time period |
<name> |
string |
None |
YES | N/A | Description of the time period |
<> <simulation>
The simulation element provides the direct relation between an (iteration) result and its CSV file where the result values can be found.
This element has the following sub-elements:
| XML Element Name | Compulsory | Maximum occurrences | Description |
|---|---|---|---|
<iteration> |
YES | unbounded | Iteration for which a CSV result file is available |
<><> <iteration>
The iteration element provides the location of the CSV file that holds the results of this particular iteration.
This element has the following simple elements:
| XML Simple Element Name | type | Unit | Compulsory | Default value | Description |
|---|---|---|---|---|---|
<nr> |
non-negative integer |
None |
YES | N/A | index of the iteration |
This element has the following sub-elements:
| XML Element Name | Compulsory | Maximum occurrences | Description |
|---|---|---|---|
<csvdata> |
YES | 1 | Where to find the CSV data for this iteration |
<><><> <csvdata>
Provides the link to the CSV file for its parent iteration.
The “type” attribute always states “Link”, as the only supported type.
This element has the following attributes:
| XML attribute Name | type | Unit | Compulsory | Description |
|---|---|---|---|---|
type |
string |
None |
YES | Type of reference provided. Currently, always set to "Link" |
The value of a “Link” based csvdata element is configured as follows:
| XML value type | Unit | Description |
|---|---|---|
| string | None |
Relative path to CSV data, with compulsory extension of .csv |
<> <columns>
The columns element contains all the column specifications that are included in the CSV result file(s), providing meta-data information that cannot be included in the CSV itself.
This element has the following sub-elements:
| XML Element Name | Compulsory | Maximum occurrences | Description |
|---|---|---|---|
<column> |
YES | unbounded | Column meta-data |
<><> <column>
the column element contains the meta-data for a single column that is included in the CSV result file(s). This is information that cannot be included in the CSV itself. A column’s meta-data always relates to an (activated) output property in PLANit.
This element has the following simple elements:
| XML Simple Element Name | type | Unit | Compulsory | Default value | Description |
|---|---|---|---|---|---|
<name> |
string |
None |
YES | N/A | Name of the output property represented by this column |
<type> |
a type | None |
YES | N/A | Type of the values in this column, based on its output property type |
<unit> |
string |
a unit | YES | N/A | Unit of the values in this column, based on its output property unit |
CSV Results
The CSV results are provided in the most common format for comma separate files (by default), where each value is separated by a comma, i.e., ',', as is each row. The user can override the separator characters in the output formatter configuration if desired.
In addition, each CSV file commences with a headings row, where the names in the heading correspond to the names in the XML meta-data <column> elements. Information regarding; name, type, and units can be found in the XML, whereas the values are available in this CSV.
See Expanded Example section.
Expanded Example
Below you will find an expanded example where many of the available output properties are activated, in this case for link based results. OD and path meta-data XML files look similar, although the activated columns will differ. This example is meant to demonstrate all aspects of the file structure, rather than representing a viable output result.
<?xml version="1.0" ?>
<metadata xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../../main/resources/xsd/metadata.xsd">
<timestamp>2020-01-24T12:11:51.870+11:00</timestamp>
<version>0.0.3-beta</version>
<description>PlanIt common code for traffic assignment</description>
<outputconfiguration>
<assignment>TraditionalStaticAssignment</assignment>
<physicalcost>BPRLinkTravelTimeCost</physicalcost>
<virtualcost>FixedConnectoidTravelTimeCost</virtualcost>
<timeperiod>
<id>0</id>
<name>Time Period 1</name>
</timeperiod>
</outputconfiguration>
<simulation>
<iteration>
<nr>500</nr>
<csvdata type="Link">src\test\resources\testcases\route_choice\xml\biDirectionalLinksRouteChoiceSingleModeWithTwoTimePeriods\Link_RunId_0_testRouteChoice42_Time Period_1_500.csv</csvdata>
</iteration>
</simulation>
<columns>
<column>
<name>Downstream Node External Id</name>
<units>none</units>
<type>integer</type>
</column>
<column>
<name>Downstream Node Id</name>
<units>none</units>
<type>integer</type>
</column>
<column>
<name>Link Segment External Id</name>
<units>none</units>
<type>integer</type>
</column>
<column>
<name>Link Segment Id</name>
<units>none</units>
<type>integer</type>
</column>
<column>
<name>Mode External Id</name>
<units>none</units>
<type>integer</type>
</column>
<column>
<name>Mode Id</name>
<units>none</units>
<type>integer</type>
</column>
<column>
<name>Upstream Node External Id</name>
<units>none</units>
<type>integer</type>
</column>
<column>
<name>Upstream Node Id</name>
<units>none</units>
<type>integer</type>
</column>
<column>
<name>Capacity per Lane</name>
<units>veh/h</units>
<type>double</type>
</column>
<column>
<name>Downstream Node Location</name>
<units>srs</units>
<type>srsname</type>
</column>
<column>
<name>Length</name>
<units>km</units>
<type>double</type>
</column>
<column>
<name>Number of Lanes</name>
<units>none</units>
<type>integer</type>
</column>
<column>
<name>Upstream Node Location</name>
<units>srs</units>
<type>srsname</type>
</column>
<column>
<name>Calculated Speed</name>
<units>km/h</units>
<type>double</type>
</column>
<column>
<name>Cost</name>
<units>h</units>
<type>double</type>
</column>
<column>
<name>Density</name>
<units>veh/km</units>
<type>double</type>
</column>
<column>
<name>Flow</name>
<units>veh/h</units>
<type>double</type>
</column>
</columns>
</metadata>
And an example of the CSV that might go with it
Downstream Node External Id,Downstream Node Id,Link Segment External Id,Link Segment Id,Mode External Id,Mode Id,Upstream Node External Id,Upstream Node Id,Capacity per Lane,Downstream Node Location,Length,Number of Lanes,Upstream Node Location,Calculated Speed,Cost,Density,Flow
9,8,1,0,1,0,12,11,1500.0000000,Not Specified,2.9000001,1,Not Specified,100.0000000,0.0290000,180.0000000,0.6000000
12,11,2,1,1,0,9,8,1500.0000000,Not Specified,2.9000001,1,Not Specified,100.0000000,0.0290000,180.0000000,0.6000000
11,10,3,2,1,0,12,11,1500.0000000,Not Specified,3.0000000,1,Not Specified,99.4679928,0.0301605,180.0000000,482.4000000
12,11,4,3,1,0,11,10,1500.0000000,Not Specified,3.0000000,1,Not Specified,99.4679928,0.0301605,180.0000000,482.4000000
16,15,5,4,1,0,12,11,1500.0000000,Not Specified,1.0000000,1,Not Specified,99.4653552,0.0100538,180.0000000,483.0000000
12,11,6,5,1,0,16,15,1500.0000000,Not Specified,1.0000000,1,Not Specified,99.4653552,0.0100538,180.0000000,483.0000000
13,12,9,8,1,0,9,8,1500.0000000,Not Specified,1.0000000,1,Not Specified,100.0000000,0.0100000,180.0000000,0.6000000
9,8,10,9,1,0,13,12,1500.0000000,Not Specified,1.0000000,1,Not Specified,100.0000000,0.0100000,180.0000000,0.6000000
11,10,11,10,1,0,10,9,1500.0000000,Not Specified,3.0000000,1,Not Specified,99.9999991,0.0300000,180.0000000,17.6000000
10,9,12,11,1,0,11,10,1500.0000000,Not Specified,3.0000000,1,Not Specified,99.9999991,0.0300000,180.0000000,17.6000000
14,13,13,12,1,0,10,9,1500.0000000,Not Specified,1.0000000,1,Not Specified,99.9999991,0.0100000,180.0000000,17.6000000
10,9,14,13,1,0,14,13,1500.0000000,Not Specified,1.0000000,1,Not Specified,99.9999991,0.0100000,180.0000000,17.6000000
15,14,15,14,1,0,11,10,1500.0000000,Not Specified,1.0000000,1,Not Specified,99.3865031,0.0100617,180.0000000,500.0000000
11,10,16,15,1,0,15,14,1500.0000000,Not Specified,1.0000000,1,Not Specified,99.3865031,0.0100617,180.0000000,500.0000000
5,4,17,16,1,0,1,0,1500.0000000,Not Specified,1.0000000,1,Not Specified,93.9295781,0.0106463,180.0000000,899.4000000
1,0,18,17,1,0,5,4,1500.0000000,Not Specified,1.0000000,1,Not Specified,93.9295781,0.0106463,180.0000000,899.4000000
4,3,19,18,1,0,1,0,1500.0000000,Not Specified,0.9000000,1,Not Specified,87.8665119,0.0102428,180.0000000,1087.4000000
1,0,20,19,1,0,4,3,1500.0000000,Not Specified,0.9000000,1,Not Specified,87.8665119,0.0102428,180.0000000,1087.4000000
2,1,21,20,1,0,1,0,1500.0000000,Not Specified,0.9000000,1,Not Specified,90.6131820,0.0099323,180.0000000,1012.0000000
1,0,22,21,1,0,2,1,1500.0000000,Not Specified,0.9000000,1,Not Specified,90.6131820,0.0099323,180.0000000,1012.0000000
6,5,23,22,1,0,2,1,1500.0000000,Not Specified,1.0000000,1,Not Specified,61.7567660,0.0161926,180.0000000,1582.4000000
2,1,24,23,1,0,6,5,1500.0000000,Not Specified,1.0000000,1,Not Specified,61.7567660,0.0161926,180.0000000,1582.4000000
3,2,25,24,1,0,2,1,1500.0000000,Not Specified,1.0000000,1,Not Specified,91.1933155,0.0109657,180.0000000,994.4000000
2,1,26,25,1,0,3,2,1500.0000000,Not Specified,1.0000000,1,Not Specified,91.1933155,0.0109657,180.0000000,994.4000000
7,6,27,26,1,0,3,2,1500.0000000,Not Specified,1.0000000,1,Not Specified,43.7230914,0.0228712,180.0000000,1900.0000000
3,2,28,27,1,0,7,6,1500.0000000,Not Specified,1.0000000,1,Not Specified,43.7230914,0.0228712,180.0000000,1900.0000000
4,3,29,28,1,0,3,2,1500.0000000,Not Specified,1.0000000,1,Not Specified,93.7709887,0.0106643,180.0000000,905.6000000
3,2,30,29,1,0,4,3,1500.0000000,Not Specified,1.0000000,1,Not Specified,93.7709887,0.0106643,180.0000000,905.6000000
8,7,31,30,1,0,4,3,1500.0000000,Not Specified,1.0000000,1,Not Specified,59.6936660,0.0167522,180.0000000,1617.0000000
4,3,32,31,1,0,8,7,1500.0000000,Not Specified,1.0000000,1,Not Specified,59.6936660,0.0167522,180.0000000,1617.0000000
23,18,33,32,1,0,16,15,1000.0000000,Not Specified,1.0000000,10,Not Specified,49.9998639,0.0200001,180.0000000,483.0000000
16,15,34,33,1,0,23,18,1000.0000000,Not Specified,1.0000000,10,Not Specified,49.9998639,0.0200001,180.0000000,483.0000000
8,7,35,34,1,0,23,18,1000.0000000,Not Specified,1.0000000,10,Not Specified,49.9829143,0.0200068,180.0000000,1617.0000000
23,18,36,35,1,0,8,7,1000.0000000,Not Specified,1.0000000,10,Not Specified,49.9829143,0.0200068,180.0000000,1617.0000000
21,16,37,36,1,0,13,12,1000.0000000,Not Specified,1.0000000,10,Not Specified,50.0000000,0.0200000,180.0000000,0.6000000
13,12,38,37,1,0,21,16,1000.0000000,Not Specified,1.0000000,10,Not Specified,50.0000000,0.0200000,180.0000000,0.6000000
5,4,39,38,1,0,21,16,1000.0000000,Not Specified,1.0000000,10,Not Specified,49.9983642,0.0200007,180.0000000,899.4000000
21,16,40,39,1,0,5,4,1000.0000000,Not Specified,1.0000000,10,Not Specified,49.9983642,0.0200007,180.0000000,899.4000000
22,17,41,40,1,0,14,13,1000.0000000,Not Specified,1.0000000,10,Not Specified,50.0000000,0.0200000,180.0000000,17.6000000
14,13,42,41,1,0,22,17,1000.0000000,Not Specified,1.0000000,10,Not Specified,50.0000000,0.0200000,180.0000000,17.6000000
6,5,43,42,1,0,22,17,1000.0000000,Not Specified,1.0000000,10,Not Specified,49.9843300,0.0200063,180.0000000,1582.4000000
22,17,44,43,1,0,6,5,1000.0000000,Not Specified,1.0000000,10,Not Specified,49.9843300,0.0200063,180.0000000,1582.4000000
24,19,45,44,1,0,15,14,1000.0000000,Not Specified,1.0000000,10,Not Specified,49.9998438,0.0200001,180.0000000,500.0000000
15,14,46,45,1,0,24,19,1000.0000000,Not Specified,1.0000000,10,Not Specified,49.9998438,0.0200001,180.0000000,500.0000000
7,6,47,46,1,0,24,19,1000.0000000,Not Specified,1.0000000,10,Not Specified,49.9674410,0.0200130,180.0000000,1900.0000000
24,19,48,47,1,0,7,6,1000.0000000,Not Specified,1.0000000,10,Not Specified,49.9674410,0.0200130,180.0000000,1900.0000000