MarkovModel

models.MarkovModel(
    states,
    interventions,
    transitions_and_rewards,
    n_cycles,
    initial_state=None,
    cycle_length=1.0,
    discount_rate=0.03,
    cycle_correction='simpson',
    effect='qaly',
)

Cohort state-transition model engine.

discount_rate is an annual rate on an annual clock. cycle_length scales the clock: with cycle_length=0.5 each cycle discounts by half a year.

Parameters

Name	Type	Description	Default
states	Sequence[str]	State labels; their order fixes every array’s axis order.	required
interventions	InterventionSpec	A sequence of intervention names or heormodel.models.Intervention objects, in the order they appear in Outcomes. A Intervention may carry parameter decision levers merged into params for that intervention.	required
transitions_and_rewards	Callable[[pd.Series, str], CohortSpec]	fn(params, intervention) -> CohortSpec returning the transition matrix and reward arrays for one intervention under one parameter set. params is a draw-matrix row (a pandas.Series); intervention is the intervention name.	required
n_cycles	int	Number of cycles in the time horizon.	required
initial_state	str | Mapping[str, float] | Sequence[float] | None	Initial state distribution: a state label (all mass there), a mapping of state label to probability, or a length-n_states array. Defaults to all mass in the first state.	None
cycle_length	float	Years per cycle; scales the discount clock.	1.0
discount_rate	float	Annual discount rate for costs and effects (0.03 by default).	0.03
cycle_correction	str	"simpson" (default), "half_cycle", or "none"; see gen_wcc.	'simpson'
effect	str	Name of the primary effect column (QALYs by default).	'qaly'

Example

import numpy as np, pandas as pd from heormodel.models.markov import CohortSpec, MarkovModel def transitions_and_rewards(params, intervention): … p_die = params[“p_die”] … transition = np.array([[1 - p_die, p_die], [0.0, 1.0]]) … return CohortSpec(transition, np.array([params[“cost”], 0.0]), … np.array([1.0, 0.0])) engine = MarkovModel( … states=(“alive”, “dead”), interventions=(“care”,), … transitions_and_rewards=transitions_and_rewards, … n_cycles=10, cycle_correction=“none”) draws = pd.DataFrame({“p_die”: [0.1], “cost”: [1000.0]}, … index=pd.RangeIndex(1, name=“iteration”)) engine.evaluate(draws).interventions [‘care’]

Methods

Name	Description
trace	Cohort occupancy over the horizon for one parameter set.

trace

models.MarkovModel.trace(params, intervention)

Cohort occupancy over the horizon for one parameter set.

A convenience for inspection and plotting (a cohort trace, a survival curve) and for validation against a hand computation; it is not part of the engine contract and does not accrue costs or effects. evaluate is what produces Outcomes. The intervention’s decision levers are applied exactly as evaluate applies them, so the trace reflects the arm. It parallels heormodel.models.ODEModel.trajectory for the cohort engine.

Parameters

Name	Type	Description	Default
params	pd.Series	One draw-matrix row (a pandas.Series) of parameter values.	required
intervention	str	The intervention name passed to transitions_and_rewards.	required

Returns

Name	Type	Description
	pd.DataFrame	A DataFrame with an integer cycle column (0 to
	pd.DataFrame	n_cycles) and one occupancy column per state, in state order.

Example

import numpy as np, pandas as pd from heormodel.models.markov import CohortSpec, MarkovModel def transitions_and_rewards(params, intervention): … p_die = params[“p_die”] … transition = np.array([[1 - p_die, p_die], [0.0, 1.0]]) … return CohortSpec(transition, np.array([params[“cost”], 0.0]), … np.array([1.0, 0.0])) engine = MarkovModel( … states=(“alive”, “dead”), interventions=(“care”,), … transitions_and_rewards=transitions_and_rewards, n_cycles=3) trace = engine.trace(pd.Series({“p_die”: 0.1, “cost”: 1000.0}), “care”) [round(float(x), 3) for x in trace[“alive”]] [1.0, 0.9, 0.81, 0.729]