aequilibrae.project

class aequilibrae.project.About(project)

Provides an interface for querying and editing the about table of an AequilibraE project

>>> project = create_example(project_path)

# Adding a new field and saving it
>>> project.about.add_info_field('my_super_relevant_field')
>>> project.about.my_super_relevant_field = 'super relevant information'
>>> project.about.write_back()

# changing the value for an existing value/field
>>> project.about.scenario_name = 'Just a better scenario name'
>>> project.about.write_back()

>>> project.close()

add_info_field(info_field: str) → None

Adds new information field to the model

Arguments:

info_field (str): Name of the desired information field to be added. Has to be a valid Python VARIABLE name (i.e. letter as first character, no spaces and no special characters)

>>> project = create_example(project_path)

>>> project.about.add_info_field('a_cool_field')
>>> project.about.a_cool_field = 'super relevant information'
>>> project.about.write_back()

>>> project.close()

create()

Creates the ‘about’ table for project files that did not previously contain it

list_fields() → list

Returns a list of all characteristics the about table holds

write_back()

Saves the information parameters back to the project database

>>> project = create_example(project_path)

>>> project.about.description = 'This is the example project. Do not use for forecast'
>>> project.about.write_back()

>>> project.close()

class aequilibrae.project.FieldEditor(project, table_name: str)

Allows user to edit the project data tables

The field editor is used for two different purposes:

• Managing data tables (adding and removing fields)

• Editing the tables’ metadata (description of each field)

This is a general class used to manage all project’s data tables accessible to the user and but it should be accessed directly from within the module corresponding to the data table one wants to edit. Example:

>>> project = create_example(project_path)

# To edit the fields of the link_types table
>>> lt_fields = project.network.link_types.fields

# To edit the fields of the modes table
>>> m_fields = project.network.modes.fields

>>> project.close()

Field descriptions are kept in the table attributes_documentation

add(field_name: str, description: str, data_type='NUMERIC') → None

Adds new field to the data table

Arguments:

field_name (str): Field to be added to the table. Must be a valid SQLite field name

description (str): Description of the field to be inserted in the metadata

data_type (str, Optional): Valid SQLite Data type. Default: “NUMERIC”

all_fields() → List[str]

Returns the list of fields available in the database

remove(field_name: str) → None

save() → None

Saves any field descriptions which my have been changed to the database and update layer statistics.

This is required for new fields to appear in applications like QGIS.

class aequilibrae.project.Log(project_base_path: Path)

API entry point to the log file contents

>>> project = Project()
>>> project.new(project_path)

>>> log = project.log()

# We get all entries for the log file
>>> entries = log.contents()

# Or clear everything (NO UN-DOs)
>>> log.clear()

>>> project.close()

clear()

Clears the log file. Use it wisely

contents() → list

Returns contents of log file

Returns:

log_contents (list): List with all entries in the log file

class aequilibrae.project.Matrices(project)

Gateway into the matrices available/recorded in the model

check_exists(name: str) → bool

Checks whether a matrix with a given name exists

Returns:

exists (bool): Does the matrix exist?

clear_database() → None

Removes records from the matrices database that do not exist in disk

delete_record(matrix_name: str) → None

Deletes a Matrix Record from the model and attempts to remove from disk

get_matrix(matrix_name: str) → AequilibraeMatrix

Returns an AequilibraE matrix available in the project

Raises an error if matrix does not exist

Arguments:

matrix_name (str): Name of the matrix to be loaded

Returns:

matrix (AequilibraeMatrix): Matrix object

get_record(matrix_name: str) → MatrixRecord

Returns a model Matrix Record for manipulation in memory

list() → DataFrame

List of all matrices available

Returns:

df (pd.DataFrame): Pandas DataFrame listing all matrices available in the model

new_record(name: str, file_name: str, matrix=None) → MatrixRecord

Creates a new record for a matrix in disk, but does not save it

If the matrix file is not already on disk, it will fail

Arguments:

name (str): Name of the matrix

file_name (str): Name of the file on disk

Returns:

matrix_record (MatrixRecord): A matrix record that can be manipulated in memory before saving

reload()

Discards all memory matrices in memory and loads recreate them

update_database() → None

Adds records to the matrices database for matrix files found on disk

class aequilibrae.project.Network(project)

Network class. Member of an AequilibraE Project

build_graphs(fields: list = None, modes: list = None, limit_to_area: Polygon = None) → None

Builds graphs for all modes currently available in the model

When called, it overwrites all graphs previously created and stored in the networks’ dictionary of graphs

Arguments:

fields (list, Optional): When working with very large graphs with large number of fields in the database, it may be useful to specify which fields to use

modes (list, Optional): When working with very large graphs with large number of fields in the database, it may be useful to generate only those we need

