Public API

path4gmns.accessibility

path4gmns.accessibility.evaluate_accessibility(ui, single_mode=False, mode='auto', time_dependent=False, demand_period_id=0, output_dir='.')[source]

perform accessibility evaluation for a target mode or more

Parameters

  • ui – network object generated by pg.read_network()

  • single_mode –

    True or False. Its default value is False. It will only affect the output to zone_accessibility.csv.

    If False, the accessibility evaluation will be conducted for all the modes defined in settings.yml. The number of accessible zones from each zone under each defined mode given a budget time (up to 240 minutes) will be outputted to zone_accessibility.csv.

    If True, the accessibility evaluation will be only conducted against the target mode. The number of accessible zones from each zone under the target mode given a budget time (up to 240 minutes) will be outputted to zone_accessibility.csv.

  • mode – target mode with its default value as ‘auto’. It can be either agent type or its name. For example, ‘w’ and ‘walk’ are equivalent inputs.

  • time_dependent –

    True or False. Its default value is False.

    If True, the accessibility will be evaluated using the period link free-flow travel time (i.e., VDF_fftt). In other words, the accessibility is time-dependent.

    If False, the accessibility will be evaluated using the link length and the free flow travel speed of each mode.

  • demand_period_id –

    The sequence number of demand period listed in demand_periods in settings.yml. demand_period_id of the first demand_period is 0.

    Use it with time_dependent when there are multiple demand periods. Its default value is 0.

  • output_dir – The directory path where zone_accessibility.csv and od_accessibility.csv are output. The default is the current working directory (CDW).

Returns

Return type

None

Note

The following files will be output.

zone_accessibility.csv

accessibility as the number of accessible zones from each zone for a target mode or any mode defined in settings.yml given a budget time (up to 240 minutes).

od_accessibility.csv:

accessibility between each OD pair in terms of free flow travel time.

path4gmns.accessibility.evaluate_equity(ui, single_mode=False, mode='auto', time_dependent=False, demand_period_id=0, time_budget=60, output_dir='.')[source]

evaluate equity for each zone under a time budget

Parameters

  • ui – network object generated by pg.read_network()

  • single_mode –

    True or False. Its default value is False. It will only affect the output to zone_accessibility.csv.

    If False, the equity evaluation will be conducted for all the modes defined in settings.yml.

    If True, the equity evaluation will be only conducted against the target mode.

  • mode – target mode with its default value as ‘auto’. It can be either agent type or its name. For example, ‘w’ and ‘walk’ are equivalent inputs.

  • time_dependent –

    True or False. Its default value is False.

    If True, the accessibility will be evaluated using the period link free-flow travel time (i.e., VDF_fftt). In other words, the accessibility is time-dependent.

    If False, the accessibility will be evaluated using the link length and the free flow travel speed of each mode.

  • demand_period_id –

    The sequence number of demand period listed in demand_periods in settings.yml. demand_period_id of the first demand_period is 0.

    Use it with time_dependent when there are multiple demand periods. Its default value is 0.

  • time_budget – the amount of time to travel in minutes

  • output_dir – The directory path where the evaluation result is output. The default is the current working directory (CDW).

Returns

Return type

None

Note

The following file will be output.

equity_str.csv

equity statistics including minimum accessibility (and the corresponding zone), maximum accessibility (and the corresponding zone), and mean accessibility for each bin_index. The accessible zones will be output as well.

str in the file name refers to the time budget. For example, the file name will be equity_60min.csv if the time budget is 60 min.

path4gmns.classes

class path4gmns.classes.UI(assignment)[source]

an abstract class only with user interfaces

find_path_for_agents(mode='all', cost_type='time')[source]

DEPRECATED

find and set up shortest path for each agent

Parameters

  • mode –

    the target transportation mode which is defined in settings.yml. It can be either agent type or its name. For example, ‘w’ and ‘walk’ are equivalent inputs.

    The default is ‘all’, which means that links are open to all modes.

  • cost_type – ‘time’ or ‘distance’. find the shortest path according travel time or travel distance.

Returns

Return type

None

find_shortest_path(from_node_id, to_node_id, mode='all', seq_type='node', cost_type='time')[source]

return shortest path between from_node_id and to_node_id

Parameters

  • from_node_id – the starting node id

  • to_node_id – the ending node id

  • mode –

    the target transportation mode which is defined in settings.yml. It can be either agent type or its name. For example, ‘w’ and ‘walk’ are equivalent inputs.

    The default is ‘all’, which means that links are open to all modes.

  • seq_type – ‘node’ or ‘link’. You will get the shortest path in sequence of either node IDs or link IDs. The default is ‘node’.

  • cost_type – ‘time’ or ‘distance’. find the shortest path according travel time or travel distance.

