state_occupancy

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

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
interventions	Sequence[str]	Every intervention actually run, in output order. An intervention in which nobody moves during a whole iteration leaves no rows in events at all, so it cannot be recovered from the log; naming it here is what keeps it in the result.	required
iterations	Sequence[Any]	Every iteration actually run, e.g. the index of the parameter draws passed to run_psa. An iteration in which nobody moves leaves no rows in events either; naming it here is what keeps it in the result, entirely in initial_state at every requested time.	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. Covers every pair
	pd.DataFrame	formed by crossing interventions with iterations, plus any
	pd.DataFrame	additional pair already present in events. A pair with no
	pd.DataFrame	event rows of its own occupies initial_state at every
	pd.DataFrame	requested time.

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], … interventions=[“care”], iterations=[0, 1]) float(occ.loc[(“care”, 0, 2.5), “H”]) 0.5

Iteration 1 has no rows in events, since nobody moved under it, so it occupies initial_state at every requested time:

occ.loc[(“care”, 1, 2.5)].tolist() [1.0, 0.0, 0.0]