Decay

Decay rates express how travel costs influence behavior, discounting the value of destinations based on how hard they are to reach (in terms of time, monetary costs, etc.). Decay rates are utilized in the calculation of accessibility scores and in trip distribution procedures.

This module provides classes and functions for configuring and applying decay rates for use in emma modeling.

Classes and Functions

  • Decay: a base class defining the basic parameters of decay rates. Various forms of decay rates, with distinct forms and applications, are defined as child classes:

    • LinDecay: linear

    • ExpDecay: exponential

    • LogDecay: logistic

    • LogNormalDecay: lognormal (probability density function)

    • LogNormalDecay_cdf: lognormal (cumulative density function)

  • dictToDecay: constructs a Decay object from a dictionary.

  • decayToJson: dumps a Decay object to a json file for storage

  • jsonToDecay: creates a Decay object from a json file

  • vectorize: a numpy vectorization wrapper that work with instance methods. Vectorizes Decay.evalute as Decay.vevaluate. However, purer vectorization can be acheived through Decay.apply.

Decay

class emma.decay.Decay(const, coef, min_impedance=0.0, max_impedance=inf, excl_less_than_min=False, excl_greater_than_max=True, lbound=0.0, ubound=1.0, name=None, desc=None)

The Decay class stores common parameters for modeling the degradation of the value of an OD connection based on impedance (time, e.g.) of traveling between zones.

The Decay class is an abstract class, and it cannot be instantiated directly. It provides basic parameters defining the components of a decay calculation, adjustments to impedance values, and bounds of the decay expression.

Parameters

  • const (Float) – The constant term in the decay expression.

  • coef (Float) – The coefficient term in the decay expression.

  • min_impedance (Float, optional) – Default is 0, which implies no minimum value (impedance values less than zero are returned as zero, since negative travel impedances are impossible).

  • max_impedance (Float, optional) – Default is float(‘inf’), which implies no maximum value.

  • excl_less_than_min (Boolean, optional) – Default is False (impedance values less than min_impedance are treated as min_impedance). If True, impedance values less than min_impedance return a decay rate of zero.

  • excl_greater_than_max (Boolean, optional) – Default is True (impedance values greater than max_impedance are return a decay rate of zero). If True, impedance values greater than max_impedance are treated as max_impedance.

  • lbound (Float, optional) – Default is 0.0. Defines the lower bound of the decay formula. If the result of the decay calculation for a given impedance value is less than lbound, lbound is returned. (The negative exponential decay formula assymptotically approaches zero as impednace values increase).

  • ubound (Float, optional) – Default is 1.0. Defines the upper bound of the decay formula. If the result of the decay calculation for a given impedance value is greater than ubound, ubound is returned. The ubound parameter is often utilized when the const term is gretaer than 1.0.

  • name (String) – A short name to identify the decay rate.

  • desc (String, optional) – Default is None. A short description of the decay parameters (“Home-based- work auto trips”, e.g.).

abstract evaluate(impedance)

Evaluates the decay expression for a given impedance value.

Parameters

impedance (Numeric) – A non-negative impedance (negative impedances evaluate to NaN).

Returns

decay_factor – The result of the Decay formula applied to impedance, honoring parameters governing input and output limits.

Return type

Float

plot(impedances, **kwargs)

Generate a plot showing decay factors assiciated with a series of impedance values.

Parameters

impedances (array-like) – A series of values for which to estimate decay factors.

toDict(dec_type)

Dump a decay rate to a dictionary.

vevaluate()

A vectorized implementation of the evaluate method of a Decay object (applies evaluate to a vector of impedances). Note that vectorized functions are a convenience provided by numpy that are basically just for loops and may not be performant.

LinDecay

class emma.decay.LinDecay(const, coef, min_impedance=0.0, max_impedance=inf, excl_less_than_min=False, excl_greater_than_max=True, lbound=0.0, ubound=1.0, name=None, desc=None)

The LinDecay class assumes a simple linear formula that defines a line for discounting the value of a connection based on cumulative impedance. The linear decay formula is shown below:

\[self.const + (self.coef * impedance))\]
apply(impedance, inplace=False, neg_value=nan)

