cv.coxkl: Cross-Validated Selection of Integration Parameter ('eta')...

In survkl: Estimate Survival Data with Data Integration

Cross-Validated Selection of Integration Parameter (eta) for the Cox–KL Model

Description

Performs K-fold cross-validation to select the integration parameter eta for the Cox–KL model. Each fold fits the model on a training split and evaluates on the held-out split using the specified performance criterion.

Usage

cv.coxkl(
  z,
  delta,
  time,
  stratum = NULL,
  RS = NULL,
  beta = NULL,
  etas = NULL,
  tol = 1e-04,
  Mstop = 100,
  backtrack = FALSE,
  nfolds = 5,
  criteria = c("V&VH", "LinPred", "CIndex_pooled", "CIndex_foldaverage"),
  c_index_stratum = NULL,
  message = FALSE,
  seed = NULL,
  ...
)

Arguments

z	Numeric matrix of covariates (rows = observations, columns = variables).
delta	Numeric vector of event indicators (1 = event, 0 = censored).
time	Numeric vector of observed event or censoring times.
stratum	Optional numeric or factor vector defining strata. If NULL, all observations are treated as a single stratum.
RS	Optional numeric vector or matrix of external risk scores. If omitted, beta must be supplied.
beta	Optional numeric vector of external coefficients. If omitted, RS must be supplied.
etas	Numeric vector of candidate tuning values to be cross-validated. (required). Values are internally sorted in ascending order.
tol	Convergence tolerance for the optimizer used inside coxkl. Default 1e-4.
Mstop	Maximum number of Newton iterations used inside coxkl. Default 100.
backtrack	Logical; if TRUE, backtracking line search is applied during optimization. Default is FALSE.
nfolds	Number of cross-validation folds. Default 5.
criteria	Character string specifying the performance criterion. Choices are "V&VH" (default), "LinPred", "CIndex_pooled", or "CIndex_foldaverage".
c_index_stratum	Optional stratum vector. Only required when criteria is set to "CIndex_pooled" or "CIndex_foldaverage", and a stratified C-index is desired while the fitted model is non-stratified. Default NULL.
message	Logical; if TRUE, prints progress messages and per-fold progress bars. Default FALSE.
seed	Optional integer seed for reproducible fold assignment. Default NULL.
...	Additional arguments passed to coxkl.

Details

External information is required: supply either RS or beta (if beta is given, RS is computed as z %*% beta). Folds are created with stratification by stratum and censoring status. Within each fold and each candidate eta, the function fits coxkl on the training split with warm-starts initialized to zero and evaluates on the test split:

• "V&VH": uses the difference of partial log-likelihoods between full and training fits; reported as -2 times the aggregated quantity.

• "LinPred": aggregates the test-split linear predictors across folds and evaluates -2 times the partial log-likelihood on the full data.

• "CIndex_pooled": pools pairwise comparable counts across folds (numerator/denominator).

• "CIndex_foldaverage": averages the per-fold stratified C-index.

The function also computes an external baseline statistic from RS using the same criterion for comparison.

Value

An object of class "cv.coxkl" with components:

internal_stat

A data.frame with one row per eta containing eta and the cross-validated measure named according to criteria (one of VVH_Loss, LinPred_Loss, CIndex_pooled, CIndex_foldaverage).

external_stat

Scalar baseline statistic computed from RS under the same criteria.

criteria

The evaluation criterion used.

nfolds

Number of folds.

Examples

data(ExampleData_lowdim)

train_dat_lowdim <- ExampleData_lowdim$train
beta_external_good_lowdim <- ExampleData_lowdim$beta_external_good

etas <- generate_eta(method = "exponential", n = 10, max_eta = 5)

cv_res <- cv.coxkl(z = train_dat_lowdim$z,
                   delta = train_dat_lowdim$status,
                   time = train_dat_lowdim$time,
                   beta = beta_external_good_lowdim,
                   etas = etas)
                    

survkl documentation built on April 22, 2026, 1:08 a.m.