rfmstate: Fit Clock-Reset Random-Forest Multistate Models

In RFmstate: Random Forest-Based Multistate Survival Analysis

Fit Clock-Reset Random-Forest Multistate Models

Description

Fits one ranger cause-specific survival forest for every declared edge of a validated acyclic, non-recurrent multistate structure. Forest response time is duration since fresh entry into the origin state.

Usage

rfmstate(
  msdata,
  covariates = NULL,
  num.trees = 1000L,
  mtry = NULL,
  min.node.size = 15L,
  min_events = 5L,
  sparse_warning = 50L,
  importance = "permutation",
  seed = NULL,
  ...
)

Arguments

msdata	An msdata object from prepare_data.
covariates	Predictor names. NULL uses the complete stored predictor contract; an explicit value must be a nonempty unique subset of that contract.
num.trees	Positive integer number of trees fitted for every edge.
mtry	Positive integer number of predictors considered at each split. NULL uses floor(sqrt(p)), bounded below by one.
min.node.size	Positive integer ranger minimum terminal-node size.
min_events	Explicit technical safeguard for target events per edge. It is not a universal adequacy threshold.
sparse_warning	Positive integer descriptive event-count threshold for an edge warning; set Inf to disable. It is not a fit threshold.
importance	One of "permutation", "impurity", "impurity_corrected", or "none". Permutation importance is recommended for interpretation under the limitations below.
seed	NULL or one nonnegative integer seed passed to every edge forest without changing the caller's RNG state.
...	Supported ranger controls: replace, sample.fraction, splitrule, num.random.splits, respect.unordered.factors, num.threads, save.memory, max.depth, always.split.variables, alpha, minprop, and verbose. Unnamed, conflicting, and unknown arguments are rejected. Configurations without genuine OOB observations are rejected.

Details

Every competing exit from an origin state remains an observed exit for that sojourn, but is coded as a non-target outcome in the binary cause-specific forest for a particular edge. An unestimable declared edge stops the whole fit; it is never omitted or represented by zero hazard. The ranger model frame is constructed anew as .rfm_time, .rfm_event, and the contract-approved predictors. Predictor factor levels and numeric ranges are learned from the actual fitting rows, not copied from a preparation-time or full-data schema.

Value

An rfmstate object containing models for every declared edge; structure; selected covariates and predictor_schema; origin-state fitting data; backend event-time grids; per-edge event, support, ranger-argument, and genuine OOB metadata; the validated msdata; fit params; package versions; verified OOB coverage; and the clock-reset semi-Markov time-scale contract.

Ranger argument contract

RFmstate controls and rejects duplicate specification of formula, data, num.trees, mtry, min.node.size, importance, seed, write.forest, oob.error, and keep.inbag. Unnamed and unknown arguments also fail. The only names accepted through ... are:

replace, sample.fraction

Bootstrap/subsampling controls.

splitrule, num.random.splits, alpha, minprop

Survival split controls supported by the installed ranger version.

respect.unordered.factors

Unordered-factor handling.

num.threads, save.memory, verbose

Computation controls.

max.depth

Maximum tree depth.

always.split.variables

Predictors always considered for splitting.

These arguments retain ranger's definitions and are checked against the installed ranger formal arguments before fitting. case.weights, class.weights, split.select.weights, response controls, and every other unlisted ranger argument are rejected in this release. Effective sampling defaults are resolved and stored. In particular, replace = FALSE, sample.fraction = 1 is rejected because it leaves no OOB observations. RFmstate forces oob.error = TRUE and keep.inbag = TRUE, verifies finite ranger OOB error after every edge fit, and stores per-sojourn OOB-tree coverage.

Limitations

The fit supports baseline, time-fixed, complete covariates in single-root acyclic non-recurrent data. It does not support left truncation, time-dependent covariates, recurrent visits/cycles, missing fitting covariates, subject-specific frailty, clock-forward hazards, or confidence intervals. Structural, outcome-time, censoring, ID, and arbitrary long-format columns cannot be added as predictors. Every declared edge must meet min_events; this technical safeguard is not a universal adequacy threshold.

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)

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