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 any of the full w, y, dead, or X inputs changes.

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.

Usage

Arguments

Value

Details

See also