to_transition_matrix

survival.to_transition_matrix(curves, *, n_cycles, cycle_length=1.0)

Per-cycle transition array from one or more cause-specific survival curves.

With one curve, builds a two-state (alive, dead) array whose per-cycle death probability is 1 - survival(t + cycle_length) / survival(t), ready for heormodel.models.CohortSpec.transition.

With several curves, treats each as a cause-specific hazard out of one shared alive state and builds a (1 + len(curves))-state array: state 0 is alive, state 1 + k is dead from cause k, absorbing. Within a cycle, the total event probability is split across causes in proportion to each cause’s cumulative hazard increment over that cycle, 1 - exp(-total hazard increment) overall. This construction is exact when every curve’s hazard is constant within a cycle (an all-exponential competing-risks model), the standard result that the chance of cause k occurring first is proportional to its share of the total hazard.

Parameters

Name	Type	Description	Default
curves	SurvivalCurve | Sequence[SurvivalCurve]	One SurvivalCurve, or a sequence of curves for competing risks out of the same starting state.	required
n_cycles	int	Number of cycles in the model horizon.	required
cycle_length	float	Years per cycle.	1.0

Returns

Name	Type	Description
	NDArray[np.float64]	Transition array, shape (n_cycles, n_states, n_states), each row
	NDArray[np.float64]	summing to 1.

Example

from heormodel.survival import to_transition_matrix, weibull curve = weibull(shape=1.2, scale=6.0) transition = to_transition_matrix(curve, n_cycles=5) [round(float(p), 5) for p in transition[:, 0, 1]] [0.10994, 0.14025, 0.15439, 0.16428, 0.17201]