GtfsIntermodalReader

The GtfsIntermodalReader class instance can be created via the IntermodalConverter. It provides the functionality to process a GTFS dataset to supplement an existing network with public transport services and infrastructure. In case there already exists public transport infrastructure in the form of poles and platforms the reader will first try to match GTFS stops to existing poles and platforms based on a number of rules/heuristics such as

• proximity
• mode compatibility
• stop location relative to road compatibility
• name/platform number compatibility
• most likely services road compatability

If no match can be found, a new stop in the form of a pole/platform (termed transfer zone in PLANit) will be created automatically. As with all services in PLANit, the parsed public transport services will be routed on a service network. A service network sits on top of a physical network, where each service node represents a location where at least one service has a stop. service legs connect service nodes, where each leg has at most two directional service leg segments analogous to links and link segments in physical networks, only here each service leg segment may comprise multiple physical link segments.

Public transport services are captured in ‘RoutedServices` in PLANit, where each service is represented as a number of either schedule based trips or frequency based trips.

Because GTFS datasets have no network, an existing network(reader) has to be provided when constructing a GTFS intermodal reader. this network will then be used to attach the stops and services upon.

GTFS Terminology

In the GTFS data format certain terminology is used. To avoid confusion the most common terms used are listed below:

• GTFS Route type: indicates the mode of transport, i.e., bus or train and various sub-types, e.g., school bus, mono-roil etc. In PLANit terminology this is a mode
• GTFS route: represent a public transport service based on their head sign (short name), e.g., 431, and/or long name, e.g., Bondi beach to Central. In Planit terminology this is a routed service
• GTFS trip: represents one or more specific instances of a service that follow a particular stopping pattern for specific timeslots and/or dates. In PLANit terminology this is a trip schedule
• GTFS stop: represents a stop location pole, platform, stand, station for a trip. It is possible that the same stop id is used by multiple modes (although this is rare). In PLANit terminology this is a transfer zone

Limitations

• Frequency based GTFS data sets are not yet fully supported.
• At present only a single GTFS dataset for a single day can be parsed. It is however possible to construct multiple time periods to consider within that day.
• Holidays, or specific changes on specific days within the GTFS schedule are not yet supported.

Configuration

All configuration of this reader is performed via its .settings property, providing access to the GtfsIntermodalReaderSettings.

Logging

The GTFS intermodal reader has extensive logging capabilities built in as well as additional settings to further expand (or reduce) logging and or warnings being generated. Typically, one would first perform a run with the basic settings, then analyse the logs, and then make further tweaks to the settings to address anomalies identified, activate/deactivate certain modes or mode mappings, override locations of GTFS stops to better align with the network, etc.

If, after reading the documentation, you remain unsure what defaults or settings to adopt, we recommend to do a trial run, inspect the generated logs and then go from there. PLANit will log the majority of the adopted defaults in its output when performing the OSM intermodal network reading.

Minimum configuration requirements

The user is required to explicitly configure at least the following settings on an GtfsIntermodalReader:

• set an InputFile via .settings.set_input_file(+)

During creation of the reader, make sure to provide the country of origin as well as the intermodal reader that is expected to provide the network (and zoning) used to place the GTFS stops and services on (see example below).

The EXTENDED GTFS RouteTypes (modes) are supported as defined in the GTFS specification. There is a default mapping available to PLANit predefined mode types, which may be altered by the user if so desired.

Methods

N/A

Properties

This class exposes the following properties:

Example

from planit import *

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

# Network reader to use to impose GTFS on:
#   Open Street Map (OSM) intermodal reader        
osm_reader = intermodal_converter.create_reader(IntermodalReaderType.OSM, "Australia")
osm_reader.settings.set_input_file(SYDNEY_OSM_PBF_FILE_PATH)

# GTFS reader
gtfs_reader: GtfsIntermodalReaderWrapper = \
    intermodal_converter.create_reader(IntermodalReaderType.GTFS, "Australia", osm_reader)
gtfs_reader.settings.set_input_file(SYDNEY_GTFS_FILE_PATH)

gtfs_reader.settings.services_settings.day_of_week = DayOfWeek.THURSDAY
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)
)

# PLANit writer
planit_writer = intermodal_converter.create_writer(IntermodalWriterType.PLANIT)
planit_writer.settings.set_output_directory(OUTPUT_PATH)
planit_writer.settings.set_country("Australia")

# perform conversion (with services)
intermodal_converter.convert_with_services(gtfs_reader, planit_writer)

See also

GtfsIntermodalReaderSettings for configuration of the GTFS intermodal reader OsmIntermodalReaderSettings for configuration of the OSM intermodal (network, zoning) reader
ConverterFactory for the converter factory to create other types of converters
IntermodalReaderType for the supported intermodal reader types
IntermodalWriterType for the supported intermodal writer types

Source code

Class GtfsIntermodalReaderWrapper in converterwrappers.py