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.

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