laser.measles.abm

laser.measles.abm

laser.measles.abm.ABMModel(scenario, params, name='abm')

Bases: BaseLaserModel

Agent-based model for measles transmission with daily timesteps.

Tracks individual agents through SEIR states, supporting heterogeneous vaccination, age structure, and stochastic transmission. Use this model when you need individual-level resolution — for example, tracking vaccination histories or age-dependent susceptibility. For faster population-level dynamics, see BiweeklyModel or CompartmentalModel.

This is the first object created in the build model stage of the researcher workflow. After construction, attach components with add_component or by setting the components property, then call model.run().

Parameters:

Name	Type	Description	Default
scenario	DataFrame | BaseABMScenario	Metapopulation patch data. Required columns: id (str), pop (int), lat (Float64), lon (Float64), mcv1 (Float64). A plain polars.DataFrame is automatically wrapped in BaseABMScenario.	required
params	ABMParams	Simulation parameters including num_ticks, seed, and start_time. This argument is mandatory.	required
name	str	Display name for log messages. Defaults to "abm".	'abm'

Example:

```python
import laser.measles as lm

params = lm.ABMParams(num_ticks=365, seed=42, start_time="2000-01")
model = lm.ABMModel(scenario=df, params=params)
model.add_component(lm.InfectionSeedingProcess)
model.add_component(lm.InfectionProcess)
model.run()
```

laser.measles.abm.ABMModel.from_snapshot(path, params, components=None, verbose=True) classmethod

Restore an ABMModel from an HDF5 snapshot file.

Convenience wrapper around load_snapshot. Use this to resume a simulation from a checkpoint saved with save_snapshot.

Parameters:

Name	Type	Description	Default
path		Path to the HDF5 file written by save_snapshot.	required
params	ABMParams	ABMParams for the resumed segment. Set start_time to the snapshot date and num_ticks to the remaining simulation duration.	required
components	list | None	Ordered list of component classes — same as the original model.	None
verbose	bool	Print a loading summary.	True

Returns:

Type	Description
ABMModel	A configured ABMModel ready for model.run().

Example:

```python
import laser.measles as lm

params2 = lm.ABMParams(num_ticks=1825, seed=42, start_time="2009-12")
model2 = lm.ABMModel.from_snapshot(
    "checkpoint.h5",
    params2,
    components=[lm.VitalDynamicsProcess, lm.InfectionProcess],
)
model2.run()
```

laser.measles.abm.ABMModel.infect(indices, num_infected)

Infect agents by moving them from Susceptible to Exposed state.

This method finds the transmission component and delegates to its infect method, which handles both individual agent state updates and patch counter updates.

Parameters:

Name	Type	Description	Default
indices	int | ndarray	The indices of the agents to infect.	required
num_infected	int | ndarray	The number of agents to infect (for API consistency). Note: In ABM, this should match the length of indices.	required

laser.measles.abm.ABMModel.initialize_people_capacity(capacity, initial_count=-1)

Initialize the people LaserFrame with a new capacity while preserving all properties.

This method uses the factory method from BasePeopleLaserFrame to create a new instance of the same type with the specified capacity, copying all properties from the existing instance.

Parameters:

Name	Type	Description	Default
capacity	int	The new capacity for the people LaserFrame	required

laser.measles.abm.ABMModel.plot(fig=None)

Plots various visualizations related to the scenario and population data.

Parameters:

fig (Figure, optional): A matplotlib Figure object to use for plotting. If None, a new figure will be created.

Yields:

None: This function uses a generator to yield control back to the caller after each plot is created.

The function generates three plots:

1. A scatter plot of the scenario patches and populations.
2. A histogram of the distribution of the day of birth for the initial population.
3. A pie chart showing the distribution of update phase times.

laser.measles.abm.ABMModel.setup_patches()

Setup the patches for the model.

laser.measles.abm.ABMModel.setup_people()

Placeholder for people - sets the data types for patch_id and susceptibility.

laser.measles.abm.ABMParams

Bases: BaseModelParams

Parameters for the agent-based measles model (daily timesteps).

Inherits all fields from BaseModelParams. Each tick represents one day, and the model tracks four SEIR states.

Parameters:

