Skip to main content
`Ctrl`+`K`

# aequilibrae.paths.TrafficAssignment

class aequilibrae.paths.TrafficAssignment(project=None)

  Traffic assignment class.

  For a comprehensive example on use, see the Use examples page.

      >>> from aequilibrae.paths import TrafficAssignment, TrafficClass

      >>> project = create_example(project_path)
      >>> project.network.build_graphs()

      >>> graph = project.network.graphs['c'] # we grab the graph for cars
      >>> graph.set_graph('free_flow_time') # let's say we want to minimize time
      >>> graph.set_skimming(['free_flow_time', 'distance']) # And will skim time and distance
      >>> graph.set_blocked_centroid_flows(True)

      >>> proj_matrices = project.matrices

      >>> demand = proj_matrices.get_matrix("demand_omx")

      # We will only assign one user class stored as 'matrix' inside the OMX file
      >>> demand.computational_view(['matrix'])

      # Creates the assignment class
      >>> assigclass = TrafficClass("car", graph, demand)

      >>> assig = TrafficAssignment()

      # The first thing to do is to add at list of traffic classes to be assigned
      >>> assig.set_classes([assigclass])

      # Then we set the volume delay function
      >>> assig.set_vdf("BPR")  # This is not case-sensitive

      # And its parameters
      >>> assig.set_vdf_parameters({"alpha": "b", "beta": "power"})

      # The capacity and free flow travel times as they exist in the graph
      >>> assig.set_capacity_field("capacity")
      >>> assig.set_time_field("free_flow_time")

      # And the algorithm we want to use to assign
      >>> assig.set_algorithm('bfw')

      >>> assig.max_iter = 10
      >>> assig.rgap_target = 0.00001

      >>> assig.execute() # we then execute the assignment

      # If you want, it is possible to access the convergence report
      >>> convergence_report = pd.DataFrame(assig.assignment.convergence_report)

      # Assignment results can be viewed as a Pandas DataFrame
      >>> results_df = assig.results()

      # Information on the assignment setup can be recovered with
      >>> info = assig.info()

      # Or save it directly to the results database
      >>> results = assig.save_results(table_name='base_year_assignment')

      # skims are here
      >>> avg_skims = assigclass.results.skims # blended ones
      >>> last_skims = assigclass._aon_results.skims # those for the last iteration

  __init__(project=None) → None

  Methods

  `__init__`([project]) |
  `add_class`(traffic_class) | Adds a traffic class to the assignment
  `add_preload`(preload[, name]) | Given a dataframe of 'link_id', 'direction' and 'preload', merge into current preloads dataframe.
  `algorithms_available`() | Returns all algorithms available for use
  `execute`([log_specification]) | Processes assignment
  `info`() | Returns information for the traffic assignment procedure
  `log_specification`() |
  `report`() | Returns the assignment convergence report
  `results`() | Prepares the assignment results as a Pandas DataFrame
  `save_results`(table_name[, keep_zero_flows, ...]) | Saves the assignment results to results_database.sqlite
  `save_select_link_flows`(table_name[, project]) | Saves the select link link flows for all classes into the results database.
  `save_select_link_matrices`(file_name) | Saves the Select Link matrices for each TrafficClass in the current TrafficAssignment class
  `save_select_link_results`(name) | Saves both the Select Link matrices and flow results at the same time, using the same name.
  `save_skims`(matrix_name[, which_ones, ...]) | Saves the skims (if any) to the skim folder and registers in the matrix list
  `select_link_flows`() | Returns a dataframe of the select link flows for each class
  `set_algorithm`(algorithm) | Chooses the assignment algorithm.
  `set_capacity_field`(capacity_field) | Sets the graph field that contains link capacity for the assignment period -> e.g. 'capacity1h'.
  `set_classes`(classes) | Sets Traffic classes to be assigned
  `set_cores`(cores) | Allows one to set the number of cores to be used AFTER traffic classes have been added
  `set_path_file_format`(file_format) | Specify path saving format.
  `set_save_path_files`(save_it) | Turn path saving on or off.
  `set_time_field`(time_field) | Sets the graph field that contains free flow travel time -> e.g. 'fftime'.
  `set_vdf`(vdf_function) | Sets the Volume-delay function to be used
  `set_vdf_parameters`(par) | Sets the parameters for the Volume-delay function.

  Attributes

  `all_algorithms` |
  `bpr_parameters` |

  add_class(traffic_class: TrafficClass) → None

    Adds a traffic class to the assignment

    Arguments:

      traffic_class (`TrafficClass`): Traffic class

  add_preload(preload: DataFrame, name: str | None = None) → None

    Given a dataframe of ‘link_id’, ‘direction’ and ‘preload’, merge into current preloads dataframe.

    Arguments:

      preload (`pd.DataFrame`): dataframe mapping ‘link_id’ & ‘direction’ to ‘preload’ name (`str`): Name for particular preload (optional - default name will be chosen if not specified)

  algorithms_available() → list

    Returns all algorithms available for use

    Returns:

      `list`: List of string values to be used with set_algorithm

  execute(log_specification=True) → None

    Processes assignment

  info() → dict

    Returns information for the traffic assignment procedure

    Dictionary contains keys ‘Algorithm’, ‘Classes’, ‘Computer name’, ‘Procedure ID’, ‘Maximum iterations’ and ‘Target RGap’.

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

    Returns:

      info (`dict`): Dictionary with summary information

  log_specification()
  report() → DataFrame

    Returns the assignment convergence report

    Returns:

      DataFrame (`pd.DataFrame`): Convergence report

  results() → DataFrame

    Prepares the assignment results as a Pandas DataFrame

    Returns:

      DataFrame (`pd.DataFrame`): Pandas DataFrame with all the assignment results indexed on link_id

  save_results(table_name: str, keep_zero_flows=True, project=None) → None

    Saves the assignment results to results_database.sqlite

    Method fails if table exists

    Arguments:

      table_name (`str`): Name of the table to hold this assignment result

      keep_zero_flows (`bool`): Whether we should keep records for zero flows. Defaults to `True`

      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. Note the traffic class

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

  save_select_link_matrices(file_name: str) → None

    Saves the Select Link matrices for each TrafficClass in the current TrafficAssignment class

  save_select_link_results(name: str) → None

    Saves both the Select Link matrices and flow results at the same time, using the same name.

    Note

    Note the Select Link matrices will have _SL_matrices.omx appended to the end for ease of identification. e.g. save_select_link_results(“Car”) will result in the following names for the flows and matrices: Select Link Flows: inserts the select link flows for each class into the database with the table name: Car Select Link Matrices (only exports to OMX format): Car.omx

    Arguments:

      name (`str`): name of the matrices

  save_skims(matrix_name: str, which_ones='final', format='omx', project=None) → None

    Saves the skims (if any) to the skim folder and registers in the matrix list

    Arguments:

      name (`str`): Name of the matrix record to hold this matrix (same name used for file name)

      which_ones (`str`, Optional): {‘final’: Results of the final iteration, ‘blended’: Averaged results for all iterations, ‘all’: Saves skims for both the final iteration and the blended ones}. Default is ‘final’

      format (`str`, Optional): File format (‘aem’ or ‘omx’). Default is ‘omx’

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

  select_link_flows() → Dict[str, DataFrame]

    Returns a dataframe of the select link flows for each class

  set_algorithm(algorithm: str)

    Chooses the assignment algorithm. e.g. ‘frank-wolfe’, ‘bfw’, ‘msa’

    ‘fw’ is also accepted as an alternative to ‘frank-wolfe’

    Arguments:

      algorithm (`str`): Algorithm to be used

  set_capacity_field(capacity_field: str) → None

    Sets the graph field that contains link capacity for the assignment period -> e.g. ‘capacity1h’

    Arguments:

      capacity_field (`str`): Field name

  set_classes(classes: List[TrafficClass]) → None

    Sets Traffic classes to be assigned

    Arguments:

      classes (`List[TrafficClass]`): List of Traffic classes for assignment

  set_cores(cores: int) → None

    Allows one to set the number of cores to be used AFTER traffic classes have been added

    Inherited from `AssignmentResultsBase`

    Arguments:

      cores (`int`): Number of CPU cores to use

  set_path_file_format(file_format: str) → None

    Specify path saving format. Either parquet or feather.

    Arguments:

      file_format (`str`): Name of file format to use for path files

  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_time_field(time_field: str) → None

    Sets the graph field that contains free flow travel time -> e.g. ‘fftime’

    Arguments:

      time_field (`str`): Field name

  set_vdf(vdf_function: str) → None

    Sets the Volume-delay function to be used

    Arguments:

      vdf_function (`str`): Name of the VDF to be used

  set_vdf_parameters(par: dict) → None

    Sets the parameters for the Volume-delay function.

    Parameter values can be scalars (same values for the entire network) or network field names (link-specific values) - Examples: {‘alpha’: 0.15, ‘beta’: 4.0} or {‘alpha’: ‘alpha’, ‘beta’: ‘beta’}

    Arguments:

      par (`dict`): Dictionary with all parameters for the chosen VDF

  all_algorithms = ['all-or-nothing', 'msa', 'frank-wolfe', 'fw', 'cfw', 'bfw']
  bpr_parameters = ['alpha', 'beta']