limit_to_area (Polygon, Optional): When working with a very large model area, you may want to filter your database to a small area for your computation, which you can do by providing a polygon. The search is limited to a spatial index search, so it is very fast but NOT PRECISE.

To use the ‘fields’ parameter, a minimalistic option is the following

>>> project = create_example(project_path)

>>> fields = ['distance']
>>> project.network.build_graphs(fields, modes = ['c', 'w'])

>>> project.close()

convex_hull() → Polygon

Queries the model for the convex hull of the entire network

Returns:

model coverage (Polygon): Shapely (Multi)polygon of the model network.

count_centroids() → int

Returns the number of centroids in the model

Returns:

int: Number of centroids

count_links() → int

Returns the number of links in the model

Returns:

int: Number of links

count_nodes() → int

Returns the number of nodes in the model

Returns:

int: Number of nodes

create_from_gmns(link_file_path: str, node_file_path: str, use_group_path: str = None, geometry_path: str = None, srid: int = 4326) → None

Creates AequilibraE model from links and nodes in GMNS format.

Arguments:

link_file_path (str): Path to a links csv file in GMNS format

node_file_path (str): Path to a nodes csv file in GMNS format

use_group_path (str, Optional): Path to a csv table containing groupings of uses. This helps AequilibraE know when a GMNS use is actually a group of other GMNS uses

geometry_path (str, Optional): Path to a csv file containing geometry information for a line object, if not specified in the link table

srid (int, Optional): Spatial Reference ID in which the GMNS geometries were created

create_from_osm(model_area: Polygon | None = None, place_name: str | None = None, modes=('car', 'transit', 'bicycle', 'walk'), clean=True) → None

Downloads the network from OpenStreetMap (OSM)

Arguments:

area (Polygon, Optional): Polygon for which the network will be downloaded. If not provided, a place name would be required

place_name (str, Optional): If not downloading with East-West-North-South boundingbox, this is required

modes (tuple, Optional): List of all modes to be downloaded. Defaults to the modes in the parameter file

clean (bool, Optional): Keeps only the links that intersects the model area polygon. Defaults to True. Does not apply to networks downloaded with a place name

>>> project = Project()
>>> project.new(project_path)

# Now we can import the network for any place we want
>>> project.network.create_from_osm(place_name="my_beautiful_hometown")

>>> project.close()

export_to_gmns(path: str)

Exports AequilibraE network to csv files in GMNS format.

Arguments:

path (str): Output folder path.

extent()

Queries the extent of the network included in the model

Returns:

model extent (Polygon): Shapely polygon with the bounding box of the model network.

list_modes()

Returns a list of all the modes in this model

Returns:

list: List of all modes

set_time_field(time_field: str) → None

Set the time field for all graphs built in the model

Arguments:

time_field (str): Network field with travel time information

skimmable_fields()

Returns a list of all fields that can be skimmed

Returns:

list: List of all fields that can be skimmed

link_types: LinkTypes = None

protected_fields = ['ogc_fid', 'geometry']

req_link_flds = ['link_id', 'a_node', 'b_node', 'direction', 'distance', 'modes', 'link_type']

req_node_flds = ['node_id', 'is_centroid']

signal = <aequilibrae.utils.python_signal.PythonSignal object>

class aequilibrae.project.NetworkSimplifier(project=None)

collapse_links_into_nodes(links: List[int])

Collapses links into nodes, adjusting the network in the neighborhood.

Arguments:

links (List[int]): List containing link IDs to be collapsed.

rebuild_network()

Rebuilds the network elements that would have to be rebuilt after massive network simplification

simplify(graph: Graph, max_speed_ratio: float = 1.1)

Simplifies the network by merging links that are shorter than a given threshold

Arguments:

graph (Graph): AequilibraE graph

max_speed_ratio (float, Optional): Maximum ratio between the fastest and slowest speed for a link to be considered for simplification.

signal = <aequilibrae.utils.python_signal.PythonSignal object>

class aequilibrae.project.Period(dataset, project)

A Period object represents a single record in the periods table

>>> project = create_example(project_path, "coquimbo")

>>> all_periods = project.network.periods

# We can just get one link in specific
>>> period1 = all_periods.get(1)

# We can find out which fields exist for the period
>>> which_fields_do_we_have = period1.data_fields()

>>> project.close()

data_fields() → list

Lists all data fields for the period, as available in the database

Returns:

data fields (list): list of all fields available for editing

renumber(new_id: int)

Renumbers the period in the network

Logs a warning if another period already exists with this period_id

Arguments:

new_id (int): New period_id

save()

Saves period to database

class aequilibrae.project.Periods(net)

Access to the API resources to manipulate the periods table in the network

>>> project = create_example(project_path, "coquimbo")

>>> all_periods = project.network.periods

