quetzal.model.stepmodel module

class quetzal.model.stepmodel.StepModel(*args, **kwargs)[source]

Bases: quetzal.model.plotmodel.PlotModel, quetzal.model.analysismodel.AnalysisModel, quetzal.model.docmodel.DocModel

Object StepModelcontains most of the transport model with :

  • Attributes are the caracteristics of the model

  • Methods are the steps and functions of the model

zones

Zoning system of the model.

Type

geodataframe

Main columns

  • area

  • population

  • geometry

centroids

Centroids of the zoning system of the model. Usually created by method preparation_ntlegs.

Type

geodataframe

Main columns

  • area

  • population

  • geometry

segments

Demand segments of the model. Created by the user.

Type

list

volumes

Volumes per OD pair. Usually created by method step_distribution or user input.

Type

dataframe

Main columns

  • origin

  • destination

  • volume per demand segment

epsg

Projection

Type

string

Links of the public transport system and pt routes caracteristics. Each line of the geodataframe correspond to a section of a PT route between two nodes=stops (‘a’ and ‘b’). Usually created by shapefile importer or GTFS importer.

Type

geodataframe

Main columns

  • ‘a’ – initial nodes of the link

  • ‘b’ – final nodes of the link

  • ‘trip_id’

  • ‘route_id’

  • ‘service_id’

  • ‘direction_id’

  • ‘agency_id’

  • ‘route_short_name’

  • ‘route_long_name’

  • ‘route_type’ – mode of the line

  • ‘arrival_time’

  • ‘time’

  • ‘headway’

  • ‘link_sequence’

  • ‘departure_time’

  • ‘geometry’

  • ‘length’

  • ‘duration’

  • ‘cost’

  • ‘road_a’ – caracteristics of the roads sections which supports the link section (created by method preparation_cast_network)

  • ‘road_b’ – caracteristics of the roads sections which supports the link section (created by method preparation_cast_network)

  • ‘road_node_list’ – caracteristics of the roads sections which supports the link section (created by method preparation_cast_network)

  • ‘road_link_list’ – caracteristics of the roads sections which supports the link section (created by method preparation_cast_network)

  • ‘road_length’ – caracteristics of the roads sections which supports the link section (created by method preparation_cast_network)

  • ‘volume’ – results of the step_assignment

  • ‘boardings’ – results of the step_assignment

  • ‘alightings’ – results of the step_assignment

nodes

Public transport stations. Usually created by shapefile importer or GTFS importer.

Type

geodataframe

Main columns

  • geometry

  • name

Links (edges) of the road network - between two road_nodes. Usually created by shapefile importer or OSMNX.

Type

geodataframe

Main columns

  • ‘a’ – initial road_nodes of the road link

  • ‘b’ – final road_nodes of the road link

  • ‘length’ – caracteristics of the section

  • ‘geometry’ – caracteristics of the section

  • ‘time’ – caracteristics of the section

  • ‘walk_time’ – caracteristics of the section

  • ‘capacity’ – caracteristics of the section

  • ‘vdf’ – description of the jam function

  • ‘alpha’ – description of the jam function

  • ‘beta’ – description of the jam function

  • ‘limit’ – description of the jam function

  • ‘penalty’ – description of the jam function

  • ‘flow’ – results of the step_road_pathfinder

  • ‘jam_time’ – results of the step_road_pathfinder

road_nodes

Nodes of the road network. Usually created by shapefile importer or OSMNX.

Type

geodataframe

Main columns

geometry

zone_to_road

Connectors, aka non-transit leg (ntleg), from zones to road_nodes. Usually created by method preparation_ntlegs.

Type

geodataframe

Main columns

  • initial and final zone/road_nodes of the ntleg (‘a’, ‘b’)

  • description of the ntleg (‘rank’, ‘distance’, ‘geometry’, ‘direction’)

  • description og the speed and time (‘speed_factor’, ‘short_leg_speed’, ‘long_leg_speed’, ‘speed’, ‘time’, ‘walk_time’)

zone_to_transit

Connectors, aka non-transit leg (ntleg), from zones to nodes (PT stations). Usually created by method preparation_ntlegs.

Type

geodataframe

