laser.measles.abm.model

laser.measles.abm.model

A class to represent the agent-based model.

laser.measles.abm.model.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.model.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.model.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.model.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.model.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.model.ABMModel.setup_patches()

Setup the patches for the model.

laser.measles.abm.model.ABMModel.setup_people()

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