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 (SEIR).

Both scenario and params are required positional arguments. There is no default constructor — omitting params raises TypeError.

Args:

scenario (pl.DataFrame): A DataFrame containing the metapopulation patch data.
    Required columns: ``id`` (str), ``pop`` (int), ``lat`` (Float64),
    ``lon`` (Float64), ``mcv1`` (Float64).
params (ABMParams): Simulation parameters including ``num_ticks``, ``seed``,
    and ``start_time``. This argument is **mandatory**.
name (str, optional): The name of the model. Defaults to ``"abm"``.

Notes:

Typical usage::

    from laser.measles.abm import ABMModel, ABMParams
    from laser.measles.abm import components

    params = ABMParams(num_ticks=365, seed=42)
    model = ABMModel(scenario=df, params=params)
    model.add_component(components.InfectionSeedingProcess)
    model.add_component(components.InfectionProcess)
    model.run()

Initialize the disease model with the given scenario and parameters.

Args:

scenario (pl.DataFrame): A DataFrame containing the metapopulation patch data, including population, latitude, and longitude.
parameters (ABMParams): A set of parameters for the model and simulations.
name (str, optional): The name of the model. Defaults to "abm".

Returns:

None

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

All fields are inherited from :class:BaseModelParams. Key fields:

Attributes:

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

Example::

params = ABMParams(num_ticks=365, seed=42)
params = ABMParams(num_ticks=730, seed=0, start_time="2010-06")

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

Helper function to create a component instance with parameters.

This function creates a callable object that will instantiate the component with the given parameters when called by the model.

Parameters

component_class : Type[BaseComponent] The component class to instantiate **kwargs Parameters to pass to the component constructor

Returns

Callable[[Any, Any], BaseComponent] A function that creates the component instance when called by the model

Examples

model.components = [ ... create_component(MyComponent, params=MyComponentParams), ... AnotherComponent, ... ]

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