laser.measles.mixing

mixing

BaseMixing(scenario, params)

Bases: ABC

Abstract base for spatial mixing models.

Subclasses implement a specific migration kernel (gravity, radiation, etc.) that computes patch-to-patch travel probabilities from population sizes and distances. The resulting matrices drive spatial transmission in infection components.

Use a concrete mixer at set parameters time by passing it to an infection component's parameter object, e.g. InfectionParams(mixer=GravityMixing(...)). The model automatically sets the scenario before the matrix is first accessed.

Parameters:

Name	Type	Description	Default
scenario	DataFrame | None	Patch data with pop, lat, and lon columns. May be None when the mixer is attached to a model component (the model sets it automatically).	required
params	BaseModel | None	Pydantic parameter object specific to the mixing model.	required

Examples:

from laser.measles.mixing.gravity import GravityMixing, GravityParams

# Construct a mixer — scenario is set automatically by the model
mixer = GravityMixing(params=GravityParams(k=0.01, c=2.0))
migration = mixer.migration_matrix  # (N, N) patch-to-patch travel
mixing = mixer.mixing_matrix        # rows sum to 1 (includes self-mixing)

migration_matrix property

Migration matrix computed from get_migration_matrix().

Returns:

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

mixing_matrix property

Mixing matrix computed from get_mixing_matrix().

Returns:

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

scenario property writable

Scenario DataFrame providing patch populations and coordinates.

get_distances()

Compute pairwise great-circle distances between all patches.

Returns:

Type	Description
ndarray	Distance matrix of shape (N, N) in kilometres.

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)

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.

trips_into()

Returns the number of trips into each patch per tick.

trips_out_of()

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

CompetingDestinationsMixing(scenario=None, params=None)

Bases: BaseMixing

Competing-destinations migration model for spatial mixing.

Extends the gravity kernel with a correction that accounts for the attractiveness of alternative destinations:

\[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}\]

When \(\delta < 0\), destinations that are surrounded by many other attractive locations receive less travel — the nearby alternatives "compete" for travellers.

Parameters:

Name	Type	Description	Default
scenario	DataFrame | None	Patch data. None when the model will set it automatically.	None
params	CompetingDestinationsParams | None	Model parameters.	None

Examples:

from laser.measles.mixing.competing_destinations import (
    CompetingDestinationsMixing, CompetingDestinationsParams,
)
from laser.measles.compartmental import components
from laser.measles import create_component

mixer = CompetingDestinationsMixing(
    params=CompetingDestinationsParams(k=0.01, delta=-0.5),
)
infection_params = components.InfectionParams(beta=0.8, mixer=mixer)
model.add_component(create_component(components.InfectionProcess, infection_params))

get_migration_matrix()

Compute the competing-destinations migration matrix.

Returns:

Type	Description
ndarray	Migration matrix of shape (N, N).

CompetingDestinationsParams

Bases: BaseModel

Parameters for the competing-destinations mixing model.

Extends the gravity kernel with a correction factor that penalises destinations surrounded by many other attractive alternatives.

Attributes:

Name	Type	Description
a	float	Population source exponent.
b	float	Population destination exponent.
c	float	Distance decay exponent.
k	float	Average trip probability.
delta	float	Destination-competition exponent — negative values penalise destinations with many nearby competitors.

Examples:

from laser.measles.mixing.competing_destinations import CompetingDestinationsParams

params = CompetingDestinationsParams(a=1.0, b=1.0, c=1.5, k=0.01, delta=-0.5)

GravityMixing(scenario=None, params=None)

Bases: BaseMixing

Gravity migration model for spatial mixing.

Computes a spatial mixing matrix where travel probability between patches is proportional to population sizes and inversely proportional to distance:

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

The scenario is optional at construction time. When attached to a model via InfectionParams(mixer=...), the model sets the scenario automatically before the mixing matrix is first computed.

Parameters:

