suspected_deviations: Intervals with suspected non-proportional hazard deviations

In survHC: Higher Criticism Tests for Non-Proportional Hazard Deviations

Intervals with suspected non-proportional hazard deviations

Description

Computes per-interval hypergeometric p-values and flags those at or below the Higher Criticism threshold. This localises a detection to specific windows of the follow-up, which is the diagnostic information a single-number test cannot provide, and is suitable for shading on a Kaplan-Meier plot.

Usage

suspected_deviations(durations_A, ...)

## Default S3 method:
suspected_deviations(
  durations_A,
  durations_B,
  event_observed_A = NULL,
  event_observed_B = NULL,
  alternative = c("greater", "less", "both"),
  gamma = 0.2,
  hc_version = c("dj2008", "dj2004", "beta", "star"),
  t_0 = -1,
  n_intervals_to_pool = NULL,
  ...
)

## S3 method for class 'formula'
suspected_deviations(formula, data, subset, na.action, ...)

Arguments

durations_A, durations_B	Numeric vectors of event or censoring times. durations_A may instead be a formula, which selects the formula method.
event_observed_A, event_observed_B	Optional 0/1 vectors, 1 indicating an observed event and 0 a censored observation. Default: all events.
alternative	One of "greater" (default), "less" or "both". With "both", columns for the reverse direction are added and suspected flags either direction.
gamma	Fraction of the smallest ordered p-values scanned, in (0, 1]. Default 0.2.
hc_version	Which Higher Criticism variant to use, matching the named methods of the Python package multitest (>= 0.2.2) and the hc_version argument of lifelines-hc. "dj2008" (default) uses u_i = i/N with denominator \sqrt{u_i(1-u_i)/N}; "dj2004" uses u_i = i/N with denominator \sqrt{p_{(i)}(1-p_{(i)})/N}, which is equation (2) of Kipnis, Galili and Yakhini (2026); "beta" uses u_i = i/(N+1) with denominator \sqrt{u_i(1-u_i)/(N+2)}; "star" uses the "beta" denominator but starts the scan at the first ordered p-value exceeding (1-\epsilon)/N. Ignored by berk_jones_test, fisher_combination_test and min_p_test.
t_0	Restrict the analysis to events at or before t_0. A negative value (default) applies no restriction.
n_intervals_to_pool	Number of equal-width intervals to pool event times into. Strongly recommended for continuous survival data, where each distinct time carries at most one event and the per-time hypergeometric p-values are too coarse to be informative. Values between 50 and 200 usually work well. NULL (default) applies no pooling.
formula	A two-sided formula Surv(time, status) ~ group; see Details.
data	An optional data frame, list or environment holding the variables named in formula.
subset	An optional vector specifying a subset of observations to use.
na.action	A function describing what should happen when the data contain NAs. Defaults to getOption("na.action"), normally na.omit.
...	Further arguments. The formula method passes these on to the default method, which accepts none and signals an error if any are supplied, so that a misspelled argument name cannot be silently ignored.

Details

Two interfaces are available and return the same numbers. The default method takes the two samples as vectors, mirroring the Python package lifelines-hc. The formula method takes the usual survival formula Surv(time, status) ~ group, which needs the survival package for Surv itself; without it, cbind(time, status) ~ group and time ~ group also work, the latter treating every observation as an event.

The grouping variable must take exactly two values. Its first level is group A and its second is group B, so alternative = "greater" tests for excess hazard in the second level. Levels are taken in factor order for a factor, and otherwise in the order sort(unique(.)) gives: numerically for numbers, alphabetically for strings.

The two interfaces differ only in their treatment of missing values. The default method rejects NA durations; the formula method applies na.action, which by default drops incomplete rows.

Value

A data frame with one row per event time or pooled interval and columns time (or time_lower and time_upper when pooled), at_risk_A, at_risk_B, observed_A, observed_B, hypergeom_pvalue, suspected and hc_threshold.

References

Kipnis, A., Galili, B. and Yakhini, Z. (2026). Higher criticism for rare and weak non-proportional hazard deviations in survival analysis. Biometrika 113(1), asaf075. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1093/biomet/asaf075")}

Kipnis, A., Galili, B. and Yakhini, Z. (2026). lifelines-hc: Higher Criticism testing for sparse non-proportional hazard departures in Python. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.48550/arXiv.2610.07268")}

See Also

higher_criticism_test, plot_pvalue_profile

Examples

set.seed(1)
# a sparse departure confined to one window
T_A <- rexp(300, 1 / 10)
T_B <- c(rexp(250, 1 / 10), rexp(50, 1 / 2))
d <- suspected_deviations(T_A, T_B, n_intervals_to_pool = 50)
head(d[d$suspected, ])

trial <- data.frame(time = c(T_A, T_B), status = 1,
                    arm = rep(c("A", "B"), c(300, 300)))
d2 <- suspected_deviations(cbind(time, status) ~ arm, data = trial,
                           n_intervals_to_pool = 50)
head(d2[d2$suspected, ])

survHC documentation built on Oct. 22, 2026, 1:06 a.m.