Examples

See your project in action!

Here we provide you with a number of representative examples for

Assignment
Converters

Traditional Static Assignment

All examples in this section are configured to be using the traditional static assignment approach

Example	Name	Description
1	Minimum	Minimum example with all default settings
2	Components	Explicit setting of default components and some small configuration changes to their options
3	Output Configuration	Changing output configuration by adding and removing columns from results and activating different types of results
4	Initial Cost	Apply initial costs
5	Memory Output	Utilise memory output formatter to get access to results without persisting them to disk

Minimum

An assignment where

Default directory which is the current directory
Default stop criterion maximum of 500 iterations with an epsilon of 0.001,
Default MSA smoothing,
Default FIXED cost for the connectors, and
Default BPR function for the cost of physical links,
Default Output formatter with results for link( segment)s are persisted

from planit import *

# create Planit instance collecting input from current dir "."
plan_it = Planit()
plan_it_project = planit_it.project

# choose traditional static assignment
plan_it_project.set(TrafficAssignment.TRADITIONAL_STATIC)         

# run!
plan_it_project.run()

Components

An assignment where we explicitly set the (default) components and change a number of settings

Custom input directory to read project inputs from
Default stop criterion maximum of 100 iterations with an epsilon of 0.000001,
Default MSA smoothing,
Default FIXED cost for the connectors, and
Default BPR function for the cost of physical links, overwrite default alpha and beta
Default Output formatter
- Results for links, paths, and ods are activated, and
- Results will be stored in the same directory as where the inputs were read from.
- explicit naming of result files to refer to this testcase

from planit import *

# input files can be found here
project_path = "path_to_input_dir">

# create PLANit instance pointing to input directory
plan_it = Planit(project_path)
plan_it_project = planit_it.project

# explicitly set default components for assignment: 
# e.g., BPR function, fixed cost for connectors, MSA smoothing explicitly
plan_it_project.set(TrafficAssignment.TRADITIONAL_STATIC)         
plan_it_project.assignment.set(PhysicalCost.BPR)
plan_it_project.assignment.set(VirtualCost.FIXED)
plan_it_project.assignment.set(Smoothing.MSA)

#overwrite default alpha and beta
alpha = 4.5
beta = 0.9
plan_it_project.assignment.physical_cost.set_default_parameters(alpha,beta)

# only persist results of the final iteration to reduce the number of files generated
plan_it_project.assignment.output_configuration.set_persist_only_final_Iteration(True)
# cap the number of iterations to 100
plan_it_project.assignment.gap_function.stop_criterion.set_max_iterations(100)
plan_it_project.assignment.gap_function.stop_criterion.set_epsilon(0.000001)

# activate OD and PATH output results, besides the default link outputs
plan_it_project.assignment.activate_output(OutputType.OD)
plan_it_project.assignment.activate_output(OutputType.PATH)

# include the description of this run in the result file names       
plan_it_project.output.set_xml_name_root("Example_2")                
plan_it_project.output.set_csv_name_root("Example_2")     
# persist results to the same directory as where the input file(s) where found
plan_it_project.output.set_output_directory(project_path)

# run!
plan_it_project.run()

Output configuration

Changing some output properties on the link results
Activate od and path results

from planit import *

plan_it = Planit()
plan_it_project = planit_it.project
plan_it_project.set(TrafficAssignment.TRADITIONAL_STATIC)

# activate and configure PATH outputs
plan_it_project.assignment.activate_output(OutputType.PATH)
#	use node XML ids as the way to uniquely identify the path in the output, e.g. "[1,5,7,2,3]"
plan_it_project.assignment.path_configuration.set_path_id_type(PathIdType.NODE_XML_ID)

# activate and configure OD outputs
plan_it_project.assignment.activate_output(OutputType.OD)         

# configure LINK outputs (active by default)
# 	add Volume Capacity Ratio property to link results 
plan_it_project.assignment.link_configuration.add(OutputProperty.VC_RATIO)
# 	remove computed speed property from link results 
plan_it_project.assignment.link_configuration.remove(OutputProperty.COMPUTED_SPEED)

# run!
plan_it_project.run()

Initial Cost

Default assignment with initial costs. Initial costs are applied in a hierarchy where the most specific initial costs available are utilised.

Currently initial costs are only supported in combination with the default link (segment) output files, where it parses the link costs from the CSV files in order to extract its initial cost.

from planit import *

