aequilibrae.distribution

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

Applies a synthetic gravity model.

Model is an instance of SyntheticGravityModel class.

Impedance is an instance of AequilibraEMatrix.

Vectors are a pandas DataFrame.

>>> import pandas as pd
>>> from aequilibrae.distribution import SyntheticGravityModel, GravityApplication

>>> project = create_example(project_path)

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

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

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

# We load the impedance matrix
>>> matrix = project.matrices.get_matrix("skims")
>>> matrix.computational_view(["distance_blended"])

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

# You create the vectors you would have
>>> df = df.assign(productions=df.population * 3.0)
>>> df = df.assign(attractions=df.employment * 4.0)
>>> vectors = df[["productions", "attractions"]]

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

# Create the problem object
>>> args = {"impedance": matrix,
...         "vectors": vectors,
...         "row_field": "productions",
...         "model": model,
...         "column_field": "attractions",
...         "nan_as_zero":True
...         }
>>> gravity = GravityApplication(**args)

# Solve and save the outputs
>>> gravity.apply()
>>> gravity.output.export(project_path / 'matrices' / 'gravity_omx.omx')

>>> project.close()

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

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

Calibrate a traditional gravity model

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

>>> from aequilibrae.distribution import GravityCalibration

>>> project = create_example(project_path)

# We load the demand matrix
>>> demand = project.matrices.get_matrix("demand_omx")
>>> demand.computational_view()

# We load the skim matrix
>>> skim = project.matrices.get_matrix("skims")
>>> skim.computational_view(["time_final"])

>>> args = {"matrix": demand,
...         "impedance": skim,
...         "row_field": "productions",
...         "function": 'expo',
...         "nan_as_zero": True}
>>> gravity = GravityCalibration(**args)

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

>>> project.close()

calibrate()

Calibrate the model

Resulting model is in output class member

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

Iterative proportional fitting procedure

>>> from aequilibrae.distribution import Ipf

>>> project = create_example(project_path)

>>> matrix = project.matrices.get_matrix("demand_omx")
>>> matrix.computational_view()

>>> vectors = pd.DataFrame(
...     {"productions": np.zeros(matrix.zones), "attractions": np.zeros(matrix.zones)},
...     index=matrix.index,
... )

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

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

>>> fratar = Ipf(**ipf_args)
>>> fratar.fit()

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

>>> project.close()

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

class aequilibrae.distribution.SyntheticGravityModel

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

Modules

gravity_application
gravity_calibration	Algorithms to calibrate synthetic gravity models with power and exponential functions
ipf
ipf_core
synthetic_gravity_model