Main columns

  • initial and final zone/nodes(stop) of the ntleg (‘a’, ‘b’)

  • description of the ntleg (‘rank’, ‘distance’, ‘geometry’, ‘direction’)

  • description og the speed and time (‘speed_factor’, ‘short_leg_speed’, ‘long_leg_speed’, ‘speed’, ‘time’, ‘walk_time’)

road_to_transit

Connectors, aka non-transit leg (ntleg), from road_nodes to nodes (pt stations). Usually created by method preparation_ntlegs.

Type

geodataframe

Main columns

  • initial and final node/road_nodes of the ntleg (‘a’, ‘b’)

  • description of the ntleg (‘rank’, ‘distance’, ‘geometry’, ‘direction’)

  • description og the speed and time (‘speed_factor’, ‘short_leg_speed’, ‘long_leg_speed’, ‘speed’, ‘time’, ‘walk_time’)

footpaths

Pedestrian links between stations to allow connections. Usually created by method preparation_footpaths.

Type

geodataframe

Main columns

  • ‘a’

  • ‘b’

  • ‘geometry’

  • ‘time’

pt_los

Level of service of the pt network - for each OD pair, possible paths and their caracteristics. Each line of the df being a path. Usually created by method step_pt_pathfinder.

Type

dataframe

Main columns

  • OD pair (‘origin’, ‘destination’)

  • description of the path (‘gtime’, ‘path’, ‘pathfinder_session’, ‘reversed’, ‘all_walk’, ‘ntransfers’, ‘time_link_path’, ‘length_link_path’)

  • links taken by the path (‘link_path’, ‘footpaths’, ‘ntlegs’, ‘boarding_links’, ‘alighting_links’)

  • nodes where transfer is made (‘boardings’, ‘alightings’, ‘transfers’, ‘node_path’)

  • results of the step_logit (utilities (per demand segment), probabilities (per demand segment))

car_los

Level of service of the car network - for each OD pair results of pathfinder with/without capacity restriction. Usually created by method step_road_pathfinder.

Type

dataframe

Main columns

  • OD pair (‘origin’, ‘destination’)

  • description of the path (‘time’, ‘path’, ‘gtime’)

pr_los

Level of service of the park and ride network - for each OD pair, possible paths and their caracteristics. Each line of the df being a path. Usually created by method step_pr_pathfinder.

Type

dataframe

Main columns

  • OD pair (‘origin’, ‘destination’)

  • description of the path (‘gtime’, ‘path’, ‘pathfinder_session’, ‘reversed’, ‘all_walk’, ‘ntransfers’, ‘time_link_path’, ‘length_link_path’)

  • links taken by the path (‘link_path’, ‘footpaths’, ‘ntlegs’, ‘boarding_links’, ‘alighting_links’)

  • nodes where transfer is made (‘boardings’, ‘alightings’, ‘transfers’, ‘node_path’)

  • results of the step_logit (utilities (per demand segment), probabilities (per demand segment))

los

Concatenation of the two tables pt_los and car_los to perform logit

Type

dataframe

utility_values

Values of the utility parameters per mode per segment. Usually created by method preparation_logit - with parameters from the parameters file

Type

dataframe

mode_utility

Modal constants per mode per segment. Usually created by method preparation_logit - with parameters from the parameters file

Type

dataframe

mode_nests

Structure of the nested logit. Usually created by method preparation_logit - with parameters from the parameters file

Type

dataframe

logit_scales

Parameter phi of the nested logit. Usually created by method preparation_logit - with parameters from the parameters file

Type

dataframe

utilities

Agregaded utilities per OD per mode. Usually created by method step_logit.

Type

dataframe

probabilities

Agregaded probabilities per OD per mode. Usually created by method step_logit.

Type

dataframe

add_type_prefixes(prefixes={'links': 'link_', 'nodes': 'node_', 'zones': 'zone_'})

deprecated! * requires: links, nodes, zones * builds: links, nodes, zones

assert_convex_road_digraph()

deprecated! * requires: road_links

assert_lines_integrity()

deprecated! * requires: links * builds: broken_sequences

assert_no_circular_lines()

deprecated! The model does not work with circular lines

  • requires: links

  • builds: circular_lines

