Fast Cox Proportional Hazards Regression (R Wrapper)

Fits the Cox proportional-hazards partial-likelihood model documented in full at build_cox_data_cache_cpp (model equation, Breslow tie-handling, and input conventions). This R-level wrapper dispatches to either the package's own native C++ implementation (fast_coxph_regression_cpp, the default and recommended path) or, for cross-checking or when the Rcpp path is unavailable, an elastic-net-with-zero-penalty Cox fit via glmnet (use_rcpp = FALSE) — not survival::coxph, despite that being the more commonly used reference implementation for Cox models in R.

Usage

fast_coxph_regression(
  X,
  y,
  dead,
  use_rcpp = TRUE,
  estimate_only = FALSE,
  optimization_alg = "lbfgs",
  warm_start_beta = NULL,
  warm_start_fisher_info = NULL,
  smart_cold_start = TRUE
)

Arguments

X: A numeric matrix of predictor variables. It is assumed that an intercept term is handled implicitly by the Cox model and should not be included in X.
y: A numeric vector representing the observed time (event time or censoring time).
dead: A numeric vector (0 or 1) indicating event status (1 for event, 0 for censored).
use_rcpp: Logical. If TRUE (default), use the optimized Rcpp implementation (fast_coxph_regression_cpp). If FALSE, use glmnet's Cox path at zero penalty (glmnet(..., family = "cox", lambda = 0)) instead.
estimate_only: Logical. If TRUE, skip variance-covariance matrix calculation for speed. Only affects the use_rcpp = TRUE path; the glmnet fallback path does not compute a variance-covariance matrix at all (vcov is never populated when use_rcpp = FALSE, regardless of estimate_only).
optimization_alg: Optimization algorithm: "newton_raphson" (default) or "lbfgs". Only affects the use_rcpp = TRUE path; unused when use_rcpp = FALSE.
warm_start_beta: Optional starting values for coefficients. If provided, smart_cold_start is ignored. Only affects the use_rcpp = TRUE path.
warm_start_fisher_info: Optional initial Fisher Information matrix. Only affects the use_rcpp = TRUE path.
smart_cold_start: Logical. If TRUE (default), use an initial OLS-based guess when starting from scratch (a "cold start") with no prior knowledge. This is ignored if warm_start_beta is provided. Only affects the use_rcpp = TRUE path.

Value

A list. When use_rcpp = TRUE (default), a list with components

b, coefficients: A numeric vector of the estimated log-hazard-ratio coefficients \(\hat\beta\) (b and coefficients are identical; both are populated for interface consistency with the package's other fast_* wrappers).
vcov: The variance-covariance matrix of \(\hat\beta\), or NULL when estimate_only = TRUE.
neg_log_lik: The negative Cox partial log-likelihood at the fitted coefficients.
fisher_information: The Hessian of the negative partial log-likelihood at the fitted coefficients.

When use_rcpp = FALSE, only a single component, b (the glmnet-fitted coefficient vector via coef(), in glmnet's own sparse-matrix representation rather than a plain numeric vector) — none of coefficients/vcov/neg_log_lik/ fisher_information are present on this path.

Details

Failure semantics. If the C++ fit (use_rcpp = TRUE) errors or fails to report converged, this function stops with an error rather than silently falling back to glmnet — the two code paths are alternative caller choices, not an automatic fallback chain (contrast with, e.g., fast_beta_regression's automatic betareg fallback).

glmnet dependency. When use_rcpp = FALSE, this function requires the glmnet package, which is listed in Suggests and is not installed automatically with EDI; it errors immediately if glmnet is not installed.

Examples

X = matrix(rnorm(500), 100, 5)
y = runif(100)
dead = rbinom(100, 1, 0.5)
fast_coxph_regression(y, dead, X)
#> $b
#> [1] 0.8198314
#> 
#> $coefficients
#> [1] 0.8198314
#> 
#> $vcov
#>           [,1]
#> [1,] 0.4132819
#> 
#> $neg_log_lik
#> [1] 131.7861
#> 
#> $fisher_information
#>          [,1]
#> [1,] 2.419656
#>