Randomization/Bootstrap Reference Distribution of the Treatment Log-Hazard-Ratio for a Treatment-Only Cox PH Model (C++ Backend, Single-Covariate)

Builds an empirical reference (null or shifted-null) distribution of the treatment log-hazard-ratio \(\hat\beta_T\) from a treatment-only (single-covariate, no other adjustment covariates) Cox proportional-hazards model, by refitting the model on B = ncol(i_mat) pre-generated resample-and-reassign draws. This backs bootstrap randomization test (BRT) inversion for confidence intervals and p-values on the Cox log-hazard-ratio: repeated calls at different delta values (or a single call at delta = 0 for a null/reference distribution) let the caller invert the empirical distribution of \(\hat\beta_T\) against a target quantile or tail probability. This is a single-covariate special case; compute_coxph_rand_bootstrap_parallel_cpp (used by fast_coxph_regression's survival inference class) generalizes this to models with additional adjustment covariates and to Gaussian smoothing noise on the resampled log-hazard-ratio, and is the version actually wired into InferenceCoxPH; this treatment-only function currently has no in-package caller and should be treated as a lighter-weight standalone utility or superseded building block rather than part of the primary inference path.

Usage

compute_coxph_rand_bootstrap_cpp(y0, dead, i_mat, w_mat, delta, num_cores)

Arguments

y0

Numeric vector of original survival times (event or censoring time), length \(n\); not itself resampled — i_mat indexes into this vector per draw.

dead

Numeric vector of length \(n\) with values in {0, 1} giving the event indicator (1 = event, 0 = right-censored) for each original row, indexed by i_mat per draw.

i_mat

Integer matrix (\(n \times B\)) of 1-based row indices into y0/ dead, one resampled dataset per column.

w_mat

Integer matrix (\(n \times B\)) of treatment assignments in {0, 1}, one resampled assignment vector per column, aligned with the corresponding column of i_mat.

delta

Sharp-null log-time shift applied multiplicatively (\(e^\delta\)) to the working survival time of treated (w == 1) resampled subjects; delta = 0 leaves times unshifted.

num_cores

Number of OpenMP threads to use for parallelizing across draws (ignored, and draws run sequentially, when the package is built without OpenMP support).

Value

Numeric vector of length B = ncol(i_mat) with the fitted treatment log-hazard-ratio \(\hat\beta_T\) for each draw, or NA_real_ for draws whose Cox fit failed to converge.

Details

Per-draw model. For each draw \(b = 1, \dots, B\), this function forms a resampled dataset of size \(n\) = length(y0) by taking row indices i_mat[, b] (1-based, into the original y0/dead) and treatment labels w_mat[, b], applies the sharp-null time shift (see below), and fits an unstratified, single-covariate (treatment-only) Cox partial-likelihood model — the \(p = 1\) case of the model documented in build_cox_data_cache_cpp and fast_coxph_regression — via Newton-Raphson (cox_fit() with estimate_only = true, maxit = 20, tol = 1e-9, no warm start, smart_cold_start = false). Only the fitted coefficient \(\hat\beta_T\) (the log hazard ratio for treatment) is returned per draw; no variance-covariance matrix is computed (this function is for building a resampling distribution, not for single-fit inference).

Sharp-null shift. delta encodes a sharp null hypothesis of a constant multiplicative shift on the time scale for treated subjects: for draw \(b\), subject \(i\) with resampled treatment label \(w_i \in \{0, 1\}\), the working survival time is \(y_i \cdot e^{\delta}\) if \(w_i = 1\) and \(y_i\) (unchanged) if \(w_i = 0\); dead status is carried over from the original row unchanged. This is an accelerated-failure-time-style sharp null (\(\delta = 0\) recovers the unshifted resample), not a proportional-hazards sharp null; delta is on the same log-time scale used elsewhere in the package's AFT/Weibull machinery, not the log-hazard-ratio scale of the returned \(\hat\beta_T\).

Resampling scheme. i_mat and w_mat are assumed pre-generated by the caller (e.g. via the package's bootstrap or randomization-draw machinery) and are not validated here: i_mat need not be a permutation (indices may repeat, as in a nonparametric bootstrap draw with replacement, or may be a permutation, as in a randomization test) and w_mat need not respect any particular design's assignment-probability structure — whatever exchangeability or randomization-validity properties the resulting reference distribution has are entirely a property of how the caller generated i_mat/w_mat, not of this function.

Non-convergence and missingness. A draw's entry in the output is NA if the Newton-Raphson fit fails to converge within maxit iterations or the fitted coefficient is non-finite; callers must handle NA entries (e.g. by omission) when computing empirical quantiles or tail probabilities from the returned vector.

Parallelism and reproducibility. When compiled with OpenMP support and num_cores > 1, draws are processed in parallel via #pragma omp parallel for schedule(dynamic); each draw is a self-contained fit with no shared mutable state across draws (aside from writing to disjoint output slots), so results are deterministic given i_mat/w_mat regardless of the number of threads or scheduling order — this function consumes no RNG state itself, since the randomness lives entirely in how the caller generated i_mat and w_mat.

Complexity. \(O(B \cdot n \log n)\) for the \(B\) independent single- covariate Cox fits (dominated by the per-draw CoxData sort), parallelized across num_cores threads when available; memory use is \(O(n)\) per in-flight draw.

See also

fast_coxph_regression for the underlying Cox partial-likelihood model and its references; build_cox_data_cache_cpp for the per-draw sorted risk-set construction each draw performs internally. See also randomization test and bootstrap for background on resampling-based reference distributions.