aequilibrae.paths.RouteChoice

class aequilibrae.paths.RouteChoice(graph: Graph, project=None)

__init__(graph: Graph, project=None)

Methods

__init__(graph[, project])
add_demand(demand[, fill])	Add demand DataFrame or matrix for the assignment.
execute([perform_assignment])	Generate route choice sets between the previously supplied nodes, potentially performing an assignment.
execute_single(origin, destination[, demand])	Generate route choice sets between origin and destination, potentially performing an assignment.
get_load_results()	Translates the link loading results from the graph format into the network format.
get_results()	Returns the results of the route choice procedure
get_select_link_loading_results()	Get the select link loading results.
get_select_link_od_matrix_results()	Get the select link OD matrix results as a sparse matrix.
info()	Returns information for the transit assignment procedure
log_specification()
prepare([nodes])	Prepare OD pairs for batch computation.
save_link_flows(table_name[, project])	Saves the link link flows for all classes into the results database.
save_select_link_flows(table_name[, project])	Saves the select link link flows for all classes into the results database.
set_choice_set_generation(algorithm, **kwargs)	Chooses the assignment algorithm and set parameters.
set_cores(cores)	Allows one to set the number of cores to be used
set_save_path_files(save_it)	turn path saving on or off.
set_save_routes([where])	Set save path for route choice results.
set_select_links(links[, link_loading])	Set the selected links.

Attributes

all_algorithms
default_parameters
demand_index_names

add_demand(demand, fill: float = 0.0)

Add demand DataFrame or matrix for the assignment.

Arguments:

demand (Union[pd.DataFrame, AequilibraeMatrix]): Demand to add to assignment. If the supplied demand is a DataFrame, it should have a 2-level MultiIndex of Origin and Destination node IDs. If an AequilibraE Matrix is supplied node IDs will be inferred from the index. Demand values should be either ``float32``s or ``float64``s.

fill (float): Value to fill any ``NaN``s with.

execute(perform_assignment: bool = True) → None

Generate route choice sets between the previously supplied nodes, potentially performing an assignment.

To access results see RouteChoice.get_results().

Arguments:

perform_assignment (bool): Whether or not to perform an assignment. Defaults to False.

execute_single(origin: int, destination: int, demand: float = 0.0) → List[Tuple[int]]

Generate route choice sets between origin and destination, potentially performing an assignment.

Does not require preparation.

Node IDs must be present in the compressed graph. To make a node ID always appear in the compressed graph add it as a centroid.

Arguments:

origin (int): Origin node ID.

destination (int): Destination node ID.

demand (float): If provided an assignment will be performed with this demand.

Returns:

route set (List[Tuple[int]]): A list of routes as tuples of link IDs.

get_load_results() → DataFrame

Translates the link loading results from the graph format into the network format.

Returns:

dataset (Union[Tuple[pd.DataFrame, pd.DataFrame], pd.DataFrame]): A tuple of link loading results as DataFrames. Columns are the matrix name concatenated direction.

get_results() → Table | Dataset

Returns the results of the route choice procedure

Returns a table of OD pairs to lists of link IDs for each OD pair provided (as columns). Represents paths from origin to destination.

If save_routes was specified then a Pyarrow dataset is returned. The caller is responsible for reading this dataset.

Returns:

results (pa.Table): Table with the results of the route choice procedure

get_select_link_loading_results() → DataFrame

Get the select link loading results.

Returns:

dataset (Tuple[pd.DataFrame, pd.DataFrame]): Select link loading results as DataFrames. Columns are the matrix name concatenated with the select link set and direction.

get_select_link_od_matrix_results() → Dict[str, Dict[str, coo_matrix]]

Get the select link OD matrix results as a sparse matrix.

Returns:

select link OD matrix results (Dict[str, Dict[str, scipy.sparse.coo_matrix]]): Returns a dict of select link set names to a dict of demand column names to a sparse OD matrix

info() → dict

Returns information for the transit assignment procedure

Dictionary contains keys ‘Algorithm’, ‘Matrix totals’, ‘Computer name’, ‘Procedure ID’, ‘Parameters’, and ‘Select links’.

The classes key is also a dictionary with all the user classes per transit class and their respective matrix totals.

Returns:

info (dict): Dictionary with summary information

log_specification()

prepare(nodes: List[int] | List[Tuple[int, int]] | None = None) → None

Prepare OD pairs for batch computation.

Arguments:

nodes (Union[list[int], list[tuple[int, int]]]): List of node IDs to operate on. If a 1D list is provided, OD pairs are taken to be all pair permutations of the list. If a list of pairs is provided OD pairs are taken as is. All node IDs must be present in the compressed graph. To make a node ID always appear in the compressed graph add it as a centroid. Duplicates will be dropped on execution. If None is provided, all OD pairs with non-zero flows will be used.

save_link_flows(table_name: str, project=None) → None

Saves the link link flows for all classes into the results database.

Arguments:

table_name (str): Name of the table being inserted to.