# We can just get one link in specific
>>> period = all_periods.get(1)

# We can save changes for all periods we have edited so far
>>> all_periods.save()

>>> project.close()

extent()

Queries the extent of the layer included in the model

Returns:

model extent (Polygon): Shapely polygon with the bounding box of the layer.

get(period_id: int) → Period

Get a period from the network by its period_id

It raises an error if period_id does not exist

Arguments:

period_id (int): Id of a period to retrieve

Returns:

period (Period): Period object for requested period_id

new_period(period_id: int, start: int, end: int, description: str = None) → Period

Creates a new period with a given ID

Arguments:

period_id (int): Id of the centroid to be created

start (int): Start time of the period to be created

end (int): End time of the period to be created

description (str): Optional human readable description of the time period e.g. ‘1pm - 5pm’

refresh()

Refreshes all the periods in memory

refresh_fields() → None

After adding a field one needs to refresh all the fields recognized by the software

save()

property data: DataFrame

Returns all periods data as a Pandas DataFrame

Returns:

table (DataFrame): Pandas DataFrame with all the periods

property default_period: Period

property fields: FieldEditor

Returns a FieldEditor class instance to edit the zones table fields and their metadata

sql = ''

Query sql for retrieving periods

class aequilibrae.project.Project

AequilibraE project class

Create Project

>>> new_project = Project()
>>> new_project.new(project_path)

# Safely closes the project
>>> new_project.close()

Open Project

>>> existing_project = Project()
>>> existing_project.open(project_path)

>>> existing_project.close()

classmethod from_path(project_folder)

activate()

check_file_indices() → None

Makes results_database.sqlite and the matrices folder compatible with project database

clone_scenario(scenario_name: str, description: str = '')

Clones the active scenario.

Arguments:

scenario_name (str): scenario name

description (str): useful scenario description

close() → None

Safely closes the project

create_empty_scenario(scenario_name: str, description: str = '')

Creates an empty scenario, without any links, nodes, and zones.

Arguments:

scenario_name (str): scenario name

description (str): useful scenario description

deactivate()

list_scenarios()

Lists the existing scenarios.

Returns:

scenarios (pd.DataFrame): Pandas DataFrame with existing scenarios

log() → Log

Returns a log object

allows the user to read the log or clear it

new(project_path: str) → None

Creates a new project

Arguments:

project_path (str): Full path to the project data folder. If folder exists, it will fail

open(project_path: str) → None

Loads project from disk

Arguments:

project_path (str): Full path to the project data folder. If the project inside does not exist, it will fail.

upgrade(ignore_project: bool = False, ignore_transit: bool = False, ignore_results: bool = False)

Find and apply all applicable migrations.

All database upgrades are applied within a single transaction.

Optionally ignore specific databases. This is useful when a database is known to be incompatible with some migrations but you’d still like to upgrade the others. Take care when ignoring a database. For a particular version of aequilibrae, it is assumed that all migrations have been applied successfully or the project was created with the latest schema, skipping/ignoring migrations will likely lead to issues/broken assumptions.

If skipping a specific migration is required, use the aequilibrae.project.tools.MigrationManager object directly. Consult it’s documentation page for details. Take care when skipping migrations.

Arguments:

ignore_project (bool, optional): Ignore the project database. No direct migrations will be

applied. Defaults to False.

ignore_transit (bool, optional): Ignore the transit database. No direct migrations will be

applied. Defaults to False.

ignore_results (bool, optional): Ignore the results database. No direct migrations will be

applied. Defaults to False.

use_scenario(scenario_name: str)

Switch the active scenario.

Arguments:

scenario_name (str): name of the scenario to be activated

property about: About

property db_connection

property db_connection_spatial

property logger: Logger

property matrices: Matrices

property network: Network

property parameters: dict

property path_to_file

property project_base_path

property project_parameters: Parameters

property results: Results

property results_connection

property run

Load and return the AequilibraE run module with the default arguments from parameters.yml partially applied.

Refer to run/__init__.py file within the project folder for documentation.

property transit: Transit

property transit_connection

property zoning

class aequilibrae.project.Scenario(name: str, base_path: Path, path_to_file: Path)

Represents a modelling scenario within an AequilibraE project.

Each scenario operates independently with its own database and file structure while sharing the overall project configuration.

Scenarios are typically managed through the Project class rather than instantiated directly by users.

The root scenario is special-cased and represents the original project configuration. All other scenarios are stored in subdirectories and reference their own database files.

about: About

base_path: Path

logger: Logger

matrices: Matrices

name: str

network: Network

path_to_file: Path

results: Results

transit: Transit

zoning: Zoning

class aequilibrae.project.Zone(dataset: dict, zoning)

Single zone object that can be queried and manipulated in memory

