Package {highMLR}

highMLR: Machine Learning Feature Selection for High Dimensional Survival Data

Description

A unified, flexible framework for high dimensional feature selection in the presence of a survival outcome. Provides multiple machine learning approaches under a single interface: Cox elastic net, random survival forest, accelerated oblique RSF, gradient-boosted Cox, stability selection, classical univariate Cox screening, pseudo-observation bridging to any regression learner, and Fine-Gray competing risks selection. Adds causal survival forest estimation of heterogeneous treatment effects, conformal survival prediction intervals, and time-dependent SHAP explanations via SurvSHAP(t).

Main functions

[highmlr()]

Main entry point. Fit one of eight ML methods.

[highmlr_compare()]

Compare multiple methods side by side.

[highmlr_stability()]

Stability selection wrapper.

[highmlr_explain()]

Time-dependent SHAP via SurvSHAP(t).

[highmlr_screen()]

Pre-screening for very high p.

[highmlr_report()]

Generate a Quarto/Rmd report.

[highmlr_causal()]

Causal survival forest (experimental).

[highmlr_conformal()]

Conformal prediction intervals.

Bundled datasets

[hnscc]

High dimensional head and neck cancer survival data.

[srdata]

High dimensional protein gene expression data.

Author(s)

Atanu Bhattacharjee atanustat@gmail.com

Coefficients from a highmlr_fit

Description

Coefficients from a highmlr_fit

Usage

## S3 method for class 'highmlr_fit'
coef(object, ...)

Arguments

Value

A named numeric vector of coefficients (where defined) or importance scores otherwise.

Machine learning feature selection for high dimensional survival data

Description

Fits one of several survival ML methods and returns a unified 'highmlr_fit' object summarising the selected features, their importance/coefficients, and (optionally) out-of-sample performance.

Usage

highmlr(
  data,
  time,
  status,
  features = NULL,
  method = c("coxnet", "rsf", "aorsf", "xgboost", "stability", "univariate", "pseudo",
    "finegray"),
  engine = NULL,
  recipe = NULL,
  resampling = c("cv", "bootstrap", "holdout", "none"),
  folds = 5L,
  tune = FALSE,
  top_n = 50L,
  parallel = FALSE,
  seed = NULL,
  ...
)

Arguments

Value

An object of class 'highmlr_fit'. See [new_highmlr_fit()].

Examples

if (requireNamespace("glmnet", quietly = TRUE)) {
  data(hnscc)
  fit <- highmlr(hnscc, time = "OS", status = "Death",
                 method = "coxnet", resampling = "cv", folds = 5)
  print(fit)
}

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

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)

Compare multiple highMLR methods on the same data

Description

Runs several methods and returns a side-by-side comparison of selected features and performance.

Usage

highmlr_compare(
  data,
  time,
  status,
  features = NULL,
  methods = c("coxnet", "rsf", "univariate"),
  ...
)

Arguments

Value

A list with two elements: 'fits' (named list of 'highmlr_fit' objects) and 'summary' (a tibble of method, n_selected, key metric).

Examples

## Not run: 
data(hnscc)
cmp <- highmlr_compare(hnscc, "OS", "Death",
                       methods = c("coxnet", "rsf", "univariate"))
cmp$summary

## End(Not run)

Conformal prediction intervals for survival times

Description

Computes calibrated lower bounds on survival time for each new subject using a split-conformal procedure with inverse probability of censoring weights (Candes, Lei and Ren, 2023). The returned lower bound satisfies a marginal coverage guarantee approximately equal to one minus alpha under standard conformal assumptions and a consistent censoring model.

Usage

highmlr_conformal(
  fit,
  new_data,
  calibration_data = NULL,
  alpha = 0.1,
  calibration_split = 0.3,
  time = NULL,
  status = NULL,
  seed = NULL
)

Arguments

Value

An object of class highmlr_conformal containing per-subject point predictions and lower confidence bounds for survival time.

Examples

## Not run: 
fit  <- highmlr(d_train, "OS", "Death", method = "coxnet")
intv <- highmlr_conformal(fit, new_data = d_test, alpha = 0.1)
print(intv)
plot(intv)

## End(Not run)

Time-dependent SHAP explanations for a highmlr_fit (SurvSHAP(t))

Description

Computes SurvSHAP(t) attributions (Krzyzinski et al., 2023) – SHAP values that vary with follow-up time – for the top features in a fitted 'highmlr_fit'. Returns the survex explainer, per-feature aggregated importance, and a plotting helper.

Usage

