Skip to content

laser.measles.api

laser.measles.api

laser.measles.api.BaseMixing(scenario, params)

Bases: ABC

Base class for migration models.

laser.measles.api.BaseMixing.migration_matrix property

Migration matrix computed from get_migration_matrix().

Returns:

Type Description
ndarray

np.ndarray: The migration matrix with lazy computation and caching.

laser.measles.api.BaseMixing.mixing_matrix property

Mixing matrix computed from get_mixing_matrix().

Returns:

Type Description
ndarray

np.ndarray: The mixing matrix with lazy computation and caching.

laser.measles.api.BaseMixing.get_migration_matrix() abstractmethod

Initialize a migration/diffusion matrix for population mixing. The diffusion matrix is a square matrix where each row represents the outbound migration from a given patch to all other patches e.g., [i,j] = [from_i, to_j].

Convention is: - Trips into node j: N_i @ M[i,j] - Trips out of node i: np.sum(M[i,j] * N_i[:,np.newaxis], axis=1)

Returns:

Type Description
ndarray

np.ndarray: The diffusion matrix: (N, N)

laser.measles.api.BaseMixing.get_mixing_matrix()

Initialize a mixing matrix for population mixing.

The mixing matrix is a square matrix where each row represents the mixing of a given patch to all other patches e.g., [i,j] = [from_i, to_j]. It also includes internal mixing within a patch.

laser.measles.api.BaseMixing.trips_into()

Returns the number of trips into each patch per tick.

laser.measles.api.BaseMixing.trips_out_of()

Returns the number of trips out of each patch per tick.

laser.measles.api.CompetingDestinationsMixing(scenario=None, params=None)

Bases: BaseMixing

Competing destinations mixing model that accounts for the effects of nearby destinations.

Formula

.. math:: M_{i,j} = k \frac{p_i^{a-1} p_j^b}{d_{i,j}^c} \left(\sum_{k \ne i,j} \frac{p_k^b}{d_{ik}^c}\right)^\delta

Where
  • M_{i,j}: migration flow from origin i to destination j
  • k: calibration constant
  • p_i, p_j, p_k: population at origins/destinations
  • d_{i,j}, d_{ik}: distances between l ocations
  • a, b, c, δ: model parameters

laser.measles.api.CompetingDestinationsParams

Bases: BaseModel

Parameters for the competing destinations mixing model.

laser.measles.api.GravityMixing(scenario=None, params=None)

Bases: BaseMixing

Gravity migration model.

Computes a spatial mixing matrix based on patch populations and distances:

.. math::

1
M_{i,j} = k \cdot p_i^{a-1} \cdot p_j^b \cdot d_{i,j}^{-c}

The scenario argument is optional. When this mixer is attached to a model via InfectionParams(mixer=...) the model automatically sets the scenario before the mixing matrix is first computed (lazy initialisation). You only need to pass scenario explicitly when using the mixer standalone (e.g. to inspect the matrix before running a simulation).

Parameters

scenario : pl.DataFrame or None, optional Patch data with id, lat, lon, pop, and mcv1 columns. If None, must be set before the mixing matrix is accessed (happens automatically when the mixer is attached to a model component). params : GravityParams or None, optional Gravity model parameters. Uses :class:GravityParams defaults if None.

Examples

Typical usage — let the model set the scenario automatically:

.. code-block:: python

1
2
3
4
5
6
7
from laser.measles.mixing.gravity import GravityMixing, GravityParams
from laser.measles.compartmental import components
from laser.measles import create_component

mixer = GravityMixing(params=GravityParams(a=1.0, b=1.0, c=2.0, k=0.01))
infection_params = components.InfectionParams(beta=0.8, mixer=mixer)
model.components = [create_component(components.InfectionProcess, infection_params)]

Standalone usage (inspect the matrix before running):

.. code-block:: python

1
2
mixer = GravityMixing(scenario=scenario, params=GravityParams(c=2.0, k=0.01))
print(mixer.mixing_matrix)

laser.measles.api.GravityParams

Bases: BaseModel

Parameters for the gravity migration model.

Formula

.. math:: M_{i,j} = k \cdot p_i^{a-1} \cdot p_j^b \cdot d_{i,j}^{-c}

Parameters:

Name Type Description Default
a float

Population source scale parameter

 required
b float

Population target scale parameter

 required
c float

Distance exponent

 required
k float

Scale parameter

 required

laser.measles.api.RadiationMixing(scenario=None, params=None)

Bases: BaseMixing

Radiation migration model where outbound migration flux from origin to destination is enhanced by destination population and absorbed by the density of nearer destinations.

Formula

.. math:: M_{i,j} = k \frac{p_i p_j}{\left(p_i + \sum_{k \in \Omega(i,j)} p_k\right)\left(p_i + p_j + \sum_{k \in \Omega(i,j)} p_k\right)}

Parameters:

Name Type Description Default
include_home bool

Whether to include home in the migration matrix

 required
k float

Scale parameter (avg trip probability)

 required

laser.measles.api.RadiationParams

Bases: BaseModel

Parameters for the radiation migration model.

Parameters:

Name Type Description Default
include_home bool

Whether to include home in the migration matrix

 required
k float

Scale parameter (avg trip probability)

 required

laser.measles.api.StoufferMixing(scenario=None, params=None)

Bases: BaseMixing

Stouffer migration model where long distance travel is impacted by intervening opportunities.

Formula

.. math:: M_{i,j} = k p_i^a \sum_j \left(\frac{p_j}{\sum_{k \in \Omega(i,j)} p_k}\right)^b

Parameters:

Name Type Description Default
include_home bool

Whether to include home in the migration matrix

 required

laser.measles.api.StoufferParams

Bases: BaseModel

Parameters for the stouffer migration model.

Parameters:

Name Type Description Default
include_home bool

Whether to include home in the migration matrix

 required
k float

Scale parameter (avg trip probability)

 required