logrank_test()

Compare survival across groups using the weighted log-rank (G-rho) test.

Usage

Source

logrank_test(
    surv,
    group,
    *,
    rho=0.0,
    gamma=0.0,
    strata=None,
)

Tests whether survival curves differ significantly across two or more groups using a chi-square test based on weighted event counts. The test is flexible: with default weights (Fleming-Harrington rho=0, gamma=0), it gives equal weight to all event times (standard log-rank). With rho=1, gamma=0 (Peto-Peto), it emphasizes early events where more subjects are at risk. Other rho/gamma combinations allow custom emphasis on different phases of follow-up.

The test compares observed vs. expected event counts under the null hypothesis of equal survival. A large chi-square statistic indicates the groups differ; p-values are interpreted as the probability of seeing such a statistic or larger if survival is truly equal.

Stratification: Optionally stratify by a nuisance variable (e.g., site, gender) to compute the test within each stratum, then combine results. This controls for confounding while testing group differences.

Parameters

surv: Surv

A Surv response object representing censored survival times. Supports right-censored data (standard time-to-event) or counting-process format (interval-based data with entry/exit times). Constructed with Surv.right(), Surv.counting(), or Surv.multistate().

group: Any

Group labels, one per observation. Can be a Narwhals series (Polars/Pandas), 1-D array, or Python sequence. Labels can be strings, integers, or other hashable types. Must have the same length as surv.

rho: float = 0.0

Fleming-Harrington weight exponents applied to the pooled Kaplan-Meier survival \(S(t-)\) at each event time. The weight is \(S(t-)^\rho \, (1-S(t-))^\gamma\).

  • rho=0, gamma=0 (default): Standard log-rank test. Equal weight across all times.
  • rho=1, gamma=0: Peto-Peto (Wilcoxon) test. Emphasizes early events.
  • rho=0, gamma=1: Tarone-Ware. Alternative early-event emphasis.
  • Other (rho, gamma): Flexible emphasis. Higher values emphasize the chosen phase.
gamma: float = 0.0

Fleming-Harrington weight exponents applied to the pooled Kaplan-Meier survival \(S(t-)\) at each event time. The weight is \(S(t-)^\rho \, (1-S(t-))^\gamma\).

  • rho=0, gamma=0 (default): Standard log-rank test. Equal weight across all times.
  • rho=1, gamma=0: Peto-Peto (Wilcoxon) test. Emphasizes early events.
  • rho=0, gamma=1: Tarone-Ware. Alternative early-event emphasis.
  • Other (rho, gamma): Flexible emphasis. Higher values emphasize the chosen phase.
strata: Any = None
Optional stratifying factor, one per observation. Same length as surv. When provided, the test is computed separately within each stratum, then combined (stratified test). Use to control for confounding or variable that affects baseline hazard but not group differences. Example: stratify by site to account for site-specific differences in survival while testing an overall group effect.

Returns

TestResult

A result object with attributes:

  • statistic: Chi-square test statistic.
  • df: Degrees of freedom (number of groups minus one).
  • p_value: Upper-tail chi-square p-value. Small values indicate survival curves differ.
  • method: Description of the test (e.g., “Log-rank test”, “Stratified log-rank test”, “G-rho test (rho=1, gamma=0)”).
  • observed: Dictionary mapping group labels to observed weighted event counts.
  • expected: Dictionary mapping group labels to expected event counts under null.

Details

The log-rank test uses the hypergeometric variance for the chi-square statistic, matching R’s survival::survdiff. The pooled Kaplan-Meier survivor curve from all groups combined is used to compute the Fleming-Harrington weights, ensuring the test is consistently weighted regardless of group sample sizes.

Counting-process data (with entry times) are fully supported, allowing stratification and left-truncation (delayed entry).

Examples

Test whether survival differs between the two sexes in the bundled lung dataset:

import greenwood as gw

lung = gw.load_dataset("lung", backend="polars")
y = gw.Surv.right(lung["time"], event=(lung["status"] == 2))
result = gw.logrank_test(y, group=lung["sex"])
result
TestResult(method='Log-rank test', statistic=10.3267, df=1, p_value=0.001311)

Extract individual components from the result:

result.statistic  # Chi-square statistic
10.32674195488564
result.p_value  # P-value for significance
0.001311164520355484
result.observed  # Observed event counts per group
{1: 112.0, 2: 53.0}

Use the Peto-Peto (Wilcoxon) weighted test to emphasize differences in early survival:

gw.logrank_test(y, group=lung["sex"], rho=1, gamma=0)
TestResult(method='G-rho test (rho=1, gamma=0)', statistic=12.7142, df=1, p_value=0.0003629)

Run a stratified test to control for institution (if available in data):

# gw.logrank_test(y, group=lung["sex"], strata=lung["institution"])