aequilibrae.project.network

class aequilibrae.project.network.Link(dataset, project)

A Link object represents a single record in the links table

>>> project = create_example(project_path)

>>> all_links = project.network.links

# Let's get a mode to work with
>>> modes = project.network.modes
>>> car_mode = modes.get('c')

# We can just get one link in specific
>>> link1 = all_links.get(3)
>>> link2 = all_links.get(17)

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

# And edit each one like this
>>> link1.lanes_ab = 3
>>> link1.lanes_ba = 2

# we can drop a mode from the link
>>> link1.drop_mode(car_mode)  # or link1.drop_mode('c')

# we can add a mode to the link
>>> link2.add_mode(car_mode)  # or link2.add_mode('c')

# Or set all modes at once
>>> link2.set_modes('cbtw')

# We can just save the link
>>> link1.save()
>>> link2.save()

>>> project.close()

add_mode(mode: str | Mode)

Adds a new mode to this link

Raises a warning if mode is already allowed on the link, and fails if mode does not exist

Arguments:

mode_id (str or Mode): Mode_id of the mode or mode object to be added to the link

data_fields() → list

lists all data fields for the link, as available in the database

Returns:

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

delete()

Deletes link from database

drop_mode(mode: str | Mode)

Removes a mode from this link

Raises a warning if mode is already NOT allowed on the link, and fails if mode does not exist

Arguments:

mode_id (str or Mode): Mode_id of the mode or mode object to be removed from the link

save(conn=None)

Saves link to database

set_modes(modes: str)

Sets the modes acceptable for this link

Arguments:

modes (str): string with all mode_ids to be assigned to this link

class aequilibrae.project.network.LinkType(data_set: dict, project)

A link_type object represents a single record in the link_types table

delete()

save()

class aequilibrae.project.network.LinkTypes(net)

Access to the API resources to manipulate the link_types table in the network.

>>> project = create_example(project_path)

>>> link_types = project.network.link_types

# We can get a dictionary of link types in the model
>>> all_link_types = link_types.all_types()

# And do a bulk change and save it
>>> for link_type_id, link_type_obj in all_link_types.items():
...     link_type_obj.beta = 1

# We can save changes for all link types in one go
>>> link_types.save()

# or just get one link_type in specific
>>> default_link_type = link_types.get('y')

# or just get it by name
>>> default_link_type = link_types.get_by_name('default')

# We can change the description of the link types
>>> default_link_type.description = 'My own new description'

# Let's say we are using alpha to store lane capacity during the night as 90% of the standard
>>> default_link_type.alpha = 0.9 * default_link_type.lane_capacity

# To save this link types we can simply
>>> default_link_type.save()

# We can also create a completely new link_type and add to the model
>>> new_type = link_types.new('a')
>>> new_type.link_type = 'Arterial'  # Only ASCII letters and *_* allowed # other fields are not mandatory

# We then save it to the database
>>> new_type.save()

# we can even keep editing and save it directly once we have added it to the project
>>> new_type.lanes = 3
>>> new_type.lane_capacity = 1100
>>> new_type.save()

>>> project.close()

all_types() → dict

Returns a dictionary with all LinkType objects available in the model. link_type_id as key

delete(link_type_id: str) → None

Removes the link_type with link_type_id from the project

get(link_type_id: str) → LinkType

Get a link_type from the network by its link_type_id

get_by_name(link_type: str) → LinkType

Get a link_type from the network by its link_type (i.e. name)

new(link_type_id: str) → LinkType

save()

property fields: FieldEditor

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

class aequilibrae.project.network.Links(net)

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

>>> project = create_example(project_path)

>>> all_links = project.network.links

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

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

>>> project.close()

copy_link(link_id: int) → Link

Creates a copy of a link with a new id

It raises an error if link_id does not exist

Arguments:

link_id (int): Id of the link to copy

Returns:

link (Link): Link object for requested link_id

delete(link_id: int) → None

Removes the link with link_id from the project

Arguments:

link_id (int): Id of a link to delete

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(link_id: int) → Link

Get a link from the network by its link_id

It raises an error if link_id does not exist

Arguments:

link_id (int): Id of a link to retrieve

Returns:

link (Link): Link object for requested link_id

new() → Link

Creates a new link

Returns:

link (Link): A new link object populated only with link_id (not saved in the model yet)