Returns

the shortest path between from_node_id and to_node_id.

Return type

str

Note

Exceptions will be thrown if either of from_node_id and and to_node_id is not valid node IDs.

get the accessible links from a node given mode and time budget

Parameters

  • source_node_id – the starting node id for evaluation, which shall be string

  • time_budget – the amount of time to travel in minutes

  • mode –

    the target transportation mode which is defined in settings.yml. It can be either agent type or its name. For example, ‘w’ and ‘walk’ are equivalent inputs.

    The default is ‘auto’.

  • time_dependent –

    True or False. Its default value is False.

    If True, the accessibility will be evaluated using the period link free-flow travel time (i.e., VDF_fftt). In other words, the accessibility is time-dependent.

    If False, the accessibility will be evaluated using the link length and the free flow travel speed of each mode.

  • demand_period_id –

    The sequence number of demand period listed in demand_periods in settings.yml. demand_period_id of the first demand_period is 0.

    Use it with time_dependent when there are multiple demand periods. Its default value is 0.

Returns

the number of links that can be accessible from source_node_id given time_budget and mode, and the link list

Return type

int

get_accessible_nodes(source_node_id, time_budget, mode='auto', time_dependent=False, demand_period_id=0)[source]

get the accessible nodes from a node given mode and time budget

Parameters

  • source_node_id – the starting node id for evaluation, which shall be string

  • time_budget – the amount of time to travel in minutes

  • mode –

    the target transportation mode which is defined in settings.yml. It can be either agent type or its name. For example, ‘w’ and ‘walk’ are equivalent inputs. Its default value is ‘a’ (i.e., mode auto).

    The default is ‘auto’.

  • time_dependent –

    True or False. Its default value is False.

    If True, the accessibility will be evaluated using the period link free-flow travel time (i.e., VDF_fftt). In other words, the accessibility is time-dependent.

    If False, the accessibility will be evaluated using the link length and the free flow travel speed of each mode.

  • demand_period_id –

    The sequence number of demand period listed in demand_periods in settings.yml. demand_period_id of the first demand_period is 0.

    Use it with time_dependent when there are multiple demand periods. Its default value is 0.

Returns

the number of nodes that can be accessible from source_node_id given time_budget and mode, and the node list

Return type

int

get_agent_dest_node_id(agent_id)[source]

return the destination node id of an agent

return the sequence of link IDs along the agent path

get_agent_node_path(agent_id)[source]

return the sequence of node IDs along the agent path

get_agent_orig_node_id(agent_id)[source]

return the origin node id of an agent

get_column_vec(at, dp, orig_zone_id, dest_zone_id)[source]

get all columns between two zones given agent type and demand period

caller is responsible for checking if (at, dp, orig_zone_id, dest_zone_id) is in column pool

get_demand_period_str(demand_period_id)[source]

return the demand period name given its id

Parameters

demand_period_id –

The sequence number of demand period listed in demand_periods in settings.yml. demand_period_id of the first demand_period is 0.

Use it with time_dependent when there are multiple demand periods. Its default value is 0.

Returns

The name of the corresponding demand period given demand_period_id ( e.g., ‘AM’).

Return type

str

get_shortest_path_tree(from_node_id, mode='all', seq_type='node', cost_type='time')[source]

return the shorest path tree from the source node (from_node_id)

Parameters

  • from_node_id – the source (root) node id

  • mode –

    the target transportation mode which is defined in settings.yml. It can be either agent type or its name. For example, ‘w’ and ‘walk’ are equivalent inputs.

    The default is ‘all’, which means that links are open to all modes.

  • seq_type – ‘node’ or ‘link’. You will get the shortest path in sequence of either node IDs or link IDs. The default is ‘node’.

  • cost_type – ‘time’ or ‘distance’. find the shortest path according travel time or travel distance.

Returns

shortest paths from the source node to any other nodes (the source node itself is excluded).

key is to_node_id and value is the corresponding shortest path information including path cost and path details (as a tuple).

path cost and path details are in line with the specified cost_type and seq_type.

Return type

dictionary

path4gmns.dtaapi

path4gmns.dtaapi.DTALiteClassic(assignment_mode, column_gen_num, column_upd_num)[source]

Python interface to call the classic DTALite with the selected assignment mode

https://github.com/jdlph/DTALite

Warning

