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_from_pandas(df[, recompute_psl])	Perform an assignment using route sets from a Pandas DataFrame.
execute_from_path_files(path_files[, ...])	Perform an assignment from an existing set of path-files.
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_path_files([where])	Save path-files to the directory specific.
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])	Chooses the assignment algorithm and set its parameters.
set_cores(cores)	Allows one to set the number of cores to be used
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_from_pandas(df: DataFrame, recompute_psl: bool = False) → None

Perform an assignment using route sets from a Pandas DataFrame.

Requires the DataFrame contains the origin id, destination id and route set columns. The route sets must be a list of links IDs stored as integers with the direction encoded as the sign. Additionally, when recompute_psl is False, the probability column must also be present.

When recompute_psl is True, the path-sized logit is recomputed for each route with respect to the graphs current cost field and the beta and cutoff_prob parameters.

All origin and destination IDs within the DataFrame must exist within the demand matrix.

All link IDs and directions must exist within the graph. Links must also be present within the compressed graph.

If recompute_psl is False the table returned from self.get_results() will have all zeros for the cost and path overlap fields, and all True for the mask field. If recompute_psl is True these fields will be recalculated as required.

execute_from_path_files(path_files: Path | str, recompute_psl: bool = False) → None

Perform an assignment from an existing set of path-files.

This method expects the path-files to be written by the self.save_path_files() method, however any parquet hive dataset with the correct structure is accepted. This allows the use of AequilibraE’s path-sized logit, link loading, select link analysis, and assignment while using externally generated routes.

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() → DataFrame

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. When the link id in the route set is positive it represents the ab direction, while negative represents the ba direction.

Returns:

results (pd.DataFrame): 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

• 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_path_files(where: Path | None = None)

Save path-files to the directory specific.

Files will be saved as a parquet hive dataset partitioned by the origin ID. Existing path-files will not be removed to allow incremental route choice set generation.

Arguments:

where (Optional[pathlib.Path]): Directory to save the dataset to.

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 | None = None, **kwargs) → None

Chooses the assignment algorithm and set its parameters.

Options for algorithm are ‘bfsle’ for breadth first search with link removal, or ‘link-penalisation’/’link-penalization’. ‘lp’ is also accepted as an alternative to ‘link-penalisation’. If algorithm is None, none will be set, but the parameters will be updated. This is useful when assigning from path-files.

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.

Setting the parameters for the route choice:

• seed is a BFSLE specific parameters.

• Although not required, setting max_depth or max_misses, is strongly recommended to prevent runaway algorithms.

• max_misses is the maximum amount of duplicate routes found per OD pair. If a set of routes is returned in a case where max_misses is exceeded, the number of routes may be fewer than max_routes. Assumes a default value of 100.

• When using BFSLE max_depth corresponds to the maximum height of the graph. 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 a set of routes is returned in a case where max_depth is exceeded, the number of routes may be 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 if it’s related to the log base penalty of the ratio of costs between two alternative routes. If a set of routes is returned in a case where max_depth is exceeded, the number of routes may be 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. 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_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']