Skip to contents

Fast Cox Proportional Hazards Regression (R Wrapper)

Source: R/helper_glm_fit.R
fast_coxph_regression.Rd

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.

See also

build_cox_data_cache_cpp for the full Cox partial-likelihood model, Breslow tie-handling, and input conventions; fast_coxph_regression_cpp for the native C++ backend this wrapper calls by default.

Examples

X = matrix(rnorm(500), 100, 5)
y = runif(100)
dead = rbinom(100, 1, 0.5)
fast_coxph_regression(X, y, dead)
#> $b
#> [1]  0.19311881 -0.09922657  0.03004752 -0.35649010 -0.50317133
#> 
#> $coefficients
#> [1]  0.19311881 -0.09922657  0.03004752 -0.35649010 -0.50317133
#> 
#> $vcov
#>              [,1]         [,2]         [,3]         [,4]         [,5]
#> [1,]  0.035735056 -0.001029973  0.001909756  0.002977374 -0.003548619
#> [2,] -0.001029973  0.025206366 -0.001420460 -0.002745109 -0.005172219
#> [3,]  0.001909756 -0.001420460  0.023808543  0.003374584 -0.002037919
#> [4,]  0.002977374 -0.002745109  0.003374584  0.032558806  0.005664298
#> [5,] -0.003548619 -0.005172219 -0.002037919  0.005664298  0.029322610
#> 
#> $neg_log_lik
#> [1] 169.9727
#> 
#> $fisher_information
#>           [,1]      [,2]      [,3]      [,4]      [,5]
#> [1,] 28.787971  1.636890 -1.407602 -3.091863  4.272081
#> [2,]  1.636890 41.602582  2.728601  1.791205  7.380009
#> [3,] -1.407602  2.728601 43.333319 -4.874392  4.264207
#> [4,] -3.091863  1.791205 -4.874392 32.824814 -6.737820
#> [5,]  4.272081  7.380009  4.264207 -6.737820 37.520062
#>