refresh()

Refreshes all the links in memory

refresh_fields() → None

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

save()

property data: GeoDataFrame

Returns all links 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

sql = ''

Query sql for retrieving links

class aequilibrae.project.network.Mode(mode_id: str, project)

A mode object represents a single record in the modes table

save()

class aequilibrae.project.network.Modes(net)

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

>>> project = create_example(project_path)

>>> modes = project.network.modes

# We can get a dictionary of all modes in the model
>>> all_modes = modes.all_modes()

# And do a bulk change and save it
>>> for mode_id, mode_obj in all_modes.items():
...     mode_obj.beta = 1
...     mode_obj.save()

# or just get one mode in specific
>>> car_mode = modes.get('c')

# or just get this same mode by name
>>> car_mode = modes.get_by_name('car')

# We can change the description of the mode
>>> car_mode.description = 'personal autos only'

# Let's say we are using alpha to store the PCE for a future year with much smaller cars
>>> car_mode.alpha = 0.95

# To save this mode we can simply
>>> car_mode.save()

# We can also create a completely new mode and add to the model
>>> new_mode = modes.new('k')
>>> new_mode.mode_name = 'flying_car'  # Only ASCII letters and *_* allowed # other fields are not mandatory

# We then explicitly add it to the network
>>> modes.add(new_mode)

# we can even keep editing and save it directly once we have added it to the project
>>> new_mode.description = 'this is my new description'
>>> new_mode.save()

>>> project.close()

add(mode: Mode) → None

We add a mode to the project

all_modes() → dict

Returns a dictionary with all mode objects available in the model. mode_id as key

delete(mode_id: str) → None

Removes the mode with mode_id from the project

get(mode_id: str) → Mode

Get a mode from the network by its mode_id

get_by_name(mode: str) → Mode

Get a mode from the network by its mode_name

new(mode_id: str) → Mode

Returns a new mode with mode_id that can be added to the model later

property fields: FieldEditor

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

class aequilibrae.project.network.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

graphs: Dict[Graph]

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.network.Node(dataset, project)

A Node object represents a single record in the nodes table

>>> from shapely.geometry import Point

>>> project = create_example(project_path)

>>> all_nodes = project.network.nodes

# We can just get one link in specific
>>> node1 = all_nodes.get(7)

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

# It success if the node_id already does not exist
>>> node1.renumber(998877)

>>> node1.geometry = Point(1,2)

# We can just save the node
>>> node1.save()

>>> project.close()

connect_mode(mode_id: str, link_types='', connectors=1, conn: Connection | None = None, area: Polygon | None = 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 provided area.

The selection of the nodes that will be connected is done simply by computing running the KMeans2 clustering algorithm from SciPy and selecting the nodes closest to each cluster centroid.

When there are no node candidates inside the provided area, is it progressively expanded until at least one candidate is found.

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

area (Polygon, Optional): Area limiting the search for connectors

data_fields() → list

lists all data fields for the node, as available in the database

Returns:

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

renumber(new_id: int)

Renumbers the node in the network

Logs a warning if another node already exists with this node_id

Arguments:

new_id (int): New node_id

save()

Saves node to database

class aequilibrae.project.network.Nodes(net)

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

>>> project = create_example(project_path)

>>> all_nodes = project.network.nodes

# We can just get one link in specific
>>> node = all_nodes.get(21)

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

>>> project.close()

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(node_id: int) → Node

Get a node from the network by its node_id

It raises an error if node_id does not exist

Arguments:

node_id (int): ID of a node to retrieve

Returns:

node (Node): Node object for requested node_id

new_centroid(node_id: int) → Node

Creates a new centroid with a given ID

Arguments:

node_id (int): ID of the centroid to be created

refresh()

Refreshes all the nodes in memory

refresh_fields() → None

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

save()

property data: GeoDataFrame

Returns all nodes 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

property lonlat: DataFrame

Returns all nodes lon/lat coords as a Pandas DataFrame

Returns:

table (DataFrame): Pandas DataFrame with all the nodes, with geometry as lon/lat

sql = ''

Query sql for retrieving nodes

class aequilibrae.project.network.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.network.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

Modules

connector_creation
gmns_builder
gmns_exporter
haversine
link
link_type
link_types
links
mode
modes
network
node
nodes
osm
period
periods
safe_class