plot_survival()

Plot Kaplan-Meier survival curve(s) with Altair.

Usage

Source

plot_survival(
    km,
    *,
    conf_int=True,
    censor_marks=True,
    risk_table=False,
    times=None,
    xlab="Time",
    ylab="Survival probability",
    width=500,
    height=300
)

Renders one or more Kaplan-Meier survival curves as an interactive Vega-Lite chart. Each curve shows the proportion of subjects surviving (event-free) over time as a right-continuous step function, with an optional shaded confidence band and censoring marks. Stratified fits produce one colored curve per group with a legend.

The result is a composable Altair object: layer, facet, or restyle it with Altair’s API, and it renders interactively (tooltips and zoom) in notebooks and browsers. Pass risk_table=True to stack an aligned numbers-at-risk table beneath the curve (the x-axis scale is shared). Requires Altair (install with pip install greenwood[altair]).

Parameters

km: KaplanMeier

A fitted KaplanMeier object, unstratified (single curve) or stratified.

conf_int: bool = True

If True (default), draw the point-wise confidence band as a shaded step area.

censor_marks: bool = True

If True (default), mark censoring times with + symbols on the curve.

risk_table: bool = False

If True, return an alt.VConcatChart stacking the curve over an aligned numbers-at-risk table. If False (default), return only the curve.

times: Any = None

Query times for the numbers-at-risk table (used only if risk_table=True). Defaults to six evenly spaced, rounded times from 0 to the maximum observed follow-up time.

xlab: str = "Time"

Axis labels (defaults "Time" and "Survival probability").

ylab: str = "Time"

Axis labels (defaults "Time" and "Survival probability").

width: int = 500

Curve dimensions in pixels (defaults 500 x 300).

height: int = 500
Curve dimensions in pixels (defaults 500 x 300).

Returns

An alt.LayerChart (or an alt.VConcatChart combining the curve and table if
risk_table=True).

Examples

import greenwood as gw

lung = gw.load_dataset("lung", backend="polars")
y = gw.Surv.right(lung["time"], event=(lung["status"] == 2))
km = gw.KaplanMeier().fit(y, by=lung["sex"])

gw.viz.altair.plot_survival(km, risk_table=True)