laser.measles.components.base_tracker_state

`laser.measles.components.base_tracker_state`

`laser.measles.components.base_tracker_state.BaseStateTracker(model, verbose=False, params=None)`

Bases: BasePhase

Component for tracking the number in each SEIR state for each time tick.

This class maintains a time series of state counts across nodes in the model. The states are dynamically generated as properties based on model.params.states (e.g., "S", "E", "I", "R"). Each state can be accessed as a property that returns a numpy array containing the time series for that state.

The tracking can be done at different aggregation levels: - aggregation_level = -1: Sum over all patches (default, backward compatible) - aggregation_level >= 0: Group by geographic level and track separately

Parameters:

Name	Type	Description	Default
`model`		The simulation model containing nodes, states, and parameters.	required
`verbose`	`bool`	Whether to print verbose output during simulation. Defaults to False.	`False`
`params`	`BaseStateTrackerParams \| None`	Component-specific parameters. If None, will use default parameters.	`None`

`laser.measles.components.base_tracker_state.BaseStateTracker.get_dataframe()`

Get a DataFrame of state counts over time.

Returns:

Type	Description
`DataFrame`	DataFrame with columns: - tick: Time step - state: State name (S, E, I, R, etc.) - patch_id: Patch/group identifier. Matches the `id` column of the scenario DataFrame at the requested `aggregation_level`, or `"all_patches"` when `aggregation_level=-1` (the default). - count: Number of individuals in this state

`laser.measles.components.base_tracker_state.BaseStateTracker.plot(fig=None)`

Plots the time series of SEIR state counts across all nodes using subplots.

This function creates a separate subplot for each state, showing how the number of individuals in each state changes over time. Each state gets its own subplot for better visibility.

Parameters:

Name	Type	Description	Default
`fig`	`Figure`	A matplotlib Figure object. If None, a new figure will be created.	`None`

Yields:

Name	Type	Description
`None`		This function uses a generator to yield control back to the caller.
		If used directly (not as a generator), it will show the plot immediately.

Example

Use as a generator (for model.visualize()):

for _ in tracker.plot(): plt.show()

`laser.measles.components.base_tracker_state.BaseStateTracker.plot_combined(fig=None)`

Plots all SEIR states on a single plot for easy comparison.

Parameters:

Name	Type	Description	Default
`fig`	`Figure`	A matplotlib Figure object. If None, a new figure will be created.	`None`

Yields:

Name	Type	Description
`None`		This function uses a generator to yield control back to the caller.

`laser.measles.components.base_tracker_state.BaseStateTrackerParams`

Bases: BaseModel

Parameters specific to the state tracker component.

Attributes:

Name	Type	Description
`filter_fn`	`Callable[[str], bool]`	Function to filter which nodes to include in aggregation.
`aggregation_level`	`int`	Controls the geographic level at which states are reported. `-1` (default): Sum over all patches; `get_dataframe()` returns a single row per tick/state with `patch_id="all_patches"`. `0`: Aggregate to the top level of the node-ID hierarchy (e.g. `"NG"` from `"NG:KN:LGA"`). `N >= 0`: Keep the first `N+1` colon-separated components of the node ID (e.g. `aggregation_level=1` → `"NG:KN"` from `"NG:KN:LGA"`). To get per-patch data, set `aggregation_level` to the depth of your hierarchy minus one. For flat IDs (no `":"`), `aggregation_level=0` gives per-patch rows. The `patch_id` column in `get_dataframe()` matches the `id` column of the scenario DataFrame at the requested hierarchy level.