project (Project, Optional): Project we want to save the results to. Defaults to the active project

save_select_link_flows(table_name: str, project=None) → None

Saves the select link link flows for all classes into the results database. Additionally, it exports the OD matrices into OMX format.

Arguments:

table_name (str): Name of the table being inserted to and the name of the OpenMatrix file used for OD matrices.

project (Project, Optional): Project we want to save the results to. Defaults to the active project

set_choice_set_generation(algorithm: str, **kwargs) → None

Chooses the assignment algorithm and set parameters. Options for algorithm are, ‘bfsle’ for breadth first search with link removal, or ‘link-penalisation’/’link-penalization’.

BFSLE implementation based on “Route choice sets for very high-resolution data” by Nadine Rieser-Schüssler, Michael Balmer & Kay W. Axhausen (2013). DOI: 10.1080/18128602.2012.671383.

‘lp’ is also accepted as an alternative to ‘link-penalisation’

Setting the parameters for the route choice:

seed is a BFSLE specific parameters.

Setting max_depth or max_misses, while not required, is strongly recommended to prevent runaway algorithms.

max_misses is the maximum amount of duplicate routes found per OD pair. If it is exceeded then the route set if returned with fewer than max_routes. It has a default value of 100.

• When using BFSLE max_depth corresponds to the maximum height of the graph of graphs. It’s value is largely dependent on the size of the paths within the network. For very small networks a value of 10 is a recommended starting point. For large networks a good starting value is 5. Increase the value until the number of desired routes is being consistently returned. If it is exceeded then the route set if returned with fewer than max_routes.

• When using LP, max_depth corresponds to the maximum number of iterations performed. While not enforced, it should be higher than max_routes. It’s value is dependent on the magnitude of the cost field, specifically it’s related to the log base penalty of the ratio of costs between two alternative routes. If it is exceeded then the route set if returned with fewer than max_routes.

Additionally BFSLE has the option to incorporate link penalisation. Every link in all routes found at a depth are penalised with the penalty factor for the next depth. So at a depth of 0 no links are penalised nor removed. At depth 1, all links found at depth 0 are penalised, then the links marked for removal are removed. All links in the routes found at depth 1 are then penalised for the next depth. The penalisation compounds. Pass set penalty=1.0 to disable.

When performing an assignment, cutoff_prob can be provided to exclude routes from the path-sized logit model. The cutoff_prob is used to compute an inverse binary logit and obtain a max difference in utilities. If a paths total cost is greater than the minimum cost path in the route set plus the max difference, the route is excluded from the PSL calculations. The route is still returned, but with a probability of 0.0.

The cutoff_prob should be in the range \([0, 1]\). It is then rescaled internally to \([0.5, 1]\) as probabilities below 0.5 produce negative differences in utilities because the choice is between two routes only, one of which is the shortest path. A higher cutoff_prob includes less routes. A value of 1.0 will only include the minimum cost route. A value of 0.0 includes all routes.

Arguments:

algorithm (str): Algorithm to be used

kwargs (dict): Dictionary with all parameters for the algorithm

set_cores(cores: int) → None

Allows one to set the number of cores to be used

Inherited from AssignmentResultsBase

Arguments:

cores (int): Number of CPU cores to use

set_save_path_files(save_it: bool) → None

turn path saving on or off.

Arguments:

save_it (bool): Boolean to indicate whether paths should be saved

set_save_routes(where: str | None = None) → None

Set save path for route choice results. Provide None to disable.

Arguments:

save_it (bool): Boolean to indicate whether routes should be saved

set_select_links(links: Dict[Hashable, List[Tuple[int, int] | List[Tuple[int, int]]]], link_loading=True)

Set the selected links. Checks if the links and directions are valid. Supports OR and AND sets of links.

Dictionary values should be a list of either a single (link_id, direction) tuple or a list of (link_id, dirirection).

The elements of the first list represent the AND sets, together they are OR’ed. If any of these sets is satisfied the link are loaded as appropriate.

The AND sets are comprised of either a single (link_id, direction) tuple or a list of (link_id, direction). The single tuple represents an AND set with a single element.

All links and directions in an AND set must appear in any order within a route for it to be considered satisfied.

Supply links=None to disable select link analysis.

Arguments:

links (Union[None, Dict[Hashable, List[Union[Tuple[int, int], List[Tuple[int, int]]]]]]): Name of link set and link IDs and directions to be used in select link analysis.

link_loading (bool): Enable select link loading. If disabled only OD matrix results are available.

all_algorithms = ['bfsle', 'lp', 'link-penalisation', 'link-penalization']

default_parameters = {'bfsle': {'penalty': 1.0}, 'generic': {'beta': 1.0, 'cutoff_prob': 0.0, 'max_depth': 0, 'max_misses': 100, 'max_routes': 0, 'penalty': 1.01, 'seed': 0, 'store_results': True}, 'link-penalisation': {}}

demand_index_names = ['origin id', 'destination id']