trend_test()

Test for linear trend across ordered groups using the log-rank test family.

Usage

Source

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

A trend test is a one-degree-of-freedom test for whether survival changes linearly across ordered groups (e.g., disease stages I, II, III, IV or dose levels: low, medium, high). It’s more powerful than the multi-degree-of-freedom log-rank test when groups are naturally ordered.

The test assigns numeric scores to each group (default: 0, 1, 2, … for sorted order) and tests whether a linear relationship exists between group score and survival. It can be combined with Fleming-Harrington weights and stratification, just like logrank_test.

When to use trend tests: Use when groups are naturally ordered and you want a higher-power test for a linear trend, rather than testing all possible differences. For exploratory analysis without assuming order, use logrank_test instead.

Parameters

surv: Surv

A Surv response object representing censored survival times. Supports right-censored data or counting-process format.

group: Any

Group labels (typically ordered categories like 0, 1, 2, 3 for dose levels or stages). Can be a Narwhals series, 1-D array, or Python sequence. Must have at least 2 groups. Must have the same length as surv.

scores: Array | None = None

Numeric scores assigned to each group to define the linear trend. If None (default), groups are sorted lexicographically and assigned scores 0, 1, 2, …, (k-1) where k is the number of groups. Provide custom scores as a dictionary mapping group labels to numeric values (e.g., {1: 0, 2: 1, 3: 2} for stage labels 1,2,3) to use different scoring (e.g., unequal spacing). Scores can be any real numbers (including negative).

rho: float = 0.0

Fleming-Harrington weight exponent applied to the pooled survival probability. The default of 0 gives a standard trend test with equal weight across all times.

gamma: float = 0.0

Fleming-Harrington weight exponent applied to (1 - pooled survival probability). The default of 0; combined with rho=1 gives Peto-Peto (Wilcoxon) trend test emphasizing early events. See logrank_test for more details on Fleming-Harrington weighting.

strata: Any = None

Optional stratifying factor. When provided, the trend test is computed separately within each stratum, then combined (stratified trend test). Use to control for confounding while testing a linear trend.

Returns

TestResult

A result object with attributes:

• statistic: chi-square test statistic (always 1 degree of freedom).
• df: always 1 for trend tests.
• p_value: upper-tail chi-square p-value.
• method: description of the test, e.g., “Linear trend test”, “Stratified linear trend test”, “G-rho trend test (rho=1, gamma=0)”.
• observed: dictionary mapping each group to observed event count (unweighted).
• expected: dictionary mapping each group to expected event count under null.

Details

The test uses a linear contrast with assigned scores:

• U = \sum_i \text{score}[i] \cdot (O[i] - E[i])
• V = \sum_i \text{score}[i]^2 \cdot \text{Var}[i]
• \chi^2 = U^2 / V \sim \chi^2(1)

This is equivalent to fitting a Cox model with group encoded as the numeric score and testing whether the coefficient is zero using a score test.

Examples

Test for linear trend in survival across ordered ECOG performance-status grades:

import greenwood as gw
import polars as pl

# Load data and build a right-censored response
lung = gw.load_dataset("lung", backend="polars")
lung = lung.filter(pl.col("ph.ecog").is_not_null())
y = gw.Surv.right(lung["time"], event=(lung["status"] == 2))

# Default: ECOG grades are sorted and assigned scores 0,1,2,3
result = gw.trend_test(y, group=lung["ph.ecog"])
result

TestResult(method='Linear trend test', statistic=10.3952, df=1, p_value=0.001263)

Use custom scores to give different weight to each grade:

# Quadratic scores emphasize the steep decline from ECOG 2 to ECOG 3
scores = {0: 0, 1: 1, 2: 4, 3: 9}
gw.trend_test(y, group=lung["ph.ecog"], scores=scores)

TestResult(method='Linear trend test', statistic=14.8506, df=1, p_value=0.0001164)

Use Peto-Peto weighting to emphasize early differences:

# Peto-Peto: rho=1 gives more weight to early event times
gw.trend_test(y, group=lung["ph.ecog"], rho=1, gamma=0)

TestResult(method='G-rho trend test (rho=1, gamma=0)', statistic=11.2013, df=1, p_value=0.0008174)

Use Tarone-Ware weighting to emphasize late differences (gamma=1):

# Tarone-Ware: gamma=1 gives more weight to late event times
gw.trend_test(y, group=lung["ph.ecog"], rho=0, gamma=1)

TestResult(method='G-rho trend test (rho=0, gamma=1)', statistic=4.4611, df=1, p_value=0.03468)

Stratified by sex to control for a confounder:

# Stratify by sex to adjust for a known confounder
gw.trend_test(y, group=lung["ph.ecog"], strata=lung["sex"])

TestResult(method='Stratified linear trend test', statistic=10.9057, df=1, p_value=0.0009587)