event_table()

Tabulate the event history: risk sets and events at each observed time.

Usage

Source

event_table(
    surv,
    *,
    group=None,
    weights=None,
)

Creates a structured summary of the survival data at each unique event time. The table shows how many subjects were at risk, how many experienced events, and how many were censored at each time point. This is the foundational data structure used by non-parametric estimators (Kaplan-Meier, Nelson-Aalen) and the log-rank test.

Uses:

  • Verification: Inspect risk sets to understand data structure and check for censoring patterns.
  • Manual calculations: Compute survival estimates, cumulative event rates, or other summaries directly from the risk-set counts.
  • Understanding censoring: See censoring patterns by time and stratification.
  • Reporting: Present summary tables in publications (common in clinical trials).

Parameters

surv: Surv

A Surv response (time-to-event data). Supports right-censored or counting-process format. Weighted responses are supported; weights are incorporated into risk-set counts.

group: Any = None

Optional grouping variable for stratification, one value per subject. Can be a Pandas/Polars series, 1-D array, or Python sequence. When provided, the table is split into blocks with a strata column, one group per block. Groups appear in order of first appearance in the data.

weights: Any = None
Optional case weights. Can be a 1-D array or series. If None (default), uses weights from the surv response if present, otherwise treats all subjects as weight 1.

Returns

EventTable

A structured result with the following attributes:

  • time: Unique event times (ascending, per stratum if grouped).
  • n_risk: Weighted number of subjects at risk (alive/uncensored and under follow-up) at each time.
  • n_event: Weighted number of events at each time.
  • n_censor: Weighted number of censored subjects at each time.
  • strata (if grouped): Stratum label for each row.
Access columns via .to_frame() (optionally format=), or iterate directly.

Details

Risk-set definition: At time \(t\), subjects “at risk” are those with:

  • Entry time \(\le t\) (for counting-process data)
  • Exit time \(> t\) (not yet having an event or censoring)

For right-censored data, entry is always 0, so the condition simplifies.

Censoring and events at the same time: Subjects censored at time t are handled carefully. A subject censored at exactly time t is at risk for any event at t (following convention in survival analysis). The table counts them in n_risk at time t, but removes them from n_risk at times > t.

Stratification order: If grouped, strata appear in the order of first appearance in the input data, not alphabetically. This allows meaningful orderings (e.g., control, then treatment).

Weights: If weights are provided, all counts (n_risk, n_event, n_censor) are sums of weights, not subject counts. This handles case weights or frequency weights.

Examples

View the basic event table for the lung dataset: how many subjects are at risk, events, and censoring at each time.

import greenwood as gw

lung = gw.load_dataset("lung", backend="polars")
y = gw.Surv.right(lung["time"], event=(lung["status"] == 2))
et = gw.event_table(y)
et.to_frame(format="polars").head(10)
shape: (10, 4)
timen_riskn_eventn_censor
f64f64f64f64
5.0228.01.00.0
11.0227.03.00.0
12.0224.01.00.0
13.0223.02.00.0
15.0221.01.00.0
26.0220.01.00.0
30.0219.01.00.0
31.0218.01.00.0
53.0217.02.00.0
54.0215.01.00.0

The first row shows the first event time: how many subjects were at risk, how many experienced an event, and how many were censored. Note that n_risk decreases over time as subjects leave the risk set (events or censoring).

Stratify by sex to see event patterns for each group separately:

et_sex = gw.event_table(y, group=lung["sex"])
et_sex.to_frame(format="polars").head(15)
shape: (15, 5)
stratatimen_riskn_eventn_censor
objectf64f64f64f64
111.0138.03.00.0
112.0135.01.00.0
113.0134.02.00.0
115.0132.01.00.0
126.0131.01.00.0
……………
160.0124.01.00.0
165.0123.02.00.0
171.0121.01.00.0
181.0120.01.00.0
188.0119.02.00.0

Now each unique time appears twice (once per stratum) with a strata column indicating the group. This is useful for inspecting whether event rates and censoring patterns differ by group.

Compute a manual survival estimate from risk-set counts. The survival probability at time \(t\) is the product of (1 - n_event / n_risk) over all times \(\le t\):

import numpy as np
et = gw.event_table(y)
df = et.to_frame(format="pandas")
# Kaplan-Meier survival at each time
df["surv"] = np.cumprod(1 - df["n_event"] / df["n_risk"])
df[["time", "n_risk", "n_event", "surv"]].head(10)
time n_risk n_event surv
0 5.0 228.0 1.0 0.995614
1 11.0 227.0 3.0 0.982456
2 12.0 224.0 1.0 0.978070
3 13.0 223.0 2.0 0.969298
4 15.0 221.0 1.0 0.964912
5 26.0 220.0 1.0 0.960526
6 30.0 219.0 1.0 0.956140
7 31.0 218.0 1.0 0.951754
8 53.0 217.0 2.0 0.942982
9 54.0 215.0 1.0 0.938596

This manual calculation matches the Kaplan-Meier estimate from KaplanMeier().fit().