predict.rfmstate: Predict Entry-Conditioned State Probabilities

In RFmstate: Random Forest-Based Multistate Survival Analysis

Predict Entry-Conditioned State Probabilities

Description

Predicts clock-reset semi-Markov state-occupation probabilities conditional on fresh entry into a selected state at elapsed duration zero.

Usage

## S3 method for class 'rfmstate'
predict(
  object,
  newdata = NULL,
  times = NULL,
  s = 0,
  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,
  extrapolate = c("error", "flat"),
  ...
)

Arguments

object	A fitted rfmstate model.
newdata	Prediction profiles. NULL uses training profiles and labels the result apparent/training.
times	Finite nonnegative elapsed durations. NULL uses fitted edge event times that fall within the conservative support horizon.
s	Legacy start-time argument; only zero is supported.
start_state	Fresh-entry starting state. Defaults to the common initial state.
grid_step	Optional positive initial internal grid step.
target_grid_points	Initial regular-grid interval count when grid_step is NULL.
max_grid_points	Maximum allowed internal grid-point count.
grid_tol	Maximum change permitted between successive refinements.
max_grid_refinements	Maximum number of grid-step halvings.
check_grid	Whether convergence is required. Keep TRUE for inferential or reported work.
extrapolate	"error" (default) or explicit "flat" cumulative-hazard sensitivity extension.
...	Ignored; no ranger arguments are accepted during prediction.

Details

These are not general Markov P(s,t) matrices. Predictions do not condition on an already elapsed sojourn and carry no confidence bands. By default the horizon cannot exceed the minimum observed sojourn support among reachable transient states.

Value

An rfmstate_pred object. entry_prob and the temporary alias P have dimensions profile by selected starting state by occupied state by elapsed time; the starting-state dimension has length one. state_occ is that selected starting-state slice. The object also contains requested time, per-profile edge cum_hazard, validated newdata, used columns, support and extrapolation metadata, grid-convergence records, conditioning statement, predictor-support extrapolation records, fit-specific schema identifier, state structure, and package versions.

Limitations

Prediction is conditional on fresh entry into start_state at elapsed duration zero. General P(s,t) prediction for s > 0, left truncation, ongoing-sojourn/landmark prediction, recurrent histories, and confidence intervals are unavailable. Missing covariates, nonfinite numeric values, incompatible classes, and unseen factor levels are rejected. Numeric values outside the fit-specific range warn and are recorded as predictor-support extrapolation; they are never truncated. Times beyond support fail unless extrapolate = "flat"; that option assumes zero additional hazard and is a sensitivity analysis only.

Examples

ms <- clinical_states()
dat <- sim_clinical_data(300, structure = ms, seed = 42)
long <- prepare_data(
  dat, "ID", ms,
  list(Responded="time_Responded", Unresponded="time_Unresponded",
       Stabilized="time_Stabilized", Progressed="time_Progressed",
       Death="time_Death"),
  "time_censored", c("age", "sex", "BMI", "treatment")
)
fit <- rfmstate(long, num.trees = 100, min_events = 3, seed = 42)
horizon <- min(fit$max_duration_by_origin)
predict(fit, data.frame(age=60, sex=1, BMI=26, treatment=1),
        times = c(0, horizon / 2))

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