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.

Example:

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

scenario = single_patch_scenario(population=100_000, mcv1_coverage=0.85)
# scenario is a Polars DataFrame with columns: id, pop, lat, lon, mcv1
```

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

Bases: BaseLaserModel

Population-level SEIR model for measles transmission with daily timesteps.

Tracks compartment counts (S, E, I, R) per patch using deterministic difference equations. This model is the fastest option for calibrating transmission parameters to surveillance data because it avoids stochastic noise. For individual-level tracking, see ABMModel; for 14-day timesteps, see BiweeklyModel.

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 | BaseCompartmentalScenario	Metapopulation patch data. Required columns: id (str), pop (int), lat (Float64), lon (Float64), mcv1 (Float64). A plain polars.DataFrame is automatically wrapped.	required
params	CompartmentalParams	Simulation parameters including num_ticks, seed, and start_time.	required
name	str	Display name for log messages. Defaults to "compartmental".	'compartmental'

Example:

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

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

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.

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 = CompartmentalParams(num_ticks=365, seed=42, start_time="2000-01")
```

laser.measles.compartmental.CompartmentalParams.states property

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

laser.measles.compartmental.CompartmentalParams.time_step_days property

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

laser.measles.compartmental.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.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")
```