path_to_initial_costs_period_1 = "specify_path"
path_to_initial_costs_generic = "specify_path"

plan_it = Planit()
plan_it_project = planit_it.project
plan_it_project.set(TrafficAssignment.TRADITIONAL_STATIC)

# specify location of initial costs for time period "1" (XML id)
plan_it_project.initial_costs.set(path_to_initial_costs_period_1, "1")

# specify initial costs for all other periods
plan_it_project.initial_costs.set(path_to_initial_costs_generic)


# run!
plan_it_project.run()

Memory output

Default assignment with memory output formatter only. Use an iterator to loop through the results of the assignment

from planit import *

plan_it = Planit()
plan_it_project = planit_it.project
plan_it_project.set(TrafficAssignment.TRADITIONAL_STATIC)

# remove default formatter - activate memory output
plan_it_project.deactivate(OutputFormatter.PLANIT_IO)
plan_it_project.activate(OutputFormatter.MEMORY)

# run!
plan_it_project.run()

#collect iteration index of last recorded iteration
i = plan_it_project.memory.get_last_iteration()

# find position of flow result column which is a value (output) of the result row
flow_pos = plan_it_project.memory.get_position_of_output_value_property(OutputType.LINK, OutputProperty.FLOW)

# find position of link (XML) id which is a key of the result row	
id_pos = plan_it_project.memory.get_position_of_output_key_property(OutputType.LINK, OutputProperty.LINK_SEGMENT_XML_ID)

# collect iterator for mode "1", time period "2", last iteration i
link_iter = plan_it_project.memory.iterator("1", "2", i, OutputType.LINK)

# print results by looping over entries
while link_iter.has_next():
	link_iter.next()
	print "id: ", link_iter.get_keys()[id_pos], " flow: ", link_iter.get_values()[flow_pos]

Converters

Below the provided examples in table form with quick links

Example	Name	Description
1	OSM network to PLANit network	Example of an Open Street Map to PLANit network conversion
2	TNTP network to PLANit network	Example of a TNTP network to PLANit network conversion
3	OSM network to Matsim network	Example of an Open Street Map to MATSim network conversion
4	PLANit network to GIS Shape network	Example of a PLANit network converted to GIS shape file conversion
5	OSM to PLANit network and pt poles/platforms	Example of an Open Street Map to PLANit network and public transport infrastructure (no services) conversion
6	OSM to MATSim network and pt poles/platforms	Example of an Open Street Map to MATSim network and public transport infrastructure (no services) conversion
7	PLANit to MATSim network and pt poles/platforms	Example of a PLANit to MATSim network and public transport infrastructure (no services) conversion
8	OSM+GTFS to PLANit network + services	Example of an OSM + GTFS reader to PLANit network and public transport (with services) conversion
9	PLANit network + services to GIS Shape	Example of a PLANit combined network and services reader to GIS shape files conversion

For more information on the various properties used, see the Python reference documentation, where each property is discussed on its own page with additional background information where needed.

Have a look at the github tests in the Py2J repository for more examples that are part of the CI pipeline and therefore should be up to date and functional.

OSM to PLANit network conversion

Convert an Open Street Map (OSM) network to a PLANit network, with absolute minimal configuration. Minimal configuration comprises the desired in and output locations of the files, the type of conversion and a hint on the locale to infer the projection used for the used coordinate system.

from planit import *

# create a network converter
planit_instance = Planit()
network_converter = planit_instance.converter_factory.create(ConverterType.NETWORK)

################### OSM READER ###########
osm_reader = network_converter.create_reader(NetworkReaderType.OSM, "Australia")
osm_reader.settings.set_input_file("<path_to_input_file>")


################### PLANit WRITER ########
planit_writer = network_converter.create_writer(NetworkWriterType.PLANIT)
planit_writer.settings.set_output_directory("<path_to_output_dir>")

# perform conversion
network_converter.convert(osm_reader,planit_writer)

TNTP to PLANit network conversion

Convert a TNTP network to a PLANit network. Since TNTP network units are not well defined, typically additional configruation is required to interpret them. Here we provide an example for the Sioux Falls network as it is available on the TNTP github page.

from planit import *

# Create a network converter
planit_instance = Planit()
network_converter = planit_instance.converter_factory.create(ConverterType.NETWORK)

################### TNTP READER ###########
#
tntp_reader = network_converter.create_reader(NetworkReaderType.TNTP)
tntp_reader.settings.set_network_file("<path_to_network_file>")
tntp_reader.settings.set_node_coordinate_file("<path_to_node_file>")