MAKE SURE TO BACKUP route_assignment.csv and link_performance.csv if you have called find_ue() before. Otherwise, they will be overwritten by results generated by DTALite.

Parameters

  • assignment_mode –

    0: Link-based UE, only generates link performance file without agent path file

    1: Path-based UE, generates link performance file and agent path file

    2: UE + dynamic traffic assignment (DTA), generates link performance file and agent path file

    3: ODME

  • column_gen_num – number of iterations to be performed before on generating column pool

  • column_upd_num – number of iterations to be performed on optimizing column pool

Returns

Return type

None

Note

The output will depend on the selected assignment_mode.

Link-based UE: link_performance.csv

Path-based UE: route_assignment.csv and link_performance.csv

UE + DTA: route_assignment.csv and link_performance.csv

route_assignment.csv: paths/columns

link_performance.csv: assigned volumes and other link attributes on each link

path4gmns.dtaapi.DTALiteMultimodal()[source]

Python interface to call the multimodal DTALite

This version of DTALite includes all-new Logbook, enhanced scenario handling, improved I/O functionality, and so on.

Its source code can be found at https://github.com/asu-trans-ai-lab/DTALite/tree/feature/multimodal.

Parameters

None –

Returns

Return type

None

Note

It is NOT compatible with the classic DTALite (i.e., DTALiteClassic()).

Only use the following data set from https://github.com/asu-trans-ai-lab/DTALite/tree/feature/multimodal/data.

Please run the script calling this API using your system terminal rather than Python console for proper logging.

path4gmns.dtaapi.perform_network_assignment_DTALite(assignment_mode, column_gen_num, column_upd_num)[source]

DEPRECATED Python interface to call the classic DTALite

https://github.com/jdlph/DTALite

path4gmns.dtaapi.run_DTALite()[source]

DEPRECATED Python interface to call the multimodal DTALite

https://github.com/asu-trans-ai-lab/DTALite/tree/feature/multimodal

path4gmns.conduct_odme

path4gmns.odme.conduct_odme(ui, odme_update_num, dp_id=0)[source]

calibrate traffic assignment results using traffic observations

Parameters

  • ui – network object generated by pg.read_network()

  • odme_update_num – number of iterations to be performed on ODME

  • dp_id –

    The sequence number of demand period listed in demand_periods in settings.yml. Its default value is 0.

    The current implementation of ODME only supports one demand period.

Returns

Return type

None

Note

You will need to call output_columns() and output_link_performance() to get the calibrated assignment results (i.e., paths/columns) in route_assignment.csv and link volumes (and other link attributes) in link_performance.csv.

path4gmns.colgen

path4gmns.colgen.find_ue(ui, column_gen_num, column_upd_num, rel_gap_tolerance=0.0001)[source]

find user equilibrium (UE)

Warning

Only Path/Column-based User Equilibrium (UE) is implemented in Python. If you need other assignment modes or dynamic traffic assignment (DTA), please use DTALiteClassic()

Parameters

  • ui – network object generated by pg.read_network()

  • column_gen_num – number of iterations to be performed on generating column pool column pool. it also specifies the maximum number of routes / columns for each OD pair.

  • column_upd_num – number of iterations to be performed on optimizing column pool

  • rel_gap_tolerance – target relative gap. find_ue() stops when either column_upd_num or rel_gap_tolerance is reached.

Returns

relative GAP to measure the UE convergency

Return type

rel_gap

Note

You will need to call output_columns() and output_link_performance() to get the assignment results, i.e., paths/columns (in route_assignment.csv) and volumes and other link attributes on each link (in link_performance.csv).

path4gmns.fw

path4gmns.fw.find_ue_fw(ui, max_iter=40, rel_gap_tolerance=0.0001)[source]

find user equilibrium (UE) with the Frank-Wolfe Algorithm

Warning

It does not preserve any paths/columns during the assignment process. If you need paths/columns (in route_assignment.csv), please use the path-based UE module: find_ue().

Parameters

  • ui – network object generated by pg.read_network()

  • max_iter – maximum number of iterations to be performed on finding UE. Default is 40.

  • rel_gap_tolerance – target relative gap. find_ue_fw() stops when either max_iter or rel_gap_tolerance is reached.

Returns

relative GAP to measure the UE convergency

Return type

rel_gap

Note

You will need to call output_link_performance() to get the assignment results, i.e., volumes and other link attributes on each link (in link_performance.csv).

path4gmns.io

path4gmns.io.read_demand(ui, use_synthetic_data=False, save_synthetic_data=True, input_dir='.')[source]

