laser.measles.api

laser.measles.api

laser.measles.api.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		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		Pydantic parameter object specific to the mixing model.	required

Example:

```python
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)
```

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.scenario property writable

Scenario DataFrame providing patch populations and coordinates.

laser.measles.api.BaseMixing.get_distances()

Compute pairwise great-circle distances between all patches.

Returns:

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

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

Example:

```python
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))
```

laser.measles.api.CompetingDestinationsMixing.get_migration_matrix()

Compute the competing-destinations migration matrix.

Returns:

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

laser.measles.api.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.

Parameters:

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

Example:

```python
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)
```

laser.measles.api.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

Example:

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

laser.measles.api.GravityMixing.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.

laser.measles.api.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}\]

Parameters:

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

Example:

```python
from laser.measles.mixing.gravity import GravityParams

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

laser.measles.api.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

Example:

```python
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))
```

laser.measles.api.RadiationMixing.get_migration_matrix()

Compute the radiation-based migration matrix.

Returns:

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

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

Example:

```python
from laser.measles.mixing.radiation import RadiationParams

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

laser.measles.api.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

Example:

```python
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))
```

laser.measles.api.StoufferMixing.get_migration_matrix()

Compute the Stouffer migration matrix.

Returns:

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

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

Example:

```python
from laser.measles.mixing.stouffer import StoufferParams

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