Kaplan-Meier Median-Difference Inference for Survival Responses

Fits a non-parametric treatment-effect estimator for censored survival responses: the difference in Kaplan-Meier median survival times between the treated and control arms, \(\hat m_T - \hat m_C\). Standard errors are obtained by back-calculating from each arm's separate Brookmeyer-Crowley confidence interval for its own median (via survival::survfit's default log-log-transformed interval): \(\hat\sigma_i = (\mathrm{upper}_i - \mathrm{lower}_i) / (2 z_{\alpha/2})\), combined (the two arms are independent by design) as \(\sqrt{\hat\sigma_T^2 + \hat\sigma_C^2}\). When either arm's median is inestimable (its Kaplan-Meier curve never reaches 0.5) or the back-calculated bounds are non-finite, the Wald-style confidence interval and p-value methods ($compute_asymp_confidence_interval(), $compute_asymp_two_sided_pval()) silently fall back to a nonparametric bootstrap instead of returning NA. A convenience method, $compute_asymp_log_rank_two_sided_pval_for_treatment_effect(), is also provided for the log-rank p-value on the same fitted survival curves. For left- or interval-censored data, the point estimate instead comes from a Turnbull NPMLE median contrast (interval::icfit(), via turnbull_npmle_stat_diff()), which has no closed-form standard error — inference on that path relies entirely on the bootstrap fallback described above. Randomization confidence intervals are not supported (the median difference's units are not commensurate with the randomization CI bisection algorithm's transformed-scale null search).

References

Kaplan, E. L., and Meier, P. (1958). "Nonparametric Estimation from Incomplete Observations." Journal of the American Statistical Association, 53(282), 457-481, doi:10.2307/2281868 , for the Kaplan-Meier survival curve estimator each arm's median is read from. Brookmeyer, R., and Crowley, J. (1982). "A Confidence Interval for the Median Survival Time." Biometrics, 38(1), 29-41, doi:10.2307/2530286 , for the per-arm median confidence interval this class's standard error is back-calculated from. Turnbull, B. W. (1976). "The Empirical Distribution Function with Arbitrarily Grouped, Censored and Truncated Data." Journal of the Royal Statistical Society, Series B, 38(3), 290-295, doi:10.1111/j.2517-6161.1976.tb01597.x , for the NPMLE used on the left-/interval-censored path.

Super class

Inference -> InferenceSurvivalKMDiff

Methods

Public methods

• InferenceSurvivalKMDiff$new()

• InferenceSurvivalKMDiff$compute_estimate()

• InferenceSurvivalKMDiff$compute_estimate_with_bootstrap_weights()

• InferenceSurvivalKMDiff$compute_asymp_confidence_interval()

• InferenceSurvivalKMDiff$compute_asymp_two_sided_pval()

• InferenceSurvivalKMDiff$compute_asymp_log_rank_two_sided_pval_for_treatment_effect()

• InferenceSurvivalKMDiff$compute_rand_confidence_interval()

• InferenceSurvivalKMDiff$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()

---

InferenceSurvivalKMDiff$new()

Uses the shared randomization two-sided p-value contract; see InferenceRand.

Initialize Kaplan-Meier median-difference survival inference and prepare treatment-group survival curves used by InferenceSurvivalKMDiff.

Usage

InferenceSurvivalKMDiff$new(
  des_obj,
  model_formula = NULL,
  verbose = FALSE,
  smart_cold_start_default = NULL
)

Arguments

des_obj

The design object.

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.

verbose

If TRUE, print additional information.

smart_cold_start_default

Whether to use smart cold start values by default.

---

InferenceSurvivalKMDiff$compute_estimate()

Computes the class-specific mean or survival contrast; see InferenceMLEorKMSummaryTable.

Usage

InferenceSurvivalKMDiff$compute_estimate(estimate_only = FALSE)

Arguments

estimate_only

If TRUE, skip variance component calculations.

Returns

The setting-appropriate (see description) numeric estimate of the treatment effect

Examples

seq_des = DesignSeqOneByOneBernoulli$new(n = 6, response_type = "survival")
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[1, 2 : 10])
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[2, 2 : 10])
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[3, 2 : 10])
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[4, 2 : 10])
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[5, 2 : 10])
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[6, 2 : 10])
seq_des$add_all_subject_responses(
  ys = c(4.71, NA, 4.78, 6.11, NA, 8.43),
  y_Ls = c(NA, 1.23, NA, NA, 5.95, NA),
  y_Rs = c(NA, Inf, NA, NA, Inf, NA)
)

seq_des_inf = InferenceSurvivalKMDiff$new(seq_des)
seq_des_inf$compute_estimate()

