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