Skip to main content
`Ctrl`+`K`

# 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']