add_centroid(point: Point, robust=True) → None

Adds a centroid to the network file

Arguments:

point (Point): Shapely Point corresponding to the desired centroid position. If None, uses the geometric center of the zone

robust (Bool, Optional): Moves the centroid location around to avoid node conflict. Defaults to True.

connect_mode(mode_id: str, link_types='', connectors=1, conn: Connection | None = None, limit_to_zone=True) → None

Adds centroid connectors for the desired mode to the network file

Centroid connectors are created by connecting the zone centroid to one or more nodes selected from all those that satisfy the mode and link_types criteria and are inside the zone.

The selection of the nodes that will be connected is done simply by searching for the node closest to the zone centroid, or the N closest nodes to the centroid.

If fewer candidates than required connectors are found, all candidates are connected.

Arguments:

mode_id (str): Mode ID we are trying to connect

link_types (str, Optional): String with all the link type IDs that can be considered. eg: yCdR. Defaults to ALL link types

connectors (int, Optional): Number of connectors to add. Defaults to 1

conn (sqlite3.Connection, Optional): Connection to the database.

limit_to_zone (bool): Limits the search for nodes inside the zone. Defaults to True.

delete()

Removes the zone from the database

disconnect_mode(mode_id: str) → None

Removes centroid connectors for the desired mode from the network file

Arguments:

mode_id (str): Mode ID we are trying to disconnect from this zone

save()

Saves/Updates the zone data to the database

class aequilibrae.project.Zoning(network)

Access to the API resources to manipulate the ‘zones’ table in the project

>>> project = create_example(project_path)

>>> zoning = project.zoning

>>> zone_downtown = zoning.get(1)
>>> zone_downtown.population = 637
>>> zone_downtown.employment = 10039
>>> zone_downtown.save()

# We can also add one more field to the table
>>> fields = zoning.fields
>>> fields.add('parking_spots', 'Total licensed parking spots', 'INTEGER')

>>> project.close()

add_centroids(robust=True)

Adds automatic centroids to the network file. It adds centroids to all zones that do not have one Centroid is added to the geographic centroid of the zone.

Arguments:

robust (bool, Optional): Moves the centroid location around to avoid node conflict. Defaults to True.

all_zones() → dict

Returns a dictionary with all Zone objects available in the model, using zone_id as key

connect_mode(mode_id: str, link_types='', connectors=1, limit_to_zone=True, bulk: bool = False)

Adds centroid connectors for the desired mode to the network file

Centroid connectors are created by connecting each zone centroid to one or more nodes selected from all those that satisfy the mode and link_types criteria and are inside the zone.

The selection of the nodes that will be connected is done simply by searching for the node closest to each zone centroid, or the N closest nodes to the centroid.

If fewer candidates than required connectors are found, all candidates are connected.

CENTROIDS THAT ARE CURRENTLY CONNECTED ARE SKIPPED ALTOGETHER

Arguments:

mode_id (str): Mode ID we are trying to connect

link_types (str, Optional): String with all the link type IDs that can be considered.

eg: yCdR. Defaults to ALL link types

connectors (int, Optional): Number of connectors to add. Defaults to 1

limit_to_zone (bool): Limits the search for nodes inside the zone. Defaults to True.

bulk (bool, Optional): Whether to use the bulk connector method or not. This is method is

considerably faster for connecting a large amount of centroids but has a high runtime overhead.

coverage() → Polygon

Returns a single polygon for the entire zoning coverage

Returns:

model coverage (Polygon): Shapely (Multi)polygon of the zoning system.

create_zoning_layer()

Creates the ‘zones’ table for project files that did not previously contain it

extent() → Polygon

Queries the extent of the layer included in the model

Returns:

model extent (Polygon): Shapely polygon with the bounding box of the layer.

get(zone_id: str) → Zone

Get a zone from the model by its zone_id

get_closest_zone(geometry: Point | LineString | MultiLineString) → int

Returns the zone in which the given geometry is located.

If the geometry is not fully enclosed by any zone, the zone closest to the geometry is returned

Arguments:

geometry (Point or LineString): A Shapely geometry object

Returns:

zone_id (int): ID of the zone applicable to the point provided

new(zone_id: int) → Zone

Creates a new zone

Returns:

zone (Zone): A new zone object populated only with zone_id (but not saved in the model yet)

refresh_geo_index()

save()

property data: GeoDataFrame

Returns all zones data as a Pandas DataFrame

Returns:

table (GeoDataFrame): GeoPandas GeoDataFrame with all the nodes

property fields: FieldEditor

Returns a FieldEditor class instance to edit the zones table fields and their metadata

Modules

about
basic_table
data
data_loader
database_connection
field_editor
network
project
project_cleaning
project_creation
scenario
table_loader
tools
zone
zoning