# Define CSV column structure
column_dict = {
        TntpFileColumnType.UPSTREAM_NODE_ID: 0,
        TntpFileColumnType.DOWNSTREAM_NODE_ID: 1,
        TntpFileColumnType.CAPACITY_PER_LANE: 2,
        TntpFileColumnType.LENGTH: 3,
        TntpFileColumnType.FREE_FLOW_TRAVEL_TIME: 4,
        TntpFileColumnType.B: 5,
        TntpFileColumnType.POWER: 6,
        TntpFileColumnType.MAXIMUM_SPEED: 7,
        TntpFileColumnType.TOLL: 8,
        TntpFileColumnType.LINK_TYPE: 9}
tntp_reader.settings.set_network_file_columns(column_dict)

# Define the units explicitly
tntp_reader.settings.set_speed_units(SpeedUnits.MILES_H)
tntp_reader.settings.set_length_units(LengthUnits.MILES)
tntp_reader.settings.set_capacity_period(1, TimeUnits.HOURS)
tntp_reader.settings.set_free_flow_travel_time_units(TimeUnits.MINUTES)
tntp_reader.settings.set_default_maximum_speed(DEFAULT_MAXIMUM_SPEED_KM_H)
#
################### TNTP READER ###########

################### PLANit WRITER ########
#
planit_writer = network_converter.create_writer(NetworkWriterType.PLANIT)
planit_writer.settings.set_output_directory("<path_to_output_dir>")
planit_writer.settings.set_country("Australia")
#
################### PLANit WRITER ########

# Perform conversion
network_converter.convert(tntp_reader, planit_writer)

OSM to MATSim network conversion

Convert an Open Street Map (OSM) network to a MATSim network, with some additional configuration on the OSM reader to ensure we only parse a private vehicle network with the main arterial roads.

from planit import *

# Create a network converter
planit_instance = Planit()
network_converter = planit_instance.converter_factory.create(ConverterType.NETWORK)

################### OSM READER ###########
#     
osm_reader = network_converter.create_reader(NetworkReaderType.OSM, "Australia")
osm_reader.settings.set_input_file("<path_to_input_file>")

# Reduce bounding box and mark some OSM ways that are partially in/out the bounding box to be kept in their entirety
osm_reader.settings.set_bounding_box(144.948083, 144.975849, -37.823582, -37.808292)
osm_reader.settings.set_keep_osm_ways_outside_bounding_box([28919629,45526180])

# Only parse car network
osm_reader.settings.highway_settings().deactivate_all_osm_road_modes_except("motorcar")

# Remove dangling subnetworks after parsing when they have less than 10 vertices
osm_reader.settings.set_remove_dangling_subnetworks(True)
osm_reader.settings.set_discard_dangling_networks_below(10)

# Deactivate all but the largest road to generate a network with only the main road network
osm_reader.settings.deactivate_all_osm_highway_types_except(["motorway", "motorway_link", "trunk", "trunk_link", "primary", "primary_link", "secondary", "secondary_link"])
#
################### OSM READER ###########

################### MATSIM WRITER ########
#
matsim_writer = network_converter.create_writer(NetworkWriterType.MATSIM)
matsim_writer.settings.set_output_directory("<path_to_output_dir>")
matsim_writer.settings.set_country("Australia")
#
################### MATSIM WRITER ########

# Perform conversion
network_converter.convert(osm_reader,matsim_writer)

PLANit to SHAPE network conversion

For visualisation of networks in GIS tools (ArcGIS, QGis, etc.) PLANit offers a GeoIO converter. This example converts a PLANit network into shape files that include layers for, for example, links (non-directional edged between nodes), link segments (directional edges between nodes with additional information on mode access, speed, etc.), and nodes (locations of intersections, or changes in number of lanes, etc.). Each produces layer can be named separately and visualised in GIS software.

from planit import *

planit = Planit()

# Create a network converter
network_converter = planit.converter_factory.create(ConverterType.NETWORK)

################### PLANit READER ###########
#  
planit_reader = network_converter.create_reader(NetworkReaderType.PLANIT, "Australia")
planit_reader.settings.set_input_directory("<path_to_input_dir>")
#
################### PLANit READER ###########

################### GIS (Shape) WRITER ###########
#  
geo_writer = network_converter.create_writer(NetworkWriterType.SHAPE)
geo_writer.settings.set_output_directory(OUTPUT_PATH)
geo_writer.settings.set_country("Australia")

