Fast Cox Proportional Hazards Regression, One-Shot Fit (C++ Backend)

Fits the unstratified Cox proportional-hazards partial-likelihood model documented in full at build_cox_data_cache_cpp — the same model, Breslow tie-handling, and input conventions — in a single call that internally builds the sorted risk-set cache, runs the optimizer, and discards the cache afterward. Use this entry point for a one-off fit; use build_cox_data_cache_cpp plus fast_coxph_regression_prebuilt_cpp instead when fitting the same (X, y, dead) repeatedly (e.g. across bootstrap/randomization replicates), to avoid rebuilding the risk-set cache on every call. fast_coxph_regression is the R-level wrapper around this backend (with an survival-free-of-Rcpp fallback path via glmnet).

Usage

fast_coxph_regression_cpp(
  X,
  y,
  dead,
  warm_start_beta = NULL,
  smart_cold_start = TRUE,
  estimate_only = FALSE,
  maxit = 20L,
  tol = 1e-9,
  cluster = NULL,
  fixed_idx = NULL,
  fixed_values = NULL,
  optimization_alg = "newton_raphson",
  warm_start_fisher_info = NULL
)

Arguments

X

A numeric matrix of predictor variables (no intercept column; see build_cox_data_cache_cpp).

y

Numeric vector of observed (event or censoring) times.

dead

Numeric vector with values in {0, 1}: event indicator (1 = event, 0 = right-censored).

warm_start_beta

Optional starting values for the coefficients \(\beta\).

smart_cold_start

Logical. If TRUE (default) and no warm_start_beta is supplied, use an OLS-based initial guess rather than a zero cold start.

estimate_only

Logical. If TRUE, skip variance-covariance matrix calculation for speed.

maxit

Maximum number of Newton-Raphson/L-BFGS iterations.

tol

Convergence tolerance.

cluster

Optional clustering variable; when supplied, the returned variance-covariance matrix uses a cluster-robust (grouped) sandwich correction instead of the naive model-based inverse-information variance, i.e. one that remains asymptotically valid under within-cluster correlation of the martingale residuals.

fixed_idx

Optional integer indices of coefficients to hold fixed rather than estimate.

fixed_values

Optional values to fix the parameters named by fixed_idx at; must be the same length as fixed_idx.

optimization_alg

Optimization algorithm: "newton_raphson" (default) or "lbfgs".

warm_start_fisher_info

Optional initial Fisher Information matrix to warm-start curvature information for the optimizer.

Value

A list containing the following components:

coefficients

A numeric vector of the estimated log-hazard-ratio coefficients \(\hat\beta\).

vcov

The variance-covariance matrix of \(\hat\beta\) (naive inverse-information, or cluster-robust sandwich if cluster is supplied); omitted/not computed when estimate_only = TRUE.

neg_ll

The negative Cox partial log-likelihood at the final iteration.

converged

A logical value indicating whether the algorithm converged.

iterations

The number of optimizer iterations performed.

fisher_information

The Hessian of the negative partial log-likelihood at the fitted coefficients (the observed information matrix).

gradient_norm

The norm of the score (gradient) vector at convergence, a diagnostic of how tightly the convergence criterion was met.

See also

build_cox_data_cache_cpp for the full Cox partial-likelihood model, Breslow tie-handling, and input conventions this function implements; fast_coxph_regression_prebuilt_cpp for the cache-reusing variant; fast_coxph_regression for the R-level wrapper.