Survival analysis

Source: R/AllGenerics.R, R/getSurvival.R

Fit a (penalized) Cox proportional hazards model on microbiome data contained in a SummarizedExperiment object. Data transformations (e.g. pairwise log-ratios) should be handled upstream (e.g. with mia::transformAssay()).

getSurvival(x, ...)

addSurvival(x, ...)

# S4 method for class 'SummarizedExperiment'
addSurvival(
  x,
  time.col,
  event.col,
  name = c("survival_coef", "survival_risk_score", "survival"),
  ...
)

# S4 method for class 'SummarizedExperiment'
getSurvival(x, time.col, event.col, assay.type = "counts", col.var = NULL, ...)

Arguments

x

A SummarizedExperiment object.

...

additional arguments.

  • penalized: Logical. If TRUE, fit penalized Cox regression using glmnet. If FALSE, fit standard Cox model using survival::coxph. (Default: TRUE)

  • lambda: Character or numeric. Penalization parameter passed to cv.glmnet. Use "lambda.1se", "lambda.min", or a numeric value. (Default: "lambda.1se")

  • alpha: Numeric scalar. Elastic net mixing parameter that controls the balance between Lasso and Ridge regression: alpha = 1 corresponds to Lasso, alpha = 0 corresponds to Ridge. Values between 0 and 1 specify a combination of the two. (Default: 0.9)

  • nfolds: Integer scalar. Number of cross-validation folds for cv.glmnet. (Default: 10)

  • nvar: Integer scalar. Optional. Maximum number of variables (log-ratios) to include in the model. (Default: NULL)

  • coef.threshold: Numeric scalar. Minimum absolute value for a coefficient to be included in the final model. (Default: 0)

time.col

Character scalar. Column name in colData(x) representing time to event or follow-up time. Must be numeric.

event.col

Character scalar. Column name in colData(x) representing event occurrence. Accepts numeric (0/1) or logical (TRUE/FALSE) values.

name

Character vector of length 3. Names for the coefficients in rowData, the risk scores in colData and the full results in metadata. (Default: c("survival_coef", "survival_risk_score", "survival"))

assay.type

Character scalar. Specifies which assay values are used in the dissimilarity estimation. (Default: "counts")

col.var

Character vector. Optional. Specifies covariate columns in colData(x) to adjust for in the survival model. (Default: NULL)

Value

getSurvival() returns a list with model summaries:

  • coef: estimated model coefficients

  • risk_scores: predicted risk scores

  • c_index: apparent concordance index

  • c_index_cv_mean: mean cross-validated C-index (if penalized)

  • c_index_cv_sd: SD of cross-validated C-index (if penalized)

  • fit: fitted model object (coxph or cv.glmnet)

addSurvival() returns x with the results added.

Details

getSurvival() fits a Cox proportional hazards model with the features of assay.type as predictors. By default (penalized = TRUE), an elastic net penalized model is fitted with glmnet::cv.glmnet(), and the penalty is selected by cross-validation using the concordance index. With penalized = FALSE, a standard model is fitted with survival::coxph().

If col.var is specified, the penalized model first fits the covariates with coxph() and uses their linear predictor as an offset, so that the features are evaluated on top of the covariates. In the standard model, the covariates are included as predictors.

The features are used as they are. Transformations, such as pairwise log-ratios, should be applied beforehand.

Coefficients with absolute value not above coef.threshold are removed, and the remaining coefficients are rescaled so that their absolute values sum to 2, as in log-contrast models (Pujolassos et al. 2024). The rescaled coefficients show the direction and relative weight of each feature, but they are not log hazard ratios. The unscaled coefficients are available from fit. Risk scores and C-index are calculated from the fitted model and are not affected by the rescaling.

addSurvival() adds the coefficients to rowData (NA for features not in the model), the risk scores to colData, and the full results to metadata.

References

Meritxell Pujolassos , Antoni Susín , M.Luz Calle (2024). Microbiome compositional data analysis for survival studies NAR Genomics and Bioinformatics, 6(2), lqae038. doi:10.1093/nargab/lqae038

See also

coda_coxnet, cv.glmnet

Examples

data(crohn_survival)
tse <- crohn_survival
tse <- transformAssay(tse, method = "relabundance")
fit <- getSurvival(
    tse, assay.type = "relabundance",
    time.col = "event_time", event.col = "event"
)
#> Warning: Starting in glmnet 5.1, the default Cox tie-handling method will change from 'breslow' to 'efron' (matching survival::coxph). To silence this message and lock in the v5.0 default, pass cox.ties = 'breslow' explicitly. To preview the v5.1 behavior, pass cox.ties = 'efron'.
#> Warning: Starting in glmnet 5.1, the default Cox tie-handling method will change from 'breslow' to 'efron' (matching survival::coxph). To silence this message and lock in the v5.0 default, pass cox.ties = 'breslow' explicitly. To preview the v5.1 behavior, pass cox.ties = 'efron'.
#> Warning: Starting in glmnet 5.1, the default Cox tie-handling method will change from 'breslow' to 'efron' (matching survival::coxph). To silence this message and lock in the v5.0 default, pass cox.ties = 'breslow' explicitly. To preview the v5.1 behavior, pass cox.ties = 'efron'.
#> Warning: Starting in glmnet 5.1, the default Cox tie-handling method will change from 'breslow' to 'efron' (matching survival::coxph). To silence this message and lock in the v5.0 default, pass cox.ties = 'breslow' explicitly. To preview the v5.1 behavior, pass cox.ties = 'efron'.
#> Warning: Starting in glmnet 5.1, the default Cox tie-handling method will change from 'breslow' to 'efron' (matching survival::coxph). To silence this message and lock in the v5.0 default, pass cox.ties = 'breslow' explicitly. To preview the v5.1 behavior, pass cox.ties = 'efron'.
#> Warning: Starting in glmnet 5.1, the default Cox tie-handling method will change from 'breslow' to 'efron' (matching survival::coxph). To silence this message and lock in the v5.0 default, pass cox.ties = 'breslow' explicitly. To preview the v5.1 behavior, pass cox.ties = 'efron'.
#> Warning: Starting in glmnet 5.1, the default Cox tie-handling method will change from 'breslow' to 'efron' (matching survival::coxph). To silence this message and lock in the v5.0 default, pass cox.ties = 'breslow' explicitly. To preview the v5.1 behavior, pass cox.ties = 'efron'.
#> Warning: Starting in glmnet 5.1, the default Cox tie-handling method will change from 'breslow' to 'efron' (matching survival::coxph). To silence this message and lock in the v5.0 default, pass cox.ties = 'breslow' explicitly. To preview the v5.1 behavior, pass cox.ties = 'efron'.
#> Warning: Starting in glmnet 5.1, the default Cox tie-handling method will change from 'breslow' to 'efron' (matching survival::coxph). To silence this message and lock in the v5.0 default, pass cox.ties = 'breslow' explicitly. To preview the v5.1 behavior, pass cox.ties = 'efron'.
#> Warning: Starting in glmnet 5.1, the default Cox tie-handling method will change from 'breslow' to 'efron' (matching survival::coxph). To silence this message and lock in the v5.0 default, pass cox.ties = 'breslow' explicitly. To preview the v5.1 behavior, pass cox.ties = 'efron'.
#> Warning: Starting in glmnet 5.1, the default Cox tie-handling method will change from 'breslow' to 'efron' (matching survival::coxph). To silence this message and lock in the v5.0 default, pass cox.ties = 'breslow' explicitly. To preview the v5.1 behavior, pass cox.ties = 'efron'.