highmlr_causal: Causal survival forest for heterogeneous treatment effects...

In highMLR: Machine Learning Feature Selection for High Dimensional Survival Data

Causal survival forest for heterogeneous treatment effects (experimental)

Description

Estimates patient-level conditional average treatment effects (CATEs) on a survival outcome using 'grf::causal_survival_forest'. Unlike the rest of 'highMLR', this function answers a different question: not "which features predict survival?" but "for which patients does treatment T extend (or shorten) survival, and which features modify that effect?".

Usage

highmlr_causal(
  data,
  time,
  status,
  treatment,
  covariates = NULL,
  horizon = NULL,
  num.trees = 2000L,
  target = c("RMST", "survival.probability"),
  honesty = TRUE,
  seed = NULL,
  ...
)

## S3 method for class 'highmlr_causal'
print(x, n = 10, ...)

## S3 method for class 'highmlr_causal'
plot(x, ...)

Arguments

data	A data frame.
time	Character: name of the survival time column.
status	Character: name of the event indicator (0/1).
treatment	Character: name of the binary treatment column (0 = control, 1 = treated). Must be exactly two levels.
covariates	Character vector of covariate column names. If 'NULL', all columns other than 'time', 'status', 'treatment'.
horizon	Numeric. The time horizon at which the treatment effect on the survival probability is estimated. Defaults to the median observed time.
num.trees	Number of trees in the forest (default 2000).
target	One of '"RMST"' (restricted mean survival time difference up to 'horizon') or '"survival.probability"' (difference in survival probability at 'horizon').
honesty	Logical (default TRUE) – honest splitting per 'grf'.
seed	Optional integer seed.
...	Passed to 'grf::causal_survival_forest'.
x	A 'highmlr_causal' object.
n	Number of top covariates to print (default 10).

Value

An object of class 'highmlr_causal' containing the fitted forest, per-patient CATE estimates with standard errors, and covariate importance.

'print()' invisibly returns 'x'; 'plot()' returns a 'ggplot' object showing the distribution of estimated CATEs.

Experimental

This function is marked experimental. The signature, defaults, and return shape may change in a future release. Use with care in published analyses, and report the package version.

Examples

## Not run: 
set.seed(1)
n <- 500; p <- 10
X <- matrix(rnorm(n*p), n, p); colnames(X) <- paste0("V", 1:p)
W <- rbinom(n, 1, 0.5)
t <- rexp(n, rate = exp(0.3*W + 0.5*X[,1]*W))
c <- rexp(n, rate = 0.05)
d <- data.frame(OS = pmin(t,c), Death = as.integer(t<=c),
                arm = W, X)
cf <- highmlr_causal(d, "OS", "Death", treatment = "arm",
                     covariates = paste0("V", 1:p))
print(cf); plot(cf)

## End(Not run)

highMLR documentation built on May 23, 2026, 5:07 p.m.