## logrank_test()


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


Usage

``` python
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](Surv.md#greenwood.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.md#greenwood.Surv.right), [Surv.counting()](Surv.md#greenwood.Surv.counting), or [Surv.multistate()](Surv.md#greenwood.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:


``` python
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:


``` python
result.statistic  # Chi-square statistic
```


    10.32674195488564


``` python
result.p_value  # P-value for significance
```


    0.001311164520355484


``` python
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:


``` python
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):


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