---

InferenceSurvivalKMDiff$compute_estimate_with_bootstrap_weights()

Recomputes the class-specific treatment estimate for a bootstrap sample; see InferenceNonParamBootstrap.

Usage

InferenceSurvivalKMDiff$compute_estimate_with_bootstrap_weights(
  subject_or_block_weights,
  estimate_only = FALSE
)

Arguments

subject_or_block_weights

Row weights for the bootstrap sample.

estimate_only

If TRUE, skip variance calculations.

---

InferenceSurvivalKMDiff$compute_asymp_confidence_interval()

Computes a (1 - alpha)-level confidence interval for the difference in Kaplan-Meier median survival times (treatment minus control).

The Brookmeyer-Crowley confidence interval is obtained for each group's median separately via survival::survfit (using a log-log transformation of the survival function by default). The per-group SE is back-calculated from the CI half-width as \(\hat\sigma_i = (\text{upper}_i - \text{lower}_i) / (2 z_{\alpha/2})\). The two groups are independent by design, so the SE of the difference is \(\sqrt{\hat\sigma_T^2 + \hat\sigma_C^2}\), and the CI is \((\hat{m}_T - \hat{m}_C) \pm z_{\alpha/2} \cdot \sqrt{\hat\sigma_T^2 + \hat\sigma_C^2}\).

Falls back to compute_bootstrap_confidence_interval when either group's median is not estimable (i.e., the Kaplan-Meier curve does not reach 0.5) or when the Brookmeyer-Crowley CI bounds are NA.

Usage

InferenceSurvivalKMDiff$compute_asymp_confidence_interval(alpha = 0.05)

Arguments

alpha

The significance level; the confidence level is 1 - alpha. Default is 0.05.

Returns

A numeric vector of length 2 giving the (lower, upper) confidence bounds for the difference in median survival times, on the original time scale.

---

InferenceSurvivalKMDiff$compute_asymp_two_sided_pval()

Computes a Wald-style 2-sided p-value based on the median difference and its back-calculated standard error.

Usage

InferenceSurvivalKMDiff$compute_asymp_two_sided_pval(delta = 0)

Arguments

delta

The null difference to test against. Default is 0.

Returns

The approximate frequentist p-value

---

InferenceSurvivalKMDiff$compute_asymp_log_rank_two_sided_pval_for_treatment_effect()

Computes a 2-sided p-value via the log rank test

Usage

InferenceSurvivalKMDiff$compute_asymp_log_rank_two_sided_pval_for_treatment_effect(
  delta = 0
)

Arguments

delta

The null difference to test against. For any treatment effect at all this is set to zero (the default).

Returns

The approximate frequentist p-value

---

InferenceSurvivalKMDiff$compute_rand_confidence_interval()

Uses the shared randomization confidence-interval contract; see InferenceRandCI.

Usage

InferenceSurvivalKMDiff$compute_rand_confidence_interval(
  alpha = 0.05,
  r = 501,
  pval_epsilon = 0.005,
  show_progress = TRUE,
  ci_search_control = NULL
)

Arguments

alpha

The confidence level in the computed confidence interval is 1 - alpha. The default is 0.05.

r

The number of randomization vectors. The default is 501.

pval_epsilon

The bisection algorithm tolerance. The default is 0.005.

show_progress

Show a text progress indicator.

ci_search_control

Unused.

Returns

A 1 - alpha sized frequentist confidence interval

---

InferenceSurvivalKMDiff$clone()

The objects of this class are cloneable with this method.

Usage

InferenceSurvivalKMDiff$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 = InferenceSurvivalKMDiff$new(seq_des)
inf$compute_estimate()
#> [1] -0.03483666
# }

## ------------------------------------------------
## Method `InferenceSurvivalKMDiff$compute_estimate()`
## ------------------------------------------------

seq_des = DesignSeqOneByOneBernoulli$new(n = 6, response_type = "survival")
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[1, 2 : 10])
#> [1] 1
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[2, 2 : 10])
#> [1] 1
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[3, 2 : 10])
#> [1] 0
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[4, 2 : 10])
#> [1] 0
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[5, 2 : 10])
#> [1] 1
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[6, 2 : 10])
#> [1] 1
seq_des$add_all_subject_responses(
  ys = c(4.71, NA, 4.78, 6.11, NA, 8.43),
  y_Ls = c(NA, 1.23, NA, NA, 5.95, NA),
  y_Rs = c(NA, Inf, NA, NA, Inf, NA)
)

seq_des_inf = InferenceSurvivalKMDiff$new(seq_des)
seq_des_inf$compute_estimate()
#> [1] 2.985