Name	Type	Description	Default
num_ticks	int	Number of daily simulation steps (e.g., 365 = 1 year).	required
seed	int	Random seed for reproducibility. Default: 20250314.	required
start_time	str	Simulation start in "YYYY-MM" format. Default: "2000-01".	required
verbose	bool	Print detailed logging. Default: False.	required

Example:

```python
params = ABMParams(num_ticks=365, seed=42, start_time="2000-01")
```

laser.measles.abm.ABMParams.states property

SEIR state names: ["S", "E", "I", "R"].

laser.measles.abm.ABMParams.time_step_days property

Duration of one tick in days (always 1 for the ABM).

laser.measles.abm.BaseABMScenario(df)

Bases: BaseScenario

Scenario wrapper for agent-based models.

Validates that the input DataFrame conforms to the BaseABMScenarioSchema (columns id, pop, lat, lon, mcv1) and makes the data available to model components during the prepare scenario stage.

Parameters:

Name	Type	Description	Default
df	DataFrame	Polars DataFrame with patch-level data.	required

Example:

```python
from laser.measles.scenarios.synthetic import single_patch_scenario

scenario = single_patch_scenario(population=50_000, mcv1_coverage=0.85)
```

laser.measles.abm.create_component(component_class, params=None)

Wrap a component class and its parameters into a single callable.

Use this at set parameters time when a component requires a custom Pydantic parameter object. The returned factory is callable with the same (model, verbose) signature that BaseLaserModel.components expects, so it can be placed directly in the component list.

Parameters:

Name	Type	Description	Default
component_class	type[T]	The component class to instantiate.	required
params	type[B] | None	A Pydantic parameter object (or None for defaults).	None

Returns:

Type	Description
Callable[[Any, Any], T]	A callable that creates the component when invoked by the model.

Example:

```python
from laser.measles import create_component
from laser.measles.compartmental.components import InfectionProcess, InfectionParams

model.components = [
    create_component(InfectionProcess, InfectionParams(beta=0.8)),
]
```

laser.measles.abm.load_snapshot(path, params, components=None, verbose=True)

Load an ABM from an HDF5 snapshot file and return it ready to run.

Restores the population, patch state, scenario, and metadata saved by save_snapshot. Components that modify the people frame (e.g. VitalDynamicsProcess) detect the snapshot context via model._from_snapshot and skip frame setup. Set params.start_time to the snapshot date printed by save_snapshot.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the HDF5 snapshot file written by save_snapshot.	required
params	ABMParams	ABMParams for the resumed segment. Set start_time to the snapshot date and num_ticks to the remaining duration.	required
components	list | None	Ordered list of component classes to attach — same list as used when building the original model.	None
verbose	bool	Print a loading summary.	True

Returns:

Type	Description
ABMModel	A configured ABMModel instance. Call model.run() to continue the simulation.

Example:

```python
import laser.measles as lm

params2 = lm.ABMParams(num_ticks=1825, seed=42, start_time="2009-12")
model2 = lm.load_snapshot(
    "checkpoint.h5",
    params2,
    components=[lm.VitalDynamicsProcess, lm.InfectionProcess],
)
model2.run()
```

laser.measles.abm.save_snapshot(model, path, squash_recovered=True, verbose=True)

Save ABM state to an HDF5 snapshot file.

Call this after ABMModel.run() to persist the full population and patch state. The resulting HDF5 file can be resumed with load_snapshot to continue the simulation from exactly where it left off — useful for warm-start parameter sweeps, segmented cluster jobs, or reproducible checkpoints.

Warning

This function mutates model: recovered agents are squashed (if squash_recovered=True) and future vaccination dates are normalized. Do not continue running the model after calling this function.

Parameters:

Name	Type	Description	Default
model	ABMModel	A fully-run (or mid-run) ABMModel instance.	required
path	str | Path	Destination HDF5 file path (created or overwritten).	required
squash_recovered	bool	If True (default), remove recovered agents before saving. This dramatically reduces file size for long measles runs.	True
verbose	bool	Print a progress summary.	True

Example:

```python
import laser.measles as lm

params = lm.ABMParams(num_ticks=3650, seed=42, start_time="2000-01")
model = lm.ABMModel(scenario, params)
model.components = [lm.VitalDynamicsProcess, lm.InfectionProcess]
model.run()

lm.save_snapshot(model, "checkpoint.h5")
# Do not use model after this point.
```