EventTable

Per-time risk-set tabulation (optionally within strata).

Usage

EventTable(
    time,
    n_risk,
    n_event,
    n_censor,
    strata=None,
)

Every array is aligned row-wise. When strata is not None, rows are grouped by stratum (each stratum’s times are ascending). Counts are weighted when case weights are supplied, so they may be floats.

Attributes

time: Array: Unique exit times at which events or censorings occur, in ascending order within each stratum. Shape (k,) where k is the total number of unique exit times across all strata.
n_risk: Array: Number of subjects (or total weight) in the risk set at each time. A subject is at risk at time t if they entered before t and have not yet exited. Shape (k,).
n_event: Array: Number of events (or total event weight) at each time. Shape (k,).
n_censor: Array: Number of censorings (or total censoring weight) at each time. Shape (k,).
strata: Array | None: Stratum labels for each row, or None when no stratification is used. When present, the arrays are grouped by stratum (each stratum’s times are ascending). Shape (k,).

Examples

An EventTable is produced by event_table. Build one from the bundled lung dataset and view it as a Polars frame with to_frame.

import greenwood as gw

# Load data and name the response columns
lung = gw.load_dataset("lung", backend="polars")
death = gw.Outcome.surv(time="time", event="status")

# Tabulate the risk set at each event time
et = gw.event_table(death, data=lung)
et.to_frame(format="polars")

shape: (186, 5)

strata	time	n_risk	n_event	n_censor
str	f64	f64	f64	f64
"all"	5.0	228.0	1.0	0.0
"all"	11.0	227.0	3.0	0.0
"all"	12.0	224.0	1.0	0.0
"all"	13.0	223.0	2.0	0.0
"all"	15.0	221.0	1.0	0.0
…	…	…	…	…
"all"	840.0	5.0	0.0	1.0
"all"	883.0	4.0	1.0	0.0
"all"	965.0	3.0	0.0	1.0
"all"	1010.0	2.0	0.0	1.0
"all"	1022.0	1.0	0.0	1.0

Methods

Name	Description
to_frame()	Return the tabulation as a DataFrame.

to_frame()

Return the tabulation as a DataFrame.

Usage

Source

to_frame(
    *,
    format=None,
)

Exports the event-table rows with one row per unique exit time and columns for the risk set, events, censorings, and optional strata labels.

Parameters

format: str | None = None: Output format: None (default), "pandas", "polars", or "pyarrow". When None, a backend is auto-detected (Polars, then Pandas, then PyArrow).

Returns

pandas.DataFrame, polars.DataFrame, or pyarrow.Table: A tidy table containing time, n_risk, n_event, n_censor, and optionally strata.

Raises

ImportError: If the requested (or, when auto-detecting, any) DataFrame library is not installed.

Examples

Build an event table from the bundled lung dataset and convert it to a Polars frame for inspection or downstream analysis:

import greenwood as gw

# Load data and name the response columns
lung = gw.load_dataset("lung", backend="polars")
death = gw.Outcome.surv(time="time", event="status")
et = gw.event_table(death, data=lung)

# Export the event table as a Polars DataFrame
et.to_frame(format="polars")

shape: (186, 5)

strata	time	n_risk	n_event	n_censor
str	f64	f64	f64	f64
"all"	5.0	228.0	1.0	0.0
"all"	11.0	227.0	3.0	0.0
"all"	12.0	224.0	1.0	0.0
"all"	13.0	223.0	2.0	0.0
"all"	15.0	221.0	1.0	0.0
…	…	…	…	…
"all"	840.0	5.0	0.0	1.0
"all"	883.0	4.0	1.0	0.0
"all"	965.0	3.0	0.0	1.0
"all"	1010.0	2.0	0.0	1.0
"all"	1022.0	1.0	0.0	1.0

Request a different backend with format=:

# Export as a Pandas DataFrame instead
et.to_frame(format="pandas")

	strata	time	n_risk	n_event	n_censor
0	all	5.0	228.0	1.0	0.0
1	all	11.0	227.0	3.0	0.0
2	all	12.0	224.0	1.0	0.0
3	all	13.0	223.0	2.0	0.0
4	all	15.0	221.0	1.0	0.0
...	...	...	...	...	...
181	all	840.0	5.0	0.0	1.0
182	all	883.0	4.0	1.0	0.0
183	all	965.0	3.0	0.0	1.0
184	all	1010.0	2.0	0.0	1.0
185	all	1022.0	1.0	0.0	1.0

186 rows × 5 columns