aequilibrae.distribution package

Submodules

aequilibrae.distribution.gravity_application module

class aequilibrae.distribution.gravity_application.GravityApplication(project=None, **kwargs)

Bases: object

Applies a synthetic gravity model.

Model is an instance of SyntheticGravityModel class. Impedance is an instance of AequilibraEMatrix. Row and Column vectors are instances of AequilibraeData.

>>> import pandas as pd
>>> from aequilibrae import Project
>>> from aequilibrae.matrix import AequilibraeMatrix, AequilibraeData
>>> from aequilibrae.distribution import SyntheticGravityModel, GravityApplication

>>> project = Project.from_path("/tmp/test_project_ga")

# We define the model we will use
>>> model = SyntheticGravityModel()

# Before adding a parameter to the model, you need to define the model functional form
>>> model.function = "GAMMA" # "EXPO" or "POWER"

# Only the parameter(s) applicable to the chosen functional form will have any effect
>>> model.alpha = 0.1
>>> model.beta = 0.0001

# Or you can load the model from a file
# model.load('path/to/model/file')

# We load the impedance matrix
>>> matrix = AequilibraeMatrix()
>>> matrix.load('/tmp/test_project_ga/matrices/skims.omx')
>>> matrix.computational_view(['distance_blended'])

# We create the vectors we will use
>>> query = "SELECT zone_id, population, employment FROM zones;"
>>> df = pd.read_sql(query, project.conn)
>>> df.sort_values(by="zone_id", inplace=True)

# You create the vectors you would have
>>> df = df.assign(production=df.population * 3.0)
>>> df = df.assign(attraction=df.employment * 4.0)

>>> zones = df.index.shape[0]

# We create the vector database
>>> args = {"entries": zones, "field_names": ["productions", "attractions"],
...     "data_types": [np.float64, np.float64], "memory_mode": True}
>>> vectors = AequilibraeData()
>>> vectors.create_empty(**args)

# Assign the data to the vector object
>>> vectors.productions[:] = df.production.values[:]
>>> vectors.attractions[:] = df.attraction.values[:]
>>> vectors.index[:] = df.zone_id.values[:]

# Balance the vectors
>>> vectors.attractions[:] *= vectors.productions.sum() / vectors.attractions.sum()

# Create the problem object
>>> args = {"impedance": matrix,
...         "rows": vectors,
...         "row_field": "productions",
...         "model": model,
...         "columns": vectors,
...         "column_field": "attractions",
...         "output": '/tmp/test_project_ga/matrices/matrix.aem',
...         "nan_as_zero":True
...         }
>>> gravity = GravityApplication(**args)

# Solve and save the outputs
>>> gravity.apply()
>>> gravity.output.export('/tmp/test_project_ga/matrices/omx_file.omx')

# To save your report into a file, you can do the following:
# with open('/tmp/test_project_ga/report.txt', 'w') as file:
#     for line in gravity.report:
#         file.write(f"{line}\n")

apply()

Runs the Gravity Application instance as instantiated

Resulting matrix is the output class member

save_to_project(name: str, file_name: str, project=None) → None

Saves the matrix output to the project file

Arguments:

name (str): Name of the desired matrix record file_name (str): Name for the matrix file name. AEM and OMX supported project (Project, Optional): Project we want to save the results to. Defaults to the active project

aequilibrae.distribution.gravity_calibration module

Algorithms to calibrate synthetic gravity models with power and exponential functions

The procedures implemented in this code are some of those suggested in Modelling Transport, 4th Edition, Ortuzar and Willumsen, Wiley 2011

class aequilibrae.distribution.gravity_calibration.GravityCalibration(project=None, **kwargs)

Bases: object

Calibrate a traditional gravity model

Available deterrence function forms are: ‘EXPO’ or ‘POWER’. ‘GAMMA’

>>> from aequilibrae import Project
>>> from aequilibrae.matrix import AequilibraeMatrix
>>> from aequilibrae.distribution import GravityCalibration

>>> project = Project.from_path("/tmp/test_project_gc")

# We load the impedance matrix
>>> matrix = AequilibraeMatrix()
>>> matrix.load('/tmp/test_project_gc/matrices/demand.omx')
>>> matrix.computational_view(['matrix'])

# We load the impedance matrix
>>> impedmatrix = AequilibraeMatrix()
>>> impedmatrix.load('/tmp/test_project_gc/matrices/skims.omx')
>>> impedmatrix.computational_view(['time_final'])

# Creates the problem
>>> args = {"matrix": matrix,
...         "impedance": impedmatrix,
...         "row_field": "productions",
...         "function": 'expo',
...         "nan_as_zero": True}
>>> gravity = GravityCalibration(**args)

# Solve and save outputs
>>> gravity.calibrate()
>>> gravity.model.save('/tmp/test_project_gc/dist_expo_model.mod')

# To save the model report in a file
# with open('/tmp/test_project_gc/report.txt', 'w') as f:
#     for line in gravity.report:
#         f.write(f'{line}\n')

calibrate()

Calibrate the model

Resulting model is in output class member

aequilibrae.distribution.ipf module

class aequilibrae.distribution.ipf.Ipf(project=None, **kwargs)

Bases: object

Iterative proportional fitting procedure

>>> from aequilibrae import Project
>>> from aequilibrae.distribution import Ipf
>>> from aequilibrae.matrix import AequilibraeMatrix, AequilibraeData

>>> project = Project.from_path("/tmp/test_project_ipf")

>>> matrix = AequilibraeMatrix()

# Here we can create from OMX or load from an AequilibraE matrix.
>>> matrix.load('/tmp/test_project/matrices/demand.omx')
>>> matrix.computational_view()

>>> args = {"entries": matrix.zones, "field_names": ["productions", "attractions"],
...         "data_types": [np.float64, np.float64], "memory_mode": True}

>>> vectors = AequilibraeData()
>>> vectors.create_empty(**args)

>>> vectors.productions[:] = matrix.rows()[:]
>>> vectors.attractions[:] = matrix.columns()[:]

# We assume that the indices would be sorted and that they would match the matrix indices
>>> vectors.index[:] = matrix.index[:]

>>> args = {
...         "matrix": matrix, "rows": vectors, "row_field": "productions", "columns": vectors,
...         "column_field": "attractions", "nan_as_zero": False}

>>> fratar = Ipf(**args)

>>> fratar.fit()

# We can get back to our OMX matrix in the end
>>> fratar.output.export("/tmp/to_omx_output.omx")
>>> fratar.output.export("/tmp/to_aem_output.aem")

fit()

Runs the IPF instance problem to adjust the matrix

Resulting matrix is the output class member

save_to_project(name: str, file_name: str, project=None) → MatrixRecord

Saves the matrix output to the project file

Arguments:

name (str): Name of the desired matrix record file_name (str): Name for the matrix file name. AEM and OMX supported project (Project, Optional): Project we want to save the results to. Defaults to the active project

aequilibrae.distribution.ipf_core module

aequilibrae.distribution.ipf_core.ipf_core(seed_matrix, target_productions, target_attractions, max_iterations=200, tolerance=0.001, cores=0)

aequilibrae.distribution.setup_ipf module

aequilibrae.distribution.synthetic_gravity_model module

class aequilibrae.distribution.synthetic_gravity_model.SyntheticGravityModel

Bases: object

Simple class object to represent synthetic gravity models

load(file_name)

Loads model from disk. Extension is *.mod

save(file_name)

Saves model to disk in yaml format. Extension is *.mod

Module contents