# Choose to not persist nodes (by default all types are persisted)
geo_writer.settings.set_persist_nodes(False)
# Change name of the layer (no extension)
geo_writer.settings.set_links_file_name("my_alternative_links_layer_name")
#
################### GIS (Shape) WRITER ###########

# Perform conversion
network_converter.convert(planit_reader, geo_writer)

OSM to PLANit intermodal conversion

In this example we not only parse the physical road network but also the public transport infrastructure (no services, but poles and platforms only) from the OSM input. The result is persisted in the PLANit format by using the PlanitIntermodalWriter. We use absolute minimum of configuration here.

from planit import *

# Create an intermodal converter
planit_instance = Planit()
intermodal_converter = planit_instance.converter_factory.create(ConverterType.INTERMODAL)

################### OSM READER ###########       
osm_reader = intermodal_converter.create_reader(IntermodalReaderType.OSM, "Australia")
osm_reader.settings.set_input_file("<path_to_input_file>")

################### PLANIT WRITER ########
planit_writer = intermodal_converter.create_writer(IntermodalWriterType.PLANIT)
planit_writer.settings.set_output_directory("<path_to_output_dir>")

# Perform conversion
intermodal_converter.convert(osm_reader,planit_writer)

OSM to MATSim intermodal conversion

In this example we not only parse the physical road network but also the public transport infrastructure (no services, but poles and platforms only) from the OSM input. The result is persisted in the MATSim format by using the MatsimIntermodalWriter.

We also show some of the configuration options specific to the intermodal OSM parser that allow the user to fine tune the way OSM entities are parsed (or not).

from planit import *

# Create an intermodal converter
planit_instance = Planit()
intermodal_converter = planit_instance.converter_factory.create(ConverterType.INTERMODAL)

################### OSM READER ###########
# 
# Open Street Map (OSM) intermodal reader for some file around the Melbourne area        
osm_reader = intermodal_converter.create_reader(IntermodalReaderType.OSM, "Australia")
osm_reader.settings.set_input_file("<path_to_input_file>")

# Overwrite mode access for roads that are tagged as private but have a bus line and stop on them
# so they are in fact not private, overwrite this tagging error by allowing certain modes
osm_reader.settings.network_settings.overwrite_mode_access_by_osm_way_id(19704989, ["bus"])

# Exclude some (pt) OSM nodes from parsing due to issues in tagging
osm_reader.settings.pt_settings.exclude_osm_nodes_by_id([2266764332, 2751390421])

# Exclude some (pt) OSM ways from parsing because they are under construction or they
# represent platforms of a miniature railway that we are not interested in
osm_reader.settings.pt_settings.exclude_osm_ways_by_id([485842787, 715380193, 48992993])

# Tagging error on stop location's waiting area, overwrite manually
osm_reader.settings.pt_settings.overwrite_waiting_area_of_stop_location(6072041693, OsmEntityType.NODE, 571731242)

# Bus stop pole too far from road to be matched, overwrite manually
osm_reader.settings.pt_settings.overwrite_waiting_area_nominated_osm_way_for_stop_location(3184269080, OsmEntityType.NODE, 24039633)
#
################### OSM READER ###########

################### MATSIM WRITER ########
#
matsim_writer = intermodal_converter.create_writer(IntermodalWriterType.MATSIM)
matsim_writer.settings.set_output_directory("<path_to_output_dir>")
matsim_writer.settings.set_country("Australia")

# Indicate we want detailed geometry for nicer visualisation in VIA
matsim_writer.settings.network_settings.set_generate_detailed_link_geometry_file(True)
#
################### MATSIM WRITER ########

# Perform conversion
intermodal_converter.convert(osm_reader,matsim_writer)

PLANit to MATSim intermodal conversion

Example of taking a native PLANit intermodal network and zoning (without services) and persist it to MATSim with minimal configuration.

from planit import *

# Create an intermodal converter
planit_instance = Planit()
intermodal_converter = planit_instance.converter_factory.create(ConverterType.INTERMODAL)

################### PLANit READER ###########       
planit_reader = intermodal_converter.create_reader(IntermodalReaderType.PLANit)
planit_reader.settings.set_input_directory("<path_to_input_dir>")

################### MATSIM WRITER ########
matsim_writer = intermodal_converter.create_writer(IntermodalWriterType.MATSIM)
matsim_writer.settings.set_output_directory("<path_to_output_dir>")
matsim_writer.settings.set_country("Australia")