A true vectorized procedure that calculates decay factors to an input vector of impedances. While this is faster than vevaluate, it may also consume more memory.

Parameters

  • impedance (Numeric) – A vector of non-negative impedance (negative impedances evaluate to NaN).

  • inplace (Boolean) – If True, the impedance vector will be modified. If False, the impedance vector is retained and a new decay vector is returned.

  • neg_value (np.float, default=np.nan) – Negative values in impedance are invalid. They will be represented in the returned array by the assigned neg_value.

Returns

decay_factors – The result of the Decay formula applied to impedance, honoring parameters governing input and output limits.

Return type

ndarray

evaluate(impedance)

Evaluates the decay expression for a given impedance value.

Parameters

impedance (Numeric) – A non-negative impedance (negative impedances evaluate to NaN).

Returns

decay_factor – The result of the Decay formula applied to impedance, honoring parameters governing input and output limits.

Return type

Float

toDict()

Dump a decay rate to a dictionary.

ExpDecay

class emma.decay.ExpDecay(const, coef, min_impedance=0.0, max_impedance=inf, excl_less_than_min=False, excl_greater_than_max=True, lbound=0.0, ubound=1.0, name=None, desc=None)

The ExpDecay class assumes a (negative) exponental formula that defines a curve for discounting the value of a connection based on cumulative impedance. The exponential decay formula is shown below:

\[self.const * (e^{self.coef * impedance})\]
apply(impedance, inplace=False, neg_value=nan)

A true vectorized procedure that calculates decay factors to an input vector of impedances. While this is faster than vevaluate, it may also consume more memory.

Parameters

  • impedance (Numeric) – A vector of non-negative impedance (negative impedances evaluate to NaN).

  • inplace (Boolean) – If True, the impedance vector will be modified. If False, the impedance vector is retained and a new decay vector is returned.

  • neg_value (np.float, default=np.nan) – Negative values in impedance are invalid. They will be represented in the returned array by the assigned neg_value.

Returns

decay_factors – The result of the Decay formula applied to impedance, honoring parameters governing input and output limits.

Return type

ndarray

evaluate(impedance)

Evaluates the decay expression for a given impedance value.

Parameters

impedance (Numeric) – A non-negative impedance (negative impedances evaluate to NaN).

Returns

decay_factor – The result of the Decay formula applied to impedance, honoring parameters governing input and output limits.

Return type

Float

toDict()

Dump a decay rate to a dictionary.

LogDecay

class emma.decay.LogDecay(const, coef, min_impedance=0.0, max_impedance=inf, excl_less_than_min=False, excl_greater_than_max=True, lbound=0.0, ubound=1.0, name=None, desc=None)

The LogDecay class assumes a logistic formula that defines a curve for discounting the value of a connection based on cumulative impedance. The logistic decay formula is shown below:

\[\dfrac{1}{1 + e^{-(self.const + self.coef \cdot impedance)}}\]
apply(impedance, inplace=False, neg_value=nan)

A true vectorized procedure that calculates decay factors to an input vector of impedances. While this is faster than vevaluate, it may also consume more memory.

Parameters

  • impedance (Numeric) – A vector of non-negative impedance (negative impedances evaluate to NaN).

  • inplace (Boolean) – If True, the impedance vector will be modified. If False, the impedance vector is retained and a new decay vector is returned.

  • neg_value (np.float, default=np.nan) – Negative values in impedance are invalid. They will be represented in the returned array by the assigned neg_value.

Returns

decay_factors – The result of the Decay formula applied to impedance, honoring parameters governing input and output limits.

Return type

ndarray

evaluate(impedance)

Evaluates the decay expression for a given impedance value.

Parameters

impedance (Numeric) – A non-negative impedance (negative impedances evaluate to NaN).

Returns

decay_factor – The result of the Decay formula applied to impedance, honoring parameters governing input and output limits.

Return type

Float

toDict()

Dump a decay rate to a dictionary.

LogNormalDecay

class emma.decay.LogNormalDecay(meanlog, sdlog, min_impedance=0.0, max_impedance=inf, excl_less_than_min=False, excl_greater_than_max=True, lbound=0.0, ubound=1.0, name=None, desc=None)

