state_occupancy

models.state_occupancy(events, *, states, initial_state, n_individuals, times)

Proportion of individuals in each state at each time.

Counts, for every requested time, how many individuals occupy each state: everyone starts in initial_state, each event row moves one individual at its time, and an event at exactly a requested time counts as having happened. Individuals appear in the log only when they move, so the initial state and the population size are explicit arguments rather than read from the log.

Survival is one minus the dead-state column, and prevalence among the alive is the summed disease-state columns divided by that survival, both one-line derivations of this table.

Parameters

Name	Type	Description	Default
events	pd.DataFrame	Event history with columns intervention, iteration, individual, time, from_state, to_state, as returned by evaluate(draws, trace="events").	required
states	Sequence[str]	Every state label, in the order the columns should take.	required
initial_state	str	State every individual occupies at time zero.	required
n_individuals	int	Number of simulated individuals per intervention and iteration.	required
times	ArrayLike	Times at which to evaluate occupancy.	required

Returns

Name	Type	Description
	pd.DataFrame	DataFrame indexed by (intervention, iteration, time) with one
	pd.DataFrame	proportion column per state; rows sum to 1.

Example

import pandas as pd from heormodel.models import state_occupancy events = pd.DataFrame({ … “intervention”: “care”, “iteration”: 0, “individual”: [0, 0, 1], … “time”: [1.0, 3.0, 2.0], “from_state”: [“H”, “S”, “H”], … “to_state”: [“S”, “D”, “D”]}) occ = state_occupancy(events, states=(“H”, “S”, “D”), … initial_state=“H”, n_individuals=4, times=[0.0, 2.5]) float(occ.loc[(“care”, 0, 2.5), “H”]) 0.5