assert_no_collision(sets=('links', 'nodes', 'zones', 'road_links', 'road_nodes'))

deprecated! * requires: links, nodes, zones

assert_no_dead_ends(cutoff=5)

deprecated! look for dead-ends in the road network only the dead-ends with a dead-rank lower than the cutoff will be identified

  • requires: road_links

assert_nodeset_consistency()

deprecated! * requires: nodes, links

build_lines(line_columns='all', group_id='trip_id', *args, **kwargs)

deprecated! None

checkpoints(link_checkpoints=(), node_checkpoints=(), **loaded_links_and_nodes_kwargs)

deprecated! tree analysis (arborescences) :param link_checkpoints: mandatory transit links collection (set) :param nodes_checkpoints: mandatory transit nodes :param volume column: column of self.od_stack to assign :loaded_links_and_nodes_kwargs: …

example:

sm.checkpoints(link_checkpoints = {}, node_checkpoints={41})
export.assigned_links_nodes_to_shp(
    sm.checkpoint_links,
    sm.checkpoint_nodes,
    gis_path=gis_path,
    link_name='links_test.shp',
    node_name='nodes_test.shp'

)

clean_road_network(cutoff=10, recursive_depth=1)

deprecated! clean road_network

  • requires: road_links, road_nodes

  • builds: road_links, road_nodes

get_lines_integrity()

deprecated! * requires: links * builds: links

get_no_circular_lines()

deprecated! * requires: links * builds: links

get_no_collision(prefixes={'links': 'link_', 'nodes': 'node_', 'zones': 'zone_'})

deprecated! * requires: links, nodes, zones * builds: links, nodes, zones

linear_solver(constrained_links, nb_clusters=20, cluster_column=None, link_path_column='link_path', linprog_kwargs={'bounds_A': [0.75, 1.5], 'bounds_emissions': [0.8, 1.2], 'bounds_tot_emissions': [0.95, 1.05], 'maxiter': 3000, 'pas_distance': 200, 'tolerance': 1e-05}, **kwargs)

deprecated! To perform the optimization on a model object once it is built and run, in order to match the observed volumes.

  • requires: od_stack, constrained_links

  • builds: aggregated model, pivot_stack_matrix

Le but de linear_solver est de modifier la matrice des volumes par OD en la multipliant par un pivot, afin de coller aux observations recueillies sur certains nœuds/liens du réseau. Etapes: 0. Construction de l’indicatrice (matrice qui indique la présence des

liens contraints dans chaque OD)

  1. Agrégation du modèle.

  2. Résolution du problème d’optimisation linéaire pour construire

    pivot_stack_matrix (matrice pivot). Plus de détails dans linearsolver_utils.

  3. Désagrégation de la matrice pivot pour revenir au modèle de base.

renumber(max_zones=500, cluster_column=None, is_od_stack=False, **kwargs)

deprecated! Clusterize zones to optimize computation time.

Requires

  • self.zones

  • self.volumes

Parameters

  • max_zones (int, optional, default 500) – _description_, by

  • cluster_column (string, optional, default None) – cluster column in self.zones if clusters are already defined

  • is_od_stack (bool, optional, default False) – If True, requires table od_stack

Builds

  • self.zones

  • self.volumes

  • self.cluster_series

renumber_nodes(n_clusters=None, adaptive_clustering=False, **kwargs)
deprecated! Create nodes clusters to optimize computation time.

It will agregate nodes based on their relative distance to build “stop areas”

Requires

self.nodes

Parameters

  • n_clusters (int, optional, default None) – Number of nodes clusters

  • adaptive_clustering (bool, optional, default False) – If True, will define itself the number of clusters. If False n_clusters must be defined

Builds

  • self.links – contain recomputed links with the clusterized nodes

  • self.nodes – contain the clusterized nodes

  • self.disaggregated_nodes – contain the former nodes

step_analysis()

deprecated! To perform on a model object once it is built and run, aggregate and analyses results.

  • requires: shared, zones, loaded_links, od_stack

  • builds: aggregated_shares, lines, economic_series

step_cast_network(nearest_method='nodes', weight='length', penalty_factor=1, speed=3, replace_nodes=False, dumb_cast=False, **nc_kwargs)