# Perform conversion
intermodal_converter.convert(planit_reader, matsim_writer)

OSM and GTFS to PLANit conversion

This example highlights the possibility to chain readers to create a combined reader. Here we create aan Open Street Map (OSM) intermodal reader that is responsible for parsing the network (link, nodes, etc.) and public transport infrastructure (poles, platforms, stations), which is then fed to the GTFS reader that will use the outcome of the OSM reader to supplement it with public transport services to create the service network and routed services in the PLANit format. The latter is then persisted as a single combined PLANit result (network, zoning, service network, and routed services).

from planit import *

# Create an intermodal converter
planit_instance = Planit()
intermodal_converter = planit_instance.converter_factory.create(ConverterType.INTERMODAL)

################### OSM READER ###########       
#
osm_reader = intermodal_converter.create_reader(IntermodalReaderType.OSM, "Australia")
osm_reader.settings.set_input_file("<path_to_input_file>")
#
################### OSM READER ###########

################### GTFS READER ###########       
#
# Create GTFS reader and chain it with the OSM reader by passing it into the create_reader method
gtfs_reader = intermodal_converter.create_reader(IntermodalReaderType.GTFS, AUSTRALIA, osm_reader)
gtfs_reader.settings.set_input_file("<path_to_zipped_input_file>")

# Limit parsing to a single day
gtfs_reader.settings.services_settings.day_of_week = DayOfWeek.THURSDAY
# Limit parsing to a particular time period within the day
gtfs_reader.settings.services_settings.add_time_period_filter(
	datetime.time(hour=6, minute=0, second=0),
	datetime.time(hour=9, minute=59, second=59)
)

# Extensive configuration options exist to configure the GTFS reader to your liking, see PLANit Python reference manual
# for details on this as there are too many options to provide in a single example, a few possibilities are listed below
gtfs_reader.settings.zoning_settings.set_overwrite_gtfs_stop_location("<a_gtfs_stop_id>", 33.33, 148.148)  # lat/lon
gtfs_reader.settings.zoning_settings.exclude_gtfs_stops_by_id(["<gtfs_stop_id>", "<another_gtfs_stop_id>"])
gtfs_reader.settings.zoning_settings.overwrite_gtfs_stop_to_link_mapping("<gtfs_stop_id>", "<planit_link_external_osm_id>", IdMapperType.EXTERNAL_ID)

################### PLANit WRITER ########
planit_writer = intermodal_converter.create_writer(IntermodalWriterType.PLANIT)
planit_writer.settings.set_output_directory("<path_to_output_dir>")
planit_writer.settings.set_country("Australia")

# Perform conversion
intermodal_converter.convert_with_services(gtfs_reader, planit_writer)

PLANit network and services to SHAPE conversion

This example shows how to persist a complete PLANit network and public transport services input set (network, zoning, service network, and routed services) as GIS shape files. Because Shape files only contain a single entity type, e.g., just links, or just nodes, a multitude of shape files is produced with this conversion. The user can choose which ones are produced individually via the settings of the Shape writer. In addition, this converter also supports persisting the “on-the-fly” connection between the zones and the physical network (by means of connectoids, links and segments) as GIS layers.

from planit import *

planit = Planit()

# Create converter
intermodal_converter = planit.converter_factory.create(ConverterType.INTERMODAL)

################### PLANit READER ###########
#  
planit_reader = intermodal_converter.create_reader(IntermodalReaderType.PLANIT, "Australia")
planit_reader.settings.set_input_directory("<path_to_input_dir>")
#
################### PLANit READER ###########

################### GIS (Shape) WRITER ###########
#  
geo_writer = intermodal_converter.create_writer(IntermodalWriterType.SHAPE)
geo_writer.settings.set_output_directory("<path_to_output_dir>")
geo_writer.settings.set_country("Australia")
# Explicitly set what to persist from the network (these flags are the default, but are included for illustration purposes)
geo_writer.settings.network_settings.set_persist_nodes(True)
geo_writer.settings.network_settings.set_persist_links(True)
# Indicate to persist interface (connectoids and link/linksegments) between (transfer)zones and physical network
geo_writer.settings.zoning_settings.persist_virtual_network = True
#
################### GIS (Shape) WRITER ###########

# Perform conversion
intermodal_converter.convert_with_services(planit_reader, geo_writer)