compute_trans_prob: Entry-Conditioned Semi-Markov State Probabilities

In RFmstate: Random Forest-Based Multistate Survival Analysis

Entry-Conditioned Semi-Markov State Probabilities

Description

Combines one clock-reset cumulative cause-specific hazard curve per allowed edge using a regular-grid entry-mass/sojourn convolution. The result is not a general Markov P(s,t) matrix: each row is conditional on fresh entry into its named starting state at elapsed duration zero.

Usage

compute_trans_prob(
  cum_hazards,
  structure,
  s = 0,
  times = NULL,
  start_state = NULL,
  grid_step = NULL,
  target_grid_points = 1024L,
  max_grid_points = 131073L,
  grid_tol = 5e-04,
  max_grid_refinements = 7L,
  check_grid = TRUE,
  prob_tol = 1e-08,
  extrapolate = c("error", "flat")
)

Arguments

cum_hazards	Named list of data frames, one for every allowed edge. Names must be "from->to"; each frame contains sortable time and nondecreasing hazard (or cum_hazard). Duplicate times retain their last supplied value. An explicit duration zero must have cumulative hazard zero within tolerance; when the first supplied time is positive, (0, 0) is prepended.
structure	An mstate_structure object.
s	Legacy starting-time argument. Only zero is supported.
times	Finite nonnegative elapsed durations. If NULL, the union of input curve times is used.
start_state	State in which fresh entry occurs. The default is the common initial state stored in structure.
grid_step	Optional initial internal grid step.
target_grid_points	Initial number of regular-grid intervals when grid_step is not supplied.
max_grid_points	Maximum number of internal grid points, including elapsed duration zero.
grid_tol	Maximum probability change allowed on grid refinement. The default 5e-4 reflects discontinuous ranger hazard curves; analytic tests retain their separate 1e-3 truth-error gate.
max_grid_refinements	Maximum number of step halvings.
check_grid	Whether to require grid-refinement convergence. Keep TRUE for reported analyses. It must be one nonmissing logical; FALSE warns and records an unchecked result.
prob_tol	Positive tolerance for probability bounds and unit mass.
extrapolate	Either "error" (default) or explicit "flat" cumulative-hazard extension.

Details

Cumulative hazards are evaluated as right-continuous step functions. Within each regular interval, total exit probability is allocated to causes in proportion to their cumulative-hazard increments. Entry mass is assigned to the interval's right endpoint. Grid refinement controls these approximations. A positive cumulative hazard at duration zero is rejected because the data contract permits no instantaneous fresh-entry transition. Tiny monotonicity corrections within the declared tolerance are counted. Probabilities are never clipped or row-normalized.

Value

A trans_prob object. entry_prob and its temporary alias P are arrays ordered selected starting state by occupied state by elapsed time; the starting-state dimension has length one. state_occ is the selected starting-state slice. The object also records time, structure, fresh-entry conditioning, support and extrapolation policy, the final internal grid and step, convergence error/refinements, roundoff corrections, and prob_tol.

Limitations

Curves must cover every declared edge and represent cumulative cause-specific hazards on the clock-reset duration scale. The function does not estimate hazards, accept left truncation or s > 0, condition on an ongoing sojourn, support cyclic/recurrent graphs, or provide uncertainty. Prediction beyond conservative support fails unless the explicit flat-hazard sensitivity extension is selected.

Examples

ms <- define_multistate(c("A", "B"), "B", list(A = "B"))
tt <- seq(0, 2, length.out = 2001)
hazards <- list("A->B" = data.frame(time = tt, hazard = 0.4 * tt))
pr <- compute_trans_prob(hazards, ms, times = c(0, 1, 2),
                         target_grid_points = 512)
pr$state_occ

RFmstate documentation built on Sept. 10, 2026, 1:09 a.m.