deprecated! Finds a path for the transport lines in the actual road network, to know on which roads a bus line is going, because the public transport links are defined between two stops, without road information. It will evaluate the best combination of nodes in the road network between the two stops. The evaluation is done with the distance. The results will be found as a list of road_links for each public transport link. If the transport network has modes on dedicated infrastructure (train, metro…), create two submodels and use a dumbcast on the dedicated infrastructure modes.

Requires

  • self.nodes

  • self.links

  • self.road_nodes

  • self.road_links

Parameters

  • nearest_method (['nodes'|'links'], optional, default 'nodes') –

    Options are:

    ’nodes’ –(default) looks for the actual nearest node in road_nodes. ‘links’ –looks for the nearest link to a stop in road_links and links the stop to its end_node (b)

  • weight (str, optional, default 'length') – Column of road_links containing road_links length

  • penalty_factor (int, optional, default 1) – Multiplicative penality of weight

  • speed (int, optional, default 3) – Walk speed

  • replace_nodes (bool, optional, default False) – If True replaces nodes by road_nodes. If False, model will use road_to_transit ntlegs

  • dumb_cast (bool, optional, default False) – If True, the network is casted on himself (cast links on links and not on road_links). It will still return the closest road_node for the stops.

  • nodes_checkpoints – mandatory transit nodes

Builds

self.links – add columns road_a, road_b, road_node_list, road_link_list, road_length

step_desire(store_shp=False, **to_shp_kwarg)

deprecated! Builds the desire matrix

  • requires: zones, shares

  • builds: neighborhood, macro_neighborhood

step_footpaths(road=False, speed=3, max_length=None, n_clusters=None, **kwargs)

deprecated! Create the footpaths : pedestrian links between stations (nodes), that will allow transfers between stations.

Requires

self.nodes

Parameters

  • road (bool, optional, default False) – If True, compute walk_time on road_links based on parameter speed

  • speed (int, optional, default 3) – Speed of walk on footpaths. Smaller than real walk speed because the footpaths do not follow roads

  • max_length (int, optional, default None) – Maximal length of footpaths

  • n_clusters (int, optional, default None) – Number of nodes clusters : create nodes clusters to optimize computation time. It will agregate nodes based on their relative distance to build “stop areas”

Builds

  • self.footpaths

  • self.road_links – add columns walk_time if road=True

step_modal_split(build_od_stack=True, **modal_split_kwargs)

deprecated! Performs modal split. Use only for simple models with the modes Public Transport and Car, with few details : only based on duration and modal penalties. Based on modes demand and levels of services, it returns the volume by mode. Does not include price. For modal split, prefer the use of function step_logit

  • Utility(car) = alpha_car * ‘duration_car’ + beta_car

  • Utility(pt) = ‘duration_pt’

Requires

  • self.volumes – all mode origin->destination demand matrix

  • self.los – levels of service. An od stack matrix with ‘duration_pt’ and ‘duration_car’

Parameters

  • build_od_stack (bool, optional) – _description_, by default True

  • time_scale (float) – time scale of the logistic regression that compares utilities. Defines selectiveness. Defined as 1/(utility value of time, in seconds)

  • alpha_car (float) – multiplicative penalty on ‘duration_car’ for the calculation of ‘utility_car’

  • beta_car (float) – additive penalty on ‘duration_car’ for the calculation of ‘utility_car’

Builds

  • self.od_stack

  • self.shared

Examples

::
los = pd.merge(

car_los, pt_los, on=[‘origin’, ‘destination’], suffixes=[‘_car’, ‘_pt’]

)

sm.step_modal_split(

time_scale=1/1800, alpha_car=2, beta_car=600

)

step_ntlegs(short_leg_speed=2, long_leg_speed=10, threshold=1000, n_ntlegs=5, max_ntleg_length=5000, zone_to_transit=True, zone_to_road=False, prefix=False)

deprecated! Builds the centroids and the non-transit links/legs (ntlegs), also known as connectors. Pameters short_leg_speed and long_leg_speed allow to model diferent types of access to the network (PT/private): for short connectors, the short_leg_speed is used - it represents a walk speed. For long connectors, which will occur for large zones at the edge of the study area, we may want to consider that the access to the network is made by car/taxi, and hence at a larger speed, the long_leg_speed. Function integrates a curve to smoothly go from short_leg_speed to long_leg_speed (can be understood as probability to access by foot or car).

