CensoringDistribution

Kaplan-Meier estimate of the censoring distribution, providing IPC weights.

Usage

CensoringDistribution(surv)

The censoring distribution \hat{G}(t) = P(\text{not censored by time } t) is the Kaplan-Meier estimator applied to the censoring process (where censoring is treated as the “event” and true events are treated as censoring). This is the foundation of all IPCW methods.

IPC weights w_i = 1 / \hat{G}(t_i^-) reweight observed subjects to represent the full population, correcting for the information lost to censoring. Subjects who experienced an event at a time when censoring was heavy receive larger weights (they represent more unobserved subjects), while subjects at times with little censoring receive weights near 1.

Parameters

surv: Surv: A right-censored Surv response. The censoring distribution is estimated from the observed censoring pattern.

Examples

Estimate the censoring distribution for the lung dataset:

import greenwood as gw

lung = gw.load_dataset("lung", backend="polars")

# Build the response from the named columns, then fit the censoring distribution
y = gw.Outcome.surv(time="time", event="status").bind(lung)
cens = gw.CensoringDistribution(y)
cens

CensoringDistribution (n=228, censored=63)
  60 unique censoring times, tail G = 0.0000

Retrieve IPC weights for all subjects:

# IPC weights: larger where censoring is heavier
weights = cens.weights()
weights[:10]

array([1.35885572, 1.59245456, 0.        , 1.09235351, 3.8210638 ,
       0.        , 1.35885572, 1.41273529, 1.10044502, 1.01015385])

Methods

Name	Description
survival()	Evaluate the censoring survival function \hat{G}(t) at arbitrary times.
survival_left()	Evaluate \hat{G}(t^-), the left-continuous censoring survival.
to_frame()	Return the censoring survival curve as a DataFrame.
weights()	IPC weights w_i = \delta_i / \hat{G}(t_i^-) for each subject.

survival()

Evaluate the censoring survival function \hat{G}(t) at arbitrary times.

Usage

Source

survival(times)

Returns the probability of not being censored by each requested time, estimated via the Kaplan-Meier estimator of the censoring distribution.

Parameters

times: Any: 1-D array-like of query times.

Returns

ndarray: \hat{G}(t) at each query time, shape (len(times),).

Examples

Evaluate the probability of remaining uncensored at one year and two years:

import greenwood as gw

lung = gw.load_dataset("lung", backend="polars")
y = gw.Outcome.surv(time="time", event="status").bind(lung)

cens = gw.CensoringDistribution(y)
cens.survival([365, 730])

array([0.69728182, 0.49350505])

survival_left()

Evaluate \hat{G}(t^-), the left-continuous censoring survival.

Usage

Source

survival_left(times)

This is the censoring survival just before each time point, used for IPC weight construction. At the first observation time, \hat{G}(t^-) = 1.

Parameters

times: Any: 1-D array-like of query times.

Returns

ndarray: \hat{G}(t^-) at each query time, shape (len(times),).

Examples

The left-continuous version evaluates the censoring survival just before each time point, which is what IPC weights use as denominator:

import greenwood as gw

lung = gw.load_dataset("lung", backend="polars")
y = gw.Outcome.surv(time="time", event="status").bind(lung)

cens = gw.CensoringDistribution(y)
cens.survival_left([365, 730])

array([0.69728182, 0.49350505])

to_frame()

Return the censoring survival curve as a DataFrame.

Usage

Source

to_frame(
    *,
    format=None,
)

Parameters

format: str | None = None: Output format: None (default), "pandas", "polars", or "pyarrow".

Returns

DataFrame: Columns: time, survival.

Examples

Export the full censoring survival curve as a Polars DataFrame:

import greenwood as gw

lung = gw.load_dataset("lung", backend="polars")
y = gw.Outcome.surv(time="time", event="status").bind(lung)

cens = gw.CensoringDistribution(y)
cens.to_frame(format="polars")

shape: (60, 2)

time	survival
f64	f64
92.0	0.995025
105.0	0.989948
173.0	0.984091
174.0	0.978233
175.0	0.972375
…	…
821.0	0.327134
840.0	0.261707
965.0	0.174471
1010.0	0.087236
1022.0	0.0

weights()

IPC weights w_i = \delta_i / \hat{G}(t_i^-) for each subject.

Usage

Source

weights(
    *,
    tau=None,
)

Uncensored subjects receive weight 1 / \hat{G}(t_i^-). Censored subjects receive weight 0 (they are excluded from the reweighted analysis). Subjects with events after tau also receive weight 0.

Parameters

tau: float | None = None: Truncation time. Subjects with event times after tau receive zero weight. Defaults to the maximum observed time.

Returns

ndarray: IPC weights, shape (n,).