The LogNormalDecay class assumes a lognormal distribution that defines a curve for discounting the value of a connection based on estimated impedance. This is a non-cumulative decay function.

\[\left(\frac{1}{impedance \cdot self.sdlog \cdot \sqrt{2 \pi}}\right) \cdot \left(e^{-\frac{(\ln (impedance) - self.meanlog)^2}{2 \cdot self.sdlog^2}}\right)\]
Parameters

  • meanlog (numeric) –

  • sdlog (numeric) –

apply(impedance, inplace=False, neg_value=nan)

A true vectorized procedure that calculates decay factors to an input vector of impedances. While this is faster than vevaluate, it may also consume more memory.

Parameters

  • impedance (Numeric) – A vector of non-negative impedance (negative impedances evaluate to NaN).

  • inplace (Boolean) – If True, the impedance vector will be modified. If False, the impedance vector is retained and a new decay vector is returned.

  • neg_value (np.float, default=np.nan) – Negative values in impedance are invalid. They will be represented in the returned array by the assigned neg_value.

Returns

decay_factors – The result of the Decay formula applied to impedance, honoring parameters governing input and output limits.

Return type

ndarray

evaluate(impedance)

Evaluates the decay expression for a given impedance value.

Parameters

impedance (Numeric) – A non-negative impedance (negative impedances evaluate to NaN).

Returns

decay_factor – The result of the Decay formula applied to impedance, honoring parameters governing input and output limits.

Return type

Float

LogNormalDecay_cdf

class emma.decay.LogNormalDecay_cdf(meanlog, sdlog, min_impedance=0.0, max_impedance=inf, excl_less_than_min=False, excl_greater_than_max=True, lbound=0.0, ubound=1.0, name=None, desc=None)

The LogNormalDecay_cdf class assumes a lognormal distribution that defines a curve for discounting the value of a connection based on estimated impedance. This is a cumulative decay function (the cumulative form of the LogNormalDecay pdf curve).

\[\frac{1}{2} + \frac{1}{2} * erf\left[\frac{\ln impedance - self.meanlog}{\sqrt{2} \cdot self.sdlog}\right]\]
Parameters

  • meanlog (numeric) –

  • sdlog (numeric) –

apply(impedance, inplace=False, neg_value=nan)

A true vectorized procedure that calculates decay factors to an input vector of impedances. While this is faster than vevaluate, it may also consume more memory.

Parameters

  • impedance (Numeric) – A vector of non-negative impedance (negative impedances evaluate to NaN).

  • inplace (Boolean) – If True, the impedance vector will be modified. If False, the impedance vector is retained and a new decay vector is returned.

  • neg_value (np.float, default=np.nan) – Negative values in impedance are invalid. They will be represented in the returned array by the assigned neg_value.

Returns

decay_factors – The result of the Decay formula applied to impedance, honoring parameters governing input and output limits.

Return type

ndarray

evaluate(impedance)

Evaluates the decay expression for a given impedance value.

Parameters

impedance (Numeric) – A non-negative impedance (negative impedances evaluate to NaN).

Returns

decay_factor – The result of the Decay formula applied to impedance, honoring parameters governing input and output limits.

Return type

Float

Functions

emma.decay.dictToDecay(decay_dict)

Construct a decay rate from a dictionary.

emma.decay.decayToJson(decay_obj, output_file)

Stores a Decay object in a JSON config file.

Parameters

  • decay_obj (Decay) – A Decay object defining decay parameters.

  • output_file (string) – The path to the output file. If just the file name is passed, the file will be saved in the current working directory.

Returns

Writes a decay config JSON file to the output file location.

Return type

None

See also

jsonToDecay(), Decay()

emma.decay.jsonToDecay(in_file)

Creates a Decay object from a JSON config file.

Parameters

in_file (string) – The file name in the current working directory or full path to the JSON config file from which to generate the Decay object.

Raises

KeyError – If ‘in_file’ is not a valid Decay config file (i.e., does not contain keys associated with Decay attributes).

Returns

Return type

Decay

See also

decayToJson(), Decay()

emma.decay.vectorize(otypes=None, signature=None)

Numpy vectorization wrapper that works with instance methods.