Cox Proportional Hazards Regression Inference for Survival Responses

Fits a Cox proportional hazards model, \(\lambda(t \mid x_i) = \lambda_0(t) \exp(x_i^\top\beta)\), for survival responses using the treatment indicator and, optionally, all recorded covariates as predictors, by maximizing the Breslow-tie-corrected partial likelihood. For exact/right-censored data, fitting uses this package's internal Newton-Raphson C++ solver (fast_coxph_regression_prebuilt_cpp) by default (use_rcpp = TRUE), falling back to survival::coxph.fit()/survival::coxph() if that fails to converge or use_rcpp = FALSE. For left- or interval-censored data (a genuinely different likelihood, with no closed-form partial-likelihood score/information), fitting instead dispatches to icenReg::ic_sp(model = "ph"), a semiparametric NPMLE Cox fit whose standard errors come from icenReg's own internal bootstrap (not a closed-form covariance) — only Wald inference (testing_type = "wald") is supported on that path; score/gradient/likelihood-ratio/Bartlett testing types raise an informative error for such data. This is a partial-likelihood class (likelihood_tier = "partial") supporting score, gradient, and likelihood-ratio tests, plus parametric likelihood-ratio bootstrap calibration (both only for the exact/right-censored path), in addition to Wald and resampling-based inference. Fitted coefficients exceeding a fixed magnitude threshold (20, on the log-hazard-ratio scale) are treated as non-estimable (a numerical-divergence guard) rather than returned.

References

Cox, D. R. (1972). "Regression Models and Life-Tables." Journal of the Royal Statistical Society, Series B, 34(2), 187-220, for the proportional hazards model and partial likelihood; Breslow, N. E. (1974). "Covariance Analysis of Censored Survival Data." Biometrics, 30(1), 89-99, doi:10.2307/2529620 , for the tied-event partial-likelihood approximation used for exact/right-censored data.

Super class

Inference -> InferenceSurvivalCoxPHRegr

Methods

Public methods

• InferenceSurvivalCoxPHRegr$new()

• InferenceSurvivalCoxPHRegr$compute_estimate()

• InferenceSurvivalCoxPHRegr$compute_asymp_confidence_interval()

• InferenceSurvivalCoxPHRegr$compute_asymp_two_sided_pval()

• InferenceSurvivalCoxPHRegr$compute_estimate_with_bootstrap_weights()

• InferenceSurvivalCoxPHRegr$clone()

+ inherited public methods from Inference

• Inference$capabilities()
• Inference$compute_exact_confidence_interval()
• Inference$compute_exact_two_sided_pval_for_treatment_effect()
• Inference$duplicate()
• Inference$get_analysis_data()
• Inference$get_covariates()
• Inference$get_design_object()
• Inference$get_model_formula()
• Inference$get_nonestimable_reason()
• Inference$get_nonestimable_stage()
• Inference$get_optimization_alg()
• Inference$get_response()
• Inference$get_response_type()
• Inference$get_treatment()
• Inference$is_nonestimable()
• Inference$set_optimization_alg()
• Inference$set_seed()
• Inference$supports()

---

InferenceSurvivalCoxPHRegr$new()

Uses the shared randomization two-sided p-value contract; see InferenceRand. Deliberately pulled from InferenceRand, not InferenceRandCI – despite InferenceRandCI's override having a richer signature (type/args_for_type), its body calls super$...(), which resolves against this class's *actual* R6 superclass (Inference, which has no such method) once the method body is extracted and merged flatly by the component system – not against InferenceRand the way it would inside InferenceRandCI's own real inheritance chain. InferenceRandCI's only other content is an incidence-response special case (Zhang exact test) that never applies to survival data anyway, so the two are behaviorally identical for this class – confirmed by tracing the body, not assumed. Matches the pattern already used by the sibling migrated classes (LogRank/ GehanWilcox/KMDiff/RestrictedMeanDiff).

Initialize a Cox PH inference object for a completed design with a survival response. Unlike most survival inference classes in this package, this one accepts left- and interval-censored data (via an icenReg-backed fallback fit; see class documentation), not only exact/right-censored.

Usage

InferenceSurvivalCoxPHRegr$new(
  des_obj,
  model_formula = NULL,
  use_rcpp = TRUE,
  verbose = FALSE,
  smart_cold_start_default = NULL
)

Arguments

des_obj

A completed Design object with a survival response.

model_formula

Optional formula for covariate adjustment. If NULL (default), the formula from the design object is used and its pre-computed design matrix is reused. If a formula is provided, a new design matrix is constructed from the design's imputed covariates.

use_rcpp

Logical. If TRUE (default), enable internal Rcpp score/information helpers for likelihood inference.

verbose

Whether to print progress messages.

smart_cold_start_default

Whether to use smart cold start values by default.

---

InferenceSurvivalCoxPHRegr$compute_estimate()

Computes the Cox PH treatment coefficient \(\hat\beta_T\) (log hazard ratio) — see class documentation for the fitting backend used (partial-likelihood C++/survival solver for exact/ right-censored data; icenReg NPMLE for left-/interval-censored data). NA if the fit fails or the fitted coefficients are numerically extreme.

Usage

InferenceSurvivalCoxPHRegr$compute_estimate(estimate_only = FALSE)

Arguments

estimate_only

If TRUE, skip variance component calculations.

---

InferenceSurvivalCoxPHRegr$compute_asymp_confidence_interval()

Computes an asymptotic confidence interval using the configured likelihood-backed test.

Usage

InferenceSurvivalCoxPHRegr$compute_asymp_confidence_interval(alpha = 0.05)

Arguments

alpha

Significance level 1 - alpha. Default 0.05.

---

InferenceSurvivalCoxPHRegr$compute_asymp_two_sided_pval()

Computes an asymptotic two-sided p-value using the configured likelihood-backed test.

Usage

InferenceSurvivalCoxPHRegr$compute_asymp_two_sided_pval(delta = 0)

Arguments

delta

Null treatment effect to test against. Default 0.

---

InferenceSurvivalCoxPHRegr$compute_estimate_with_bootstrap_weights()

Recomputes the Cox PH treatment estimate under subject/block bootstrap weights (via weighted_cox_bootstrap_surrogate_fit(), which assumes ordinary right-censoring semantics), used by the Bayesian bootstrap and related weighted-resampling machinery. If the weights are effectively constant, short-circuits to the unweighted $compute_estimate(estimate_only = TRUE). Not supported for left- or interval-censored data — raises an error immediately, since the surrogate weighted fit has no extension for that likelihood. Always leaves the standard error unavailable (NA) regardless of estimate_only — this weighted path never computes a variance.

Usage

InferenceSurvivalCoxPHRegr$compute_estimate_with_bootstrap_weights(
  subject_or_block_weights,
  estimate_only = FALSE
)

Arguments

subject_or_block_weights

Subject-, block-, cluster-, or matched-set bootstrap weights.

estimate_only

Present for interface parity; this method never computes variance components regardless of its value.

---

InferenceSurvivalCoxPHRegr$clone()

The objects of this class are cloneable with this method.

Usage

InferenceSurvivalCoxPHRegr$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

# \donttest{
seq_des = DesignSeqOneByOneBernoulli$new(n = 10, response_type = 'survival')
for (i in 1:10) {
  seq_des$add_one_subject_to_experiment_and_assign(data.frame(x1 = rnorm(1)))
}
seq_des$add_all_subject_responses(runif(10))
inf = InferenceSurvivalCoxPHRegr$new(seq_des)
inf$compute_estimate()
#> [1] 2.496359
# }