laser.measles.migration

laser.measles.migration

laser.measles.migration.get_diffusion_matrix(df, scale, func, f_kwargs, enforce_scale=True)

Build a row-stochastic diffusion matrix from a migration kernel.

Computes a raw migration matrix using func(**f_kwargs), normalises it so the average row sum equals 1, scales by scale, then fills the diagonal so every row sums exactly to 1. The result can be used directly as a spatial mixing matrix in infection components.

Parameters:

Name	Type	Description	Default
df	DataFrame	Scenario DataFrame (only its length is used to handle the single-patch edge case).	required
scale	float	Average fraction of a patch's population that travels per tick. Capped automatically when enforce_scale is True.	required
func	Callable	Migration kernel function (e.g., [gravity][laser.core.migration.gravity]).	required
f_kwargs	dict	Keyword arguments forwarded to func.	required
enforce_scale	bool	If True, cap scale so that no diagonal entry becomes negative (i.e., no patch sends out more than 100 % of its population).	True

Returns:

Type	Description
ndarray	Row-stochastic diffusion matrix of shape (N, N) where N is the number of patches.

Example:

```python
from laser.measles.migration import get_diffusion_matrix, pairwise_haversine
from laser.core.migration import gravity

distances = pairwise_haversine(scenario)
mat = get_diffusion_matrix(
    scenario,
    scale=0.01,
    func=gravity,
    f_kwargs=dict(populations=scenario["pop"].to_numpy(),
                  distances=distances, k=1.0, a=1.0, b=1.0, c=2.0),
)
```

laser.measles.migration.init_gravity_diffusion(df, scale, dist_exp, enforce_scale=True)

Initialize a gravity 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].

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with 'pop', 'lat', and 'lon' columns	required
scale	float	Scaling factor for the diffusion matrix, i.e., the average total outbound migration	required
dist_exp	float	Distance exponent for the gravity model, i.e., the sensitivity of migration to distance	required

Returns:

Type	Description
ndarray	Normalized diffusion matrix where each row sums to 1

laser.measles.migration.pairwise_haversine(df)

Pairwise distances for all (lon, lat) points using the Haversine formula.

Parameters:

Name	Type	Description	Default
df	DataFrame	Polars DataFrame with 'lon' and 'lat' columns	required

Returns:

Type	Description
	Pairwise distances in kilometers