highmlr_explain(
  fit,
  new_data = NULL,
  top_n = 10L,
  times = NULL,
  method = c("survshap", "permutation", "break_down"),
  n_explain = 25L,
  seed = NULL,
  ...
)

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

## S3 method for class 'highmlr_explain'
plot(x, top_n = 10, ...)

Arguments

Value

A list with class 'highmlr_explain' containing: * 'explainer' – the 'survex' explainer object * 'survshap' – the time-dependent SHAP object (if applicable) * 'top_features' – the top features table from the fit * 'aggregated' – tibble of mean absolute SHAP per feature, averaged across time and explained rows

Generate a Quarto/Rmd report skeleton for a highmlr_fit

Description

Writes a self-contained Rmd file that, when rendered, produces a standard biomarker report (selected features, hazard ratios where available, performance, forest plot).

Usage

highmlr_report(fit, file = "highmlr_report.Rmd", render = FALSE)

Arguments

Value

Invisibly, the path to the written file.

Pre-screen features when p is very large

Description

Lightweight filter before the main pipeline (e.g. to drop features with low variance or low marginal association).

Usage

highmlr_screen(
  data,
  time,
  status,
  features = NULL,
  filter = c("variance", "univariate_p", "none"),
  keep = 1000L
)

Arguments

Value

Character vector of retained feature names.

Examples

## Not run: 
data(srdata)
keep <- highmlr_screen(srdata, "OS", "event",
                       filter = "variance", keep = 500)
fit <- highmlr(srdata, "OS", "event", features = keep, method = "coxnet")

## End(Not run)

Post-hoc stability analysis of a fitted highmlr_fit

Description

Runs stability selection on the data used in 'fit', returning a selection frequency per feature.

Usage

highmlr_stability(fit, B = 100L, cutoff = 0.75, PFER = 1, ...)

Arguments

Value

A new 'highmlr_fit' with 'method = "stability"'.

High dimensional head and neck cancer survival and gene expression data

Description

Survival and gene expression measurements for head and neck squamous cell carcinoma patients, used to demonstrate high-dimensional feature selection.

Usage

hnscc

Format

A data frame with 565 rows (one per patient) and 104 columns. The first five columns are the identifier and outcome variables: ID (patient identifier), Death (overall survival event indicator, 1 = death, 0 = censored), OS (overall survival time), PFS (progression-free survival time), and Prog (progression event indicator, 1 = progression, 0 = none). The remaining 99 columns are numeric gene expression features named by gene symbol (for example GJB1, HPN, PROM1).

Source

Bundled with the package since highMLR v0.1.1.

Constructor for highmlr_fit objects

Description

Internal constructor. Not exported. Use [highmlr()] to create fits.

Usage

new_highmlr_fit(
  selected,
  performance = NULL,
  model = NULL,
  method = NA_character_,
  call = NULL,
  data_summary = list(),
  meta = list()
)

Arguments

Value

An object of class 'highmlr_fit'.

Plot method for highmlr_conformal objects

Description

Plot method for highmlr_conformal objects

Usage

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

Arguments

Value

A ggplot object.

Forest / importance plot for a highmlr_fit

Description

Forest / importance plot for a highmlr_fit

Usage

## S3 method for class 'highmlr_fit'
plot(x, top_n = 20, ...)

Arguments

Value

A 'ggplot' object.

Predict from a highmlr_fit

Description

Predict from a highmlr_fit

Usage

## S3 method for class 'highmlr_fit'
predict(object, new_data, type = c("linear_pred", "survival", "risk"), ...)

Arguments

Value

Predicted values (vector or tibble depending on 'type').

Print method for highmlr_conformal objects

Description

Print method for highmlr_conformal objects

Usage

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

Arguments

Value

Invisibly returns x.

Print method for highmlr_fit

Description

Print method for highmlr_fit

Usage

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

Arguments

Value

Invisibly returns 'x'.

High dimensional protein gene expression survival data

Description

Protein expression measurements with a survival outcome, used to demonstrate high-dimensional feature selection.

Usage

srdata

Format

A data frame with 288 rows and 250 columns. The first four columns are the identifier and outcome variables: ID (subject identifier), Visit (visit number), OS (overall survival time), and event (survival event indicator, 1 = event, 0 = censored). The remaining 246 columns are numeric protein expression features named by protein or marker (for example C6kine, ActivinA, Adiponectin).

Source

Bundled with the package since highMLR v0.1.1.

Summary method for highmlr_fit

Description

Summary method for highmlr_fit

Usage

## S3 method for class 'highmlr_fit'
summary(object, ...)

Arguments

Value

A list with the full selected feature table and performance.