Default Output Formatter

The default output formatter for PLANit

Description

The Default output formatter is activated by default (OutputFormatter.PLANIT_IO) on any PLANit run (hence the name). It persists the results to disk by using a combination of Extendible Markup Language (XML) and Comma Separated Value (CSV) formats:

XML: used to store meta-information on the CSV results
CSV: contains the actual results, with a header to identify XML meta-information

XML Meta information

The XML files provides the user with meta-information on the assignment run. this includes column meta-data, assignment meta-data, and csv result locations related to this meta-data. For detailed information on this output format please refer to the data-format section in this manual.

The column meta-data provided information regarding:

Name: corresponds to the name in CVS header
Units: unit of the column values
Type: type of the value, e.g. integer, float, etc.

Each items is in fact nothing more than a human readable version of an activated OutputProperty.

CSV results

The csv results file, is a simple comma separated tabular format with the first row containing column headers and all other rows containing data entries, i.e., a typical tabular format.

An example of a raw csv file that could be generated by PLANit’s default memory output formatter is provided below.

Downstream Node Xml Id,Downstream Node Id,Link Segment Xml Id,Link Segment Id,Mode Xml Id,Mode Id,Upstream Node Xml Id,Upstream Node Id,Capacity per Lane,Downstream Node Location,Length,Number of Lanes,Upstream Node Location,Calculated Speed,Cost,Density,Flow
1,0,1,0,1,0,11,4,1200.0000000,Not Specified,1.0000000,3,Not Specified,40.0000000,0.0250000,180.0000000,3600.0000000
12,5,3,2,1,0,4,3,1200.0000000,Not Specified,1.0000000,3,Not Specified,40.0000000,0.0250000,180.0000000,3600.0000000
2,1,4,3,1,0,1,0,1200.0000000,Not Specified,2.0000000,1,Not Specified,1.4457831,1.3833333,180.0000000,3600.0000000
4,3,5,4,1,0,2,1,1200.0000000,Not Specified,2.0000000,1,Not Specified,1.4457831,1.3833333,180.0000000,3600.0000000

As you can see each column can contain either numbers, decimals, or string values, each of which correspond to an activated output property reflected by the header name (and XML meta-information). This way, the data is easy to process, interpret, and modify, while still being human-readable.

Location and naming of outputs

The configuration options on this class instance pertain to configuring the location and file name structure of the output files . As a user you can configure:

Output directory location
A descriptive name to be embedded in each output file, i.e., the “root name”
Extension to use for the XML and CSV files

The naming structure of each CSV output file looks like the following ([] indicates a configurable constant, and <> indicates a non-configurable variable).

<outputtype name>_RunId_<run_id>_[root name]_Time_Period_<time period>_<iteration index>[csv_extension]

reflects the output type this file provides results for, e.g. “Link”, “Path”, etc.
reflects the unique simulation run identifier within this PLANit instance, always 0 in PLANit Python
the time period’s description as provided in the user input, e.g. “1”, “first time period”, “8-10”, etc.
the iteration index of the traffic assignment, e.g. 0,1,….100, etc.

The user can then configure

[root name] prefix describing this run/application/scenario
[csv_extension] the extension to use

Whenever the user includes spaces in any of the configurable aspects of the result files. Planit will replaces those with underscores.

An concrete example of a result file name would be Link_RunId_0_test_basic_1_Time_Period 1_2.csv, here the root name is set to test basic 1 and the default extension for csv is left untouched.

The naming structure of an XML file is identical, except that it does not contain iteration information since meta-data is invariant to iteration results. Also, the extension configuration is sepcific to xml;

<outputtype name>_RunId_<run_id>_[root name]_Time_Period_<time period>[xml_extension],

with concrete example Link_RunId 0_test_basic_1_Time_Period_1.xml.

Defaults

The following defaults are provided for the extension and and root name, a.k.a. prefix, of this output formatter

Name	Value	Type	Unit
`DEFAULT_CSV_NAME_EXTENSION`	`.csv`	`string`	`None`
`DEFAULT_CSV_NAME_PREFIX`	`CSVOutput`	`string`	`None`
`DEFAULT_XML_NAME_EXTENSION`	`.xml`	`string`	`None`
`DEFAULT_XML_NAME_PREFIX`	`XMLOutput`	`string`	`None`

The following defaults are used for the output locatino

Name	Value	Type	Unit
`DEFAULT_CSV_OUTPUT_DIRECTORY`	`.`, i.e., current working directory	`string`	`None`
`DEFAULT_XML_OUTPUT_DIRECTORY`	`.`, i.e., current working directory	`string`	`None`

Methods

The Default output formatter exposes the following methods

Name	Description
`set_description(+)`	Overwrite the default description that is being included in XML meta-data files
`set_output_directory(+)`	Overwrite the default output directory for both CSV and XML files
`set_csv_directory(+)`	Overwrite `DEFAULT_CSV_OUTPUT_DIRECTORY`
`set_csv_name_extension(+)`	Overwrite `DEFAULT_CSV_NAME_EXTENSION`
`set_csv_name_root(+)`	Overwrite `DEFAULT_CSV_NAME_PREFIX`
`set_xml_directory(+)`	Overwrite `DEFAULT_XML_OUTPUT_DIRECTORY`
`set_xml_name_extension(+)`	Overwrite `DEFAULT_XML_NAME_EXTENSION`
`set_xml_name_root(+)`	Overwrite `DEFAULT_XML_NAME_PREFIX`

Properties

No exposed properties (yet)

Example 1

from planit import *

#all input and output available in public user directory (windows)
io_dir = "c:\users\public\planit\"

#collect input
plan_it = Planit(io_dir)
# configure to persist output in same directory
plan_it.project.output.set_output_directory(io_dir)

#description of this run test
description = "test_1"
plan_it.project.output.set_csv_name_root(description)
plan_it.project.output.set_xml_name_root(description)

#
# <more configuration>
#

#run simulation
plan_it.run()

Source code

Class PlanItOutputFormatterWrapper in projectwrappers.py

Default Output Formatter

Description

XML Meta information

CSV results

Location and naming of outputs

Defaults

Methods

Properties

Example 1

See also

Source code

.set_csv_directory(+)

.set_csv_name_extension(+)

.set_csv_name_root(+)

.set_description(+)

.set_output_directory(+)

.set_xml_directory(+)

.set_xml_name_extension(+)

.set_xml_name_root(+)