Fast Cox Proportional Hazards Regression, Cache-Reusing Fit (C++ Backend)

Fits the same unstratified-or-stratified Cox partial-likelihood model documented at build_cox_data_cache_cpp / build_stratified_cox_data_cache_cpp, but takes a pre-built risk-set cache (cox_data_xptr, an externalptr produced by one of those two functions) instead of raw (X, y, dead) data, skipping the sort/tabulation step on every call. This is the entry point the package's Cox inference classes (e.g. InferenceCoxPH, InferenceStratifiedCoxPH) use for repeated fits on the same data (successive estimate_only vs. full-variance calls, or bootstrap/ randomization replicates that only change the treatment column of X, rebuilding the cache only when the covariates or assignment actually change). fast_coxph_regression_cpp is the equivalent one-shot entry point that builds and discards the cache internally, for callers that only need a single fit.

Usage

fast_coxph_regression_prebuilt_cpp(
  cox_data_xptr,
  warm_start_beta = NULL,
  smart_cold_start = TRUE,
  estimate_only = FALSE,
  maxit = 20L,
  tol = 1e-9,
  fixed_idx = NULL,
  fixed_values = NULL,
  optimization_alg = "newton_raphson",
  warm_start_fisher_info = NULL
)

Arguments

cox_data_xptr

An externalptr to a cached Cox risk-set representation, as returned by build_cox_data_cache_cpp (unstratified) or build_stratified_cox_data_cache_cpp (stratified).

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.

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\); omitted 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.

gradient_norm

The norm of the score (gradient) vector at convergence.

Details

Because cox_data_xptr carries a fixed, already-sorted risk-set structure (whether unstratified — one risk set — or stratified — one risk set per stratum, depending on which cache-building function produced it), the number and identity of subjects/strata are entirely determined by the cache; only the optimization behavior (warm starts, convergence, algorithm) is configurable through this function's own arguments. Passing a stale cache (built from data that has since changed) silently fits the model to the cached data, not the caller's current X/y/dead — callers are responsible for invalidating and rebuilding the cache when the underlying data changes; see build_cox_data_cache_cpp for the exact caching/mutation contract.

See also

build_cox_data_cache_cpp/ build_stratified_cox_data_cache_cpp for building the required cache and the full Cox partial-likelihood model documentation; fast_coxph_regression_cpp for the one-shot (build-and-discard) variant.