a dedicated API to read demand and zone information

path4gmns.io.read_measurements(ui, input_dir='.')[source]

load traffic observations specified in measurement.csv

path4gmns.io.read_network(length_unit='mile', speed_unit='mph', input_dir='.')[source]
path4gmns.io.load_demand(ui, agent_type_str='a', demand_period_str='AM', input_dir='.', filename='demand.csv')[source]

load demand for an agent type and a demand period

this is an user interface while _read_demand() is intended for internal use.

path4gmns.io.load_columns(ui, input_dir='.')[source]
path4gmns.io.output_columns(ui, output_geometry=False, output_dir='.')[source]
path4gmns.io.output_agent_paths(ui, output_geometry=True, output_dir='.')[source]

output unique agent path

use it with find_path_for_agents() (which has been DEPRECATED)

path4gmns.io.output_agent_trajectory(ui, output_dir='.')[source]
path4gmns.io.output_synthetic_zones(ui, output_dir='.')[source]
path4gmns.io.output_synthetic_demand(ui, output_dir='.')[source]

path4gmns.simulation

path4gmns.simulation.perform_simple_simulation(ui, loading_profile='uniform')[source]

perform simple traffic simulation using point queue model

Warning

The underlying routing decision is made through find_path_for_agents(), which must be called before this function.

Parameters

  • ui – network object generated by pg.read_network()

  • loading_profile –

    demand loading profile, i.e., how agents are loaded to network with respect to their departure times. Three loading profiles are supported, which are uniform, random, and constant.

    With uniform loading profile, agents will be uniformly distributed between [simulation start time, simulation start time + simulation duration).

    With random loading profile, the departure time of each agent is randomly set up between [simulation start time, simulation start time + simulation duration).

    With constant loading profile, the departure times of all agents are the same, which are simulation start time.

Returns

Return type

None

Note

You will need to call output_agent_trajectory() to get the simulation results, i.e., trajectory of each agent (in trajectory.csv).

path4gmns.utils

path4gmns.utils.download_sample_data_sets()[source]

DEPRECATED in 0.10.0. Please use download_sample_datasets().

download sample data sets from the Github repo

the following data sets will be downloaded: ASU, Braess Paradox, Chicago Sketch, Lima Network, Sioux Falls, and Two Corridors.

path4gmns.utils.download_sample_datasets(repo_name='Path4GMNS')[source]

download sample datasets from the Github repository

The following six datasets will be downloaded: ASU, Braess Paradox, Chicago Sketch, Lima Network, Sioux Falls, and Two Corridors.

Parameters

repo_name – the target repository name, which shall be either Path4GMNS or DTALite. The default value is Path4GMNS.

Returns

Return type

None

Note

The sample dataset will be downloaded to the current working directory (CWD).

path4gmns.utils.download_sample_setting_file()[source]

download the sample settings.yml from the Github repo

path4gmns.utils.get_python_ver()[source]

path4gmns.zonesyn

path4gmns.zonesyn.network_to_zones(ui, grid_dimension=8, max_bin=5, total_demand=100000, time_budget=120, mode='auto')[source]

synthesize zones and OD demand given a network

Parameters

  • ui – network object generated by pg.read_network().

  • grid_dimension – positive integer. If its value is d, a total of d * d zones will be synthesized.

  • max_bin – positive integer. The maximum number of bin_idex generated for synthesized zones.

  • total_demand –

    The total demand or the total number of trips to be allocated to the OD demand matrix. it should be a positive integer.

    The allocated demand to each zone is proportional to the number of its activity nodes. Given an origin zone, its production volume will be proportionally allocated to each connected destination zone. Gravity Model is NOT in use.

    note that the summation of demand over each OD pair is roughly the same as total_demand due to rounding errors.

  • time_budget – the amount of time to travel in minutes, which is used to cut off the demand allocation. If the minimum travel time between an OD pair under a specific mode is greater than time_budget, we consider that the two zones are not connected and no demand will be allocated between them.

  • mode –

    target mode with its default value as ‘auto’. It can be either agent type or its name. For example, ‘w’ and ‘walk’ are equivalent inputs.

    It is used along with time_budget to check if the minimum travel time under the given mode exceeds the time budget or not.

Returns

Return type

None

Note

The following files will be output.

zone.csv.csv

synthesized zones including zone id, activity nodes, coordinates of its centroid, it boundaries (as a grid or rectangle), production volume, and attraction volume.

zone_id will be an integer starting from one.

syn_demand.csv

synthesized demand between each connected OD pair (within a time budget).