cv.splsdrcox_dynamic {Coxmos}

Cross validation sPLS-DRCOX

Description

The function cv.splsdrcox_dynamic conducts a cross-validation for the sPLS-DRCOX model, which is a specialized model tailored for survival analysis. The function aims to optimize the model's performance by determining the best number of PLS components and variables through cross-validation.

Usage

cv.splsdrcox_dynamic(
  X,
  Y,
  max.ncomp = 8,
  vector = NULL,
  n_run = 3,
  k_folds = 10,
  x.center = TRUE,
  x.scale = FALSE,
  remove_near_zero_variance = TRUE,
  remove_zero_variance = TRUE,
  toKeep.zv = NULL,
  remove_variance_at_fold_level = FALSE,
  remove_non_significant_models = FALSE,
  remove_non_significant = FALSE,
  alpha = 0.05,
  MIN_NVAR = 10,
  MAX_NVAR = 1000,
  n.cut_points = 5,
  MIN_AUC_INCREASE = 0.01,
  EVAL_METHOD = "AUC",
  w_AIC = 0,
  w_c.index = 0,
  w_AUC = 1,
  w_BRIER = 0,
  times = NULL,
  max_time_points = 15,
  MIN_AUC = 0.8,
  MIN_COMP_TO_CHECK = 3,
  pred.attr = "mean",
  pred.method = "cenROC",
  fast_mode = FALSE,
  max.iter = 200,
  MIN_EPV = 5,
  return_models = FALSE,
  returnData = FALSE,
  PARALLEL = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

X

Numeric matrix or data.frame. Explanatory variables. Qualitative variables must be transform into binary variables.

Y

Numeric matrix or data.frame. Response variables. Object must have two columns named as "time" and "event". For event column, accepted values are: 0/1 or FALSE/TRUE for censored and event observations.

max.ncomp

Numeric. Maximum number of PLS components to compute for the cross validation (default: 8).

vector

Numeric vector. Used for computing best number of variables. As many values as components have to be provided. If vector = NULL, an automatic detection is perform (default: NULL).

n_run

Numeric. Number of runs for cross validation (default: 3).

k_folds

Numeric. Number of folds for cross validation (default: 10).

x.center

Logical. If x.center = TRUE, X matrix is centered to zero means (default: TRUE).

x.scale

Logical. If x.scale = TRUE, X matrix is scaled to unit variances (default: FALSE).

remove_near_zero_variance

Logical. If remove_near_zero_variance = TRUE, near zero variance variables will be removed (default: TRUE).

remove_zero_variance

Logical. If remove_zero_variance = TRUE, zero variance variables will be removed (default: TRUE).

toKeep.zv

Character vector. Name of variables in X to not be deleted by (near) zero variance filtering (default: NULL).

remove_variance_at_fold_level

Logical. If remove_variance_at_fold_level = TRUE, (near) zero variance will be removed at fold level (default: FALSE).

remove_non_significant_models

Logical. If remove_non_significant_models = TRUE, non-significant models are removed before computing the evaluation. A non-significant model is a model with at least one component/variable with a P-Value higher than the alpha cutoff.

remove_non_significant

Logical. If remove_non_significant = TRUE, non-significant variables/components in final cox model will be removed until all variables are significant by forward selection (default: FALSE).

alpha

Numeric. Numerical values are regarded as significant if they fall below the threshold (default: 0.05).

MIN_NVAR

Numeric. Minimum range size for computing cut points to select the best number of variables to use (default: 10).

MAX_NVAR

Numeric. Maximum range size for computing cut points to select the best number of variables to use (default: 1000).

n.cut_points

Numeric. Number of cut points for searching the optimal number of variables. If only two cut points are selected, minimum and maximum size are used. For MB approaches as many as n.cut_points^n.blocks models will be computed as minimum (default: 5).

MIN_AUC_INCREASE

Numeric. Minimum improvement between different cross validation models to continue evaluating higher values in the multiple tested parameters. If it is not reached for next 'MIN_COMP_TO_CHECK' models and the minimum 'MIN_AUC' value is reached, the evaluation stops (default: 0.01).

EVAL_METHOD

Character. If EVAL_METHOD = "AUC", AUC metric will be use to compute the best number of variables. In other case, c-index metric will be used (default: "AUC").

w_AIC

Numeric. Weight for AIC evaluator. All weights must sum 1 (default: 0).

w_c.index

Numeric. Weight for C-Index evaluator. All weights must sum 1 (default: 0).

w_AUC

Numeric. Weight for AUC evaluator. All weights must sum 1 (default: 1).

w_BRIER

Numeric. Weight for BRIER SCORE evaluator. All weights must sum 1 (default: 0).

times

Numeric vector. Time points where the AUC will be evaluated. If NULL, a maximum of 'max_time_points' points will be selected equally distributed (default: NULL).

max_time_points

Numeric. Maximum number of time points to use for evaluating the model (default: 15).

MIN_AUC

Numeric. Minimum AUC desire to reach cross-validation models. If the minimum is reached, the evaluation could stop if the improvement does not reach an AUC higher than adding the 'MIN_AUC_INCREASE' value (default: 0.8).

MIN_COMP_TO_CHECK

Numeric. Number of penalties/components to evaluate to check if the AUC improves. If for the next 'MIN_COMP_TO_CHECK' the AUC is not better and the 'MIN_AUC' is meet, the evaluation could stop (default: 3).

pred.attr

Character. Way to evaluate the metric selected. Must be one of the following: "mean" or "median" (default: "mean").

pred.method

Character. AUC evaluation algorithm method for evaluate the model performance. Must be one of the following: "risksetROC", "survivalROC", "cenROC", "nsROC", "smoothROCtime_C", "smoothROCtime_I" (default: "cenROC").

fast_mode

Logical. If fast_mode = TRUE, for each run, only one fold is evaluated simultaneously. If fast_mode = FALSE, for each run, all linear predictors are computed for test observations. Once all have their linear predictors, the evaluation is perform across all the observations together (default: FALSE).

max.iter

Numeric. Maximum number of iterations for PLS convergence (default: 200).

MIN_EPV

Numeric. Minimum number of Events Per Variable (EPV) you want reach for the final cox model. Used to restrict the number of variables/components can be computed in final cox models. If the minimum is not meet, the model cannot be computed (default: 5).

return_models

Logical. Return all models computed in cross validation (default: FALSE).

returnData

Logical. Return original and normalized X and Y matrices (default: TRUE).

PARALLEL

Logical. Run the cross validation with multicore option. As many cores as your total cores - 1 will be used. It could lead to higher RAM consumption (default: FALSE).

verbose

Logical. If verbose = TRUE, extra messages could be displayed (default: FALSE).

seed

Number. Seed value for performing runs/folds divisions (default: 123).

Details

The cv.splsdrcox_dynamic function is designed to perform cross-validation for the sPLS-DRCOX model, a specialized model for survival analysis. The function's primary objective is to identify the optimal number of PLS components and variables that yield the best model performance.

The function accepts both numeric matrices and data frames for explanatory (X) and response (Y) variables. It is essential to ensure that qualitative variables in X are transformed into binary format. The response variable Y should have two columns: "time" and "event". The event column should contain binary values, where 0/1 or FALSE/TRUE represent censored and event observations, respectively.

The cross-validation process is controlled by several parameters, including the maximum number of PLS components (max.ncomp), the number of runs (n_run), and the number of folds (k_folds). The function also provides options for data preprocessing, such as centering and scaling of the X matrix, and removal of variables with near-zero or zero variance.

Significance testing is incorporated into the model evaluation process. Users can specify the alpha threshold (alpha) for determining significance. Non-significant models or variables can be optionally removed from the evaluation based on user-defined criteria.

The function also offers flexibility in model evaluation metrics. Users can choose between different metrics such as AUC, AIC, C-Index, and Brier Score. The importance of each metric in the evaluation can be controlled using weights (w_AIC, w_c.index, w_AUC, w_BRIER).

For computational efficiency, the function provides an option to run the cross-validation in parallel (PARALLEL). Additionally, verbose logging can be enabled to display extra messages during the execution.

Value

Instance of class "Coxmos" and model "cv.sPLS-DRCOX-Dynamic". best_model_info: A data.frame with the information for the best model. df_results_folds: A data.frame with fold-level information. df_results_runs: A data.frame with run-level information. df_results_comps: A data.frame with component-level information (for cv.coxEN, EN.alpha information).

lst_models: If return_models = TRUE, return a the list of all cross-validated models. pred.method: AUC evaluation algorithm method for evaluate the model performance.

opt.comp: Optimal component selected by the best_model. opt.nvar: Optimal number of variables selected by the best_model.

plot_AIC: AIC plot by each hyper-parameter. plot_c_index: C-Index plot by each hyper-parameter. plot_BRIER: Brier Score plot by each hyper-parameter. plot_AUC: AUC plot by each hyper-parameter.

class: Cross-Validated model class.

lst_train_indexes: List (of lists) of indexes for the observations used in each run/fold for train the models. lst_test_indexes: List (of lists) of indexes for the observations used in each run/fold for test the models.

time: time consumed for running the cross-validated function.

Author(s)

Pedro Salguero Garcia. Maintainer: [e-mail]

Examples

data("X_proteomic")
data("Y_proteomic")
set.seed(123)
index_train <- caret::createDataPartition(Y_proteomic$event, p = .5, list = FALSE, times = 1)
X_train <- X_proteomic[index_train,1:20]
Y_train <- Y_proteomic[index_train,]
cv.splsdrcox_dynamic_model <- cv.splsdrcox_dynamic(X_train, Y_train, max.ncomp = 1, vector = NULL,
n_run = 1, k_folds = 2, x.center = TRUE, x.scale = TRUE)