laser.measles.compartmental

laser.measles.compartmental

laser.measles.compartmental.BaseScenario = BaseCompartmentalScenario module-attribute

Base class for scenario data wrappers.

Provides a wrapper around polars DataFrames with additional validation and convenience methods.

laser.measles.compartmental.CompartmentalModel(scenario, params, name='compartmental')

Bases: BaseLaserModel

A class to represent the compartmental model with daily timesteps.

Args:

scenario (BaseScenario): A scenario containing the scenario data, including population, latitude, and longitude.
params (CompartmentalParams): A set of parameters for the model.
name (str, optional): The name of the model. Defaults to "compartmental".

Notes:

This class initializes the model with the given scenario and parameters. The scenario must include the following columns:

    - `id` (string): The name of the patch or location.
    - `pop` (integer): The population count for the patch.
    - `lat` (float degrees): The latitude of the patches (e.g., from geographic or population centroid).
    - `lon` (float degrees): The longitude of the patches (e.g., from geographic or population centroid).
    - `mcv1` (float): The MCV1 coverage for the patches.

The default model uses SEIR compartments:
    - S: Susceptible individuals
    - E: Exposed individuals (infected but not yet infectious)
    - I: Infectious individuals
    - R: Recovered/immune individuals

Initialize the disease model with the given scenario and parameters.

Args:

scenario (BaseScenario): A scenario containing the scenario data, including population, latitude, and longitude.
params (CompartmentalParams): A set of parameters for the model, including seed, num_ticks, beta, sigma, gamma, and other SEIR parameters.
name (str, optional): The name of the model. Defaults to "compartmental".

Returns:

None

laser.measles.compartmental.CompartmentalModel.expose(indices, num_exposed)

Exposes the given nodes with the given number of exposed individuals. Moves individuals from Susceptible to Exposed compartment.

Parameters:

Name	Type	Description	Default
indices	int | ndarray	The indices of the nodes to expose.	required
num_exposed	int | ndarray	The number of exposed individuals.	required

laser.measles.compartmental.CompartmentalModel.from_snapshot(path, params, components=None, verbose=True) classmethod

Load a CompartmentalModel from an HDF5 snapshot.

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

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the HDF5 file written by save_snapshot.	required
params	CompartmentalParams	CompartmentalParams for the resumed segment.	required
components	list | None	Ordered list of component classes — same as the original model, minus InfectionSeedingProcess.	None
verbose	bool	Print a loading summary.	True

Returns:

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

Example:

```python
import laser.measles as lm
from laser.measles.compartmental.components import InfectionProcess

params2 = lm.CompartmentalParams(num_ticks=365, seed=42, start_time="2001-01")
model2 = lm.CompartmentalModel.from_snapshot(
    "checkpoint.h5", params2, components=[InfectionProcess]
)
model2.run()
```

laser.measles.compartmental.CompartmentalModel.infect(indices, num_infected)

Infects the given nodes with the given number of infected individuals. Moves individuals from Exposed to Infected compartment.

Parameters:

Name	Type	Description	Default
indices	int | ndarray	The indices of the nodes to infect.	required
num_infected	int | ndarray	The number of infected individuals.	required

laser.measles.compartmental.CompartmentalModel.recover(indices, num_recovered)

Recovers the given nodes with the given number of recovered individuals. Moves individuals from Infected to Recovered compartment.

Parameters:

Name	Type	Description	Default
indices	int | ndarray	The indices of the nodes to recover.	required
num_recovered	int | ndarray	The number of recovered individuals.	required

laser.measles.compartmental.CompartmentalParams

Bases: BaseModelParams

Parameters for the compartmental SEIR model with 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 = CompartmentalParams(num_ticks=365, seed=42)
params = CompartmentalParams(num_ticks=730, seed=0, start_time="2010-01")

laser.measles.compartmental.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.compartmental.load_snapshot(path, params, components=None, verbose=True)

Load a compartmental model from an HDF5 snapshot file and return it ready to run.

Restores the patch SEIR state, scenario, and metadata saved by save_snapshot. Set params.start_time to the snapshot date printed by save_snapshot. Do not include InfectionSeedingProcess in the components list — infections are already encoded in the restored patch states.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the HDF5 snapshot file written by save_snapshot.	required
params	CompartmentalParams	CompartmentalParams 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, minus InfectionSeedingProcess.	None
verbose	bool	Print a loading summary.	True

Returns:

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

Example:

```python
import laser.measles as lm
from laser.measles.compartmental import load_snapshot
from laser.measles.compartmental.components import InfectionProcess

params2 = lm.CompartmentalParams(num_ticks=365, seed=42, start_time="2001-01")
model2 = load_snapshot(
    "checkpoint.h5", params2, components=[InfectionProcess]
)
model2.run()
```

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

Save compartmental model patch state to an HDF5 snapshot file.

Call this after CompartmentalModel.run() to persist the full patch SEIR state. The resulting HDF5 file can be resumed with load_snapshot to continue the simulation from exactly where it left off.

Parameters:

Name	Type	Description	Default
model	CompartmentalModel	A fully-run (or mid-run) CompartmentalModel instance.	required
path	str | Path	Destination HDF5 file path (created or overwritten).	required
verbose	bool	Print a progress summary.	True

Example:

```python
import laser.measles as lm
from laser.measles.compartmental import save_snapshot
from laser.measles.compartmental.components import (
    InfectionSeedingProcess,
    InfectionProcess,
)

params = lm.CompartmentalParams(num_ticks=365, seed=42, start_time="2000-01")
model = lm.CompartmentalModel(scenario, params)
model.components = [InfectionSeedingProcess, InfectionProcess]
model.run()

save_snapshot(model, "checkpoint.h5")
```