Requires

  • self.nodes

  • self.zones

Parameters

  • short_leg_speed (int, optional, default 2) – Speed of the short legs, in km/h

  • long_leg_speed (int, optional, default 10) – Speed of the short legs, in km/h

  • threshold (int, optional, default 1000) – Threshold for the definition of the short and long legs

  • n_ntlegs (int, optional, default 5) – Number of ntlegs to create per zone (and per type)

  • max_ntleg_length (int, optional, default 5000) – maximal length of the ntlegs, in m

  • zone_to_transit (bool, optional, default True) – True to create links between zones and transit stops (nodes)

  • zone_to_road (bool, optional, default False) – True to create links between zones and road_nodes, and between road_nodes and nodes

  • prefix (bool, optional, default False) – If True, add prefixes to the index of the ntlegs ztt_ (zone_to_transit), ztr_ (zone_to_road), rtt_ (road_to_transit)

Builds

  • self.centroids

  • self.zone_to_transit

  • self.zone_to_road

  • self.road_to_transit

Examples

::
sm.step_ntlegs(

n_ntlegs=5, walk_speed=2, short_leg_speed=3, long_leg_speed=15, threshold=500, max_ntleg_length=5000

)

step_pathfinder(broken_routes=True, broken_modes=True, route_column='route_id', mode_column='route_type', boarding_time=None, speedup=False, walk_on_road=False, keep_pathfinder=False, force=False, path_analysis=True, **kwargs)

deprecated! Performs public transport pathfinder.

With :

  • all or nothing Diskjstra algorithm if broken_routes=False AND broken_modes=False

  • Prunning algorithm if broken_routes=True OR/AND broken_modes=True

For optimal strategy pathfinder, use step_pt_pathfinder of the class OptimalModel

For connection scan pathfinder algorithm (with time tables), use step_pt_pathfinder of the class ConnectionScanModel.

Requires

  • self.zones

  • self.links

  • self.footpaths

  • self.zone_to_road

  • self.zone_to_transit

Parameters

  • broken_routes (bool, optional, default True) – If True, will perform the route breaker of the pathfinder prunning algorithm with the different routes found in the route_column

  • broken_modes (bool, optional, default True) – If True, will perform the mode breaker of the pathfinder prunning algorithm with the different modes found in the mode_column

  • route_column (str, optional, default 'route_id') – columns of the self.links containing the routes identifier (prunning algorithm)

  • mode_column (str, optional, default 'route_type') – columns of the self.links containing the modes identifier (prunning algorithm)

  • boarding_time (float, optional, default None) – aditional boarding time

  • alighting_time (float, optional, default None) – aditional alighting time

  • speedup (bool, optional, default False) – Speed up the computation time, by

  • walk_on_road (bool, optional, default False) – If True, will consider using the road network and zone_to_road for pedestrian paths. Warning : it will only compare those paths using the raod network with the paths using pedestrian links (footpaths, zone_to_transit) Force the use of road network for pedestrian paths by NOT defining footpaths and zone_to_transit

  • keep_pathfinder (bool, optional, default False) – If True, keeps all computation steps of the pathfinder Use to performed advanced route and mode breaker (without the need to create submodel for route_breaker, for example)

  • force (bool, optional, default False) – If True, will NOT perform integrity_test_collision on the ‘nodes’, ‘links’, ‘zones’,’road_nodes’, ‘road_links’.

  • path_analysis (bool, optional, default True) – Performs paths analysis, adds columns ‘all_walk’ and ‘ntransfers’ to the output pt_los

Builds

self.pt_los

quetzal.model.stepmodel.read_hdf(filepath, *args, **kwargs)[source]
quetzal.model.stepmodel.read_json(folder, **kwargs)[source]
quetzal.model.stepmodel.read_zip(filepath, *args, **kwargs)[source]
quetzal.model.stepmodel.read_zipped_hdf(filepath, *args, **kwargs)[source]
quetzal.model.stepmodel.read_zippedpickles(folder, *args, **kwarg)[source]