Data formats

In this section of the manual we discuss the data formats supported by PLANitm i.e., input/output file formats and structure.

Here we only focus on the structure of the data formats . If the reader wants to know how to set up an assignment using input/output files of a specific format, we refer to the reference documentation on the Java and Python API for more detailed information.

We make a clear distinction between input and output data formats. Inputs comprise the network, demands, and zoning structure, while outputs are differentiated by output type (link, path, etc.). Since PLANit is modular and extendible, you can write your own components for parsing inputs and persisting outputs. However, in most cases, you can simply use the default input and output components provided by PLANit, referred to as the “default format”.

Input Data Formats

The following input data formats are available:

Data Format File type Status Documentation Python support Java support
PLANit default input format XML supported YES YES YES
TNTP open format ASCII prototype NO NO YES
BasicCSV CSV prototype NO NO YES

It is strongly recommended to only use the officially supported native xml format at this stage, as the TNTP and BasicCSV input formats do not support the full feature set of PLANit, are not available in Python, nor are they tested fully. Also, the TNTP format is ambiguous in its specification and often example networks provided in this format do not strictly follow the format either.

PLANit default input format

For detailed information on the PLANit default input format we refer the reader to the dedicated section on the PLANit default Input Data Format. For a taste of what this format looks like, we provide a small example below to give a first impression.

Minimum example

Below you will find an example of a very simple - yet complete - input file for PLANit, with a simple network containing:

  • One link having two directions, so
  • Two link segments, and
  • Two nodes (on either end of the link)

Basic zoning structure:

  • Two zones, each with one centroid, so
  • Two centroids,
  • Two connectoids, i.e., references to nodes that allow access/egress to/from a zone

Basic demands:

  • 1 time period with a duration of 1 hour (3600s)
  • 1 trip between zone 1 and zone 2

Resulting in the following single XML input file:

<PLANit xmlns:gml="http://www.opengis.net/gml"
	xmlns:xml="http://www.w3.org/XML/1998/namespace"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:noNamespaceSchemaLocation="<path_to>/macroscopicinput.xsd">
	
	<!-- Demand component -->
	<macroscopicdemand>
		<demandconfiguration>
			<timeperiods>
				<timeperiod id="1">
					<duration>3600</duration>
				</timeperiod>
			</timeperiods>
		</demandconfiguration>
		<oddemands>
			<odcellbycellmatrix timeperiodref="0">
				<o ref="1">
					<d ref="2">1</d>
				</o>
			</odcellbycellmatrix>
		</oddemands>
	</macroscopicdemand>
	
	<!-- Physical network component -->
	<macroscopicnetwork>
		<infrastructure>
			<nodes>
				<node id="1" />
				<node id="2" />
			</nodes>
			<links>
				<link nodearef="1" nodebref="2">
					<linksegment id="1" dir="a_b" />
					<linksegment id="2" dir="b_a" />
					<length>10</length>
				</link>
			</links>
		</infrastructure>
	</macroscopicnetwork>
	
	<!-- zoning structure component -->
	<macroscopiczoning>
		<zones>
			<zone id="1">
				<centroid>
					<gml:Point>									
						<gml:pos>45.256 -110.45</gml:pos>
					</gml:Point>
				</centroid>
				<connectoids>
					<connectoid noderef="1" />
				</connectoids>
			</zone>
			<zone id="2">
				<centroid>
					<name>2</name>
					<gml:Point>
						<gml:pos>45.256 -110.45</gml:pos>
					</gml:Point>
				</centroid>
				<connectoids>
					<connectoid noderef="2" />
				</connectoids>
			</zone>
		</zones>
	</macroscopiczoning>
</PLANit>

Output Data Formats

The following output data formats are available:

Data Format File type Status Documentation Python support Java support
PLANit default output format XML supported YES YES YES
Memory output format None supported YES YES YES

The memory output format does not result in any files on disk as it keeps all the results in memory.

PLANit default output format

For detailed information on the PLANit default output format we refer the reader to the dedicated section on the PLANit Default Output Data Format. For a taste of what this format looks like, we provide a small example below to give a first impression.

Below you will find an example of link output for a PLANit run. Meta-data is provided in a separate XML file, while the raw results are provided in a CSV file with heading row.

XML meta-data includes:

  • Time stamp of when the data is created
  • PLANit version used
  • Scenario description
  • Traffic assignment component configuration information
  • Location of CSV result file
  • CSV column meta-data (name, units, type)

CSV raw data includes:

  • Column headings to relate column to meta-data in XML
  • Row for each link (segment) result
  • Value in each column of each row to store result value

In the example below, you will find the XML meta-data file for basic link results, where we only activated link segment costs (although many other columns can be activated in your own simulation. The link segment (external) id and the mode (external) id uniquely identify each result row.

The CSV file contains the results for this example, where we only have a single row with non-zero results.

In general, the CSV file is generally much much larger than the xml meta-data file.

Identical approach is used for other output types (paths, origing-destinations, etc.), only the meta-data and supported properties differ


<metadata xmlns:xml="http://www.w3.org/XML/1998/namespace"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:noNamespaceSchemaLocation="<path_to>/linkmetadata.xsd">
	<timestamp>2020-01-24T12:07:00.302+11:00</timestamp>
	<version>0.1</version>
	<description>PlanIt example</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>1</nr>
			<csvdata type="Link"><path_to_result>\Link_RunId 0_TEST_Time Period 1_1.csv</csvdata>
		</iteration>
	</simulation>
	<columns>
		<column>
			<name>Link Segment External Id</name>
			<units>none</units>
			<type>integer</type>
		</column>
		<column>
			<name>Mode External Id</name>
			<units>none</units>
			<type>integer</type>
		</column>
		<column>
			<name>Cost</name>
			<units>h</units>
			<type>double</type>
		</column>
	</columns>
</metadata>

CSV example, with a cost of 6 minutes (0.1 h) for link segment 1, and mode 1

Link Segment External Id,Mode External Id,Cost
1,1,0.1

See Also

PLANit Output Data Formats for information on all available output formats
PLANit Default Output Data Format for the Default PLANit output format
PLANit Input Data Formats for information on all available input formats
PLANit Default Input Data Format for the Default PLANit input format

Input Data formats

Output Data formats

Last modified May 29, 2020: - added link,od,path supported output properties to output data format - finalised default output format - refactoring (c239a27)