Build a Reusable Unstratified Cox Data Cache (C++ Backend)

Precomputes and caches the sorted risk-set structure needed to evaluate the Cox partial-likelihood, score, and Hessian, so that repeated Newton-Raphson or L-BFGS fits on the same (X, y, dead) data (e.g. across bootstrap/randomization replicates of the treatment column, or successive estimate_only vs. full-variance calls) do not repeat the \(O(n \log n)\) sort and event-time tabulation on every call. This is the unstratified counterpart of build_stratified_cox_data_cache_cpp; the returned cache is consumed by fast_coxph_regression_prebuilt_cpp, which implements the same Cox partial-likelihood as fast_coxph_regression and fast_coxph_regression_cpp.

Usage

build_cox_data_cache_cpp(X, y, dead)

Arguments

X

A numeric matrix of predictor variables (no intercept column); \(n\) rows, one per subject.

y

A numeric vector of length \(n\) giving the observed (event or censoring) time for each subject.

dead

A numeric vector of length \(n\) with values in {0, 1} indicating event status (1 = event/death, 0 = right-censored).

Value

An externalptr to a cached, sorted Cox risk-set representation of (X, y, dead), for use as the cox_data_xptr argument of fast_coxph_regression_prebuilt_cpp.

Details

Model. No fitting happens here; this function only prepares the single risk set (stratum) used by the Breslow-tied Cox partial likelihood $$\ell(\beta) = \sum_{k} \Big[ \big(\textstyle\sum_{i \in D_k} x_i\big)^\top \beta - d_k \log\!\big(\textstyle\sum_{j \in R_k} e^{x_j^\top \beta}\big) \Big],$$ where \(D_k\) is the set of subjects with an event at the \(k\)-th unique event time and \(R_k\) is the risk set (all subjects with y >= that event time). See fast_coxph_regression for the full model, scale, and optimizer contract; this page documents only the cache construction.

What is cached. Internally builds a single CoxData record that: (1) sorts subjects by ascending y (observed/censoring time), breaking ties by placing events (dead == 1) before censored observations at the same time; (2) stores the sort-permuted y, dead, and row-major copy of X; and (3) tabulates the vector of unique event times and, for each, the number of tied events (event_counts), which drives the Breslow tie-handling correction in the partial-likelihood, score, and Hessian.

Input conventions. X is an \(n \times p\) design matrix with one row per subject and no intercept column (Cox models are fit on the partial likelihood, which has no intercept). y is the observed time (event or censoring time), and dead is a 0/1 event indicator (1 = event, 0 = right-censored); both must have length \(n\) matching nrow(X). Tied event times are handled via the Breslow approximation (via event_counts), not the exact (Cox) or Efron method. There is no support for left- or interval-censored data at this layer; classes with more general censoring (see supports_interval_or_left_censored_data() in InferenceEngine) bypass this cache and dispatch to icenReg instead. NA/non-finite values in X, y, or dead and negative values of y are not checked or handled at this layer; callers are responsible for filtering or imputing upstream.

Return value and object lifetime. Returns an externalptr (Rcpp::XPtr) wrapping a heap-allocated std::vector<CoxData> of length 1 (a single unstratified stratum), so that fast_coxph_regression_prebuilt_cpp can share the same stratified interface as the stratified cache. The pointer owns its memory (finalizer registered via XPtr(..., true)) and is freed automatically by R's garbage collector; it must not be serialized (e.g. via saveRDS) or reused after the R session that created it exits. The cache is immutable once built and safe to reuse across many calls to fast_coxph_regression_prebuilt_cpp as long as X, y, and dead have not changed; callers (e.g. InferenceCoxPH$private$cox_data_cache) are responsible for invalidating and rebuilding the cache when the treatment assignment or covariates change.

Complexity. \(O(n \log n)\) for the sort plus \(O(n)\) for the tabulation pass, where \(n\) is the number of subjects; memory use is \(O(np)\) for the row-major copy of X plus \(O(n)\) for the sorted y/dead and event-time tables.

See also

build_stratified_cox_data_cache_cpp for the stratified (multiple risk-set) analog, fast_coxph_regression_prebuilt_cpp for the fitting routine that consumes this cache, and fast_coxph_regression for the full Cox model documentation, including the partial-likelihood derivation, tie-handling, and references. Analogous Python API: lifelines CoxPHFitter.