Name	Type	Description	Default
scenario	DataFrame | None	Patch data with pop, lat, and lon columns. None when the model will set it.	None
params	GravityParams | None	Gravity model parameters. Uses GravityParams defaults if None.	None

Examples:

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)]

get_migration_matrix()

Compute the gravity-based migration matrix.

Returns:

Type	Description
ndarray	Migration matrix of shape (N, N) where entry [i, j] is the probability of travel from patch i to patch j.

GravityParams

Bases: BaseModel

Parameters for the gravity migration model.

The gravity kernel computes migration flow as:

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

Attributes:

Name	Type	Description
a	float	Population source exponent (applied as a - 1 inside the kernel).
b	float	Population destination exponent.
c	float	Distance decay exponent - larger values suppress long-distance travel.
k	float	Average trip probability (scales the overall matrix).

Examples:

from laser.measles.mixing.gravity import GravityParams

params = GravityParams(a=1.0, b=1.0, c=2.0, k=0.01)

RadiationMixing(scenario=None, params=None)

Bases: BaseMixing

Radiation migration model for spatial mixing.

Outbound migration from origin i to destination j is enhanced by the destination population and absorbed by the density of nearer destinations (intervening opportunities):

\[M_{i,j} = k \frac{p_i \, p_j}{(p_i + s_{ij})(p_i + p_j + s_{ij})}\]

where \(s_{ij} = \sum_{k \in \Omega(i,j)} p_k\) is the total population of patches closer to i than j.

Parameters:

Name	Type	Description	Default
scenario	DataFrame | None	Patch data. None when the model will set it automatically.	None
params	RadiationParams | None	Model parameters. Uses RadiationParams defaults if None.	None

Examples:

from laser.measles.mixing.radiation import RadiationMixing, RadiationParams
from laser.measles.compartmental import components
from laser.measles import create_component

mixer = RadiationMixing(params=RadiationParams(k=0.01))
infection_params = components.InfectionParams(beta=0.8, mixer=mixer)
model.add_component(create_component(components.InfectionProcess, infection_params))

The include_home and k model parameters are configured via RadiationParams.

get_migration_matrix()

Compute the radiation-based migration matrix.

Returns:

Type	Description
ndarray	Migration matrix of shape (N, N).

RadiationParams

Bases: BaseModel

Parameters for the radiation migration model.

Attributes:

Name	Type	Description
include_home	bool	Whether to include home in the migration matrix
k	float	Scale parameter (avg trip probability)

Examples:

from laser.measles.mixing.radiation import RadiationParams

params = RadiationParams(k=0.02, include_home=True)

StoufferMixing(scenario=None, params=None)

Bases: BaseMixing

Stouffer intervening-opportunities migration model.

Long-distance travel is suppressed by the cumulative population of patches between origin and destination (intervening opportunities):

\[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
scenario	DataFrame | None	Patch data. None when the model will set it automatically.	None
params	StoufferParams | None	Model parameters. Uses StoufferParams defaults if None.	None

Examples:

from laser.measles.mixing.stouffer import StoufferMixing, StoufferParams
from laser.measles.compartmental import components
from laser.measles import create_component

mixer = StoufferMixing(params=StoufferParams(k=0.01))
infection_params = components.InfectionParams(beta=0.8, mixer=mixer)
model.add_component(create_component(components.InfectionProcess, infection_params))

The include_home model parameter is configured via StoufferParams.

get_migration_matrix()

Compute the Stouffer migration matrix.

Returns:

Type	Description
ndarray	Migration matrix of shape (N, N).

StoufferParams

Bases: BaseModel

Parameters for the Stouffer migration model.

Attributes:

Name	Type	Description
include_home	bool	Whether to include home in the migration matrix
k	float	Scale parameter (avg trip probability)

Examples:

from laser.measles.mixing.stouffer import StoufferParams

params = StoufferParams(k=0.02, include_home=True, a=1.0, b=1.0)