Plotting

tausurv.plot draws the figures of a survival analysis with matplotlib. Every function returns a Display dataclass holding the figure, the axes and the artists it created, so the figure can be changed afterwards with plain matplotlib.

What’s in the module

Plot	Function	When
Kaplan-Meier curves	ts.plot.km	Marginal / per-group survival from raw data
Cumulative incidence (lines)	ts.plot.cif	Competing risks, one cause per line
Cumulative incidence (stacked)	ts.plot.stacked_cif	Cohort decomposition, stacks to 1
Predicted survival	ts.plot.predicted_survival	$\hat S(t \mid x)$ for one or many subjects
Risk stratification	ts.plot.risk_strata	KM by quantile of a continuous risk score
Forest plot	ts.plot.forest	Coefficients / hazard ratios with CIs
Calibration	ts.plot.calibration	Predicted vs observed at a horizon
AUC / C / Brier over time	ts.plot.auc_over_time etc.	Evaluation curves with CV-fold bands
Copula diagnostics	ts.plot.copula.contour etc.	Joint CDF, density, samples
SHAP for survival	ts.plot.shap.curves etc.	Time-varying feature attributions

Levels of use

Every plot can be used at three levels, with the same parameter names:

1. One call: ts.plot.km(event_time, event_indicator, group=arm) draws the figure and returns a Display.
2. The Display: it carries .fig, .ax and plot-specific handles (.lines, .ci_polys, .at_risk_ax, …) for changing single elements.
3. Matplotlib: .ax is an ordinary Axes.

Shared conventions

• Each function returns a <Name>Display dataclass, never a raw Axes.
• Standard parameter names: ax, ci, ci_level, legend, xlabel, ylabel, title, color, label. Same defaults across plots.
• Comparisons: group= for splitting raw subject data; models= for precomputed per-model overlays; a (n_estimates, n_times) values array for a mean and spread band over folds, resamples or runs.
• Visual constants: CI bands at alpha=0.18, no edge, colour matched to the line. Reference lines at #888888, dashed, lw=0.6, alpha=0.6. Survival step plots use where="post". Legends are frameless.
• Style: every plot picks up the active rcParams. Apply ts.plot.set_style("publication") once at the top of an analysis; plots never touch the style themselves.
• Lazy import: import tausurv does not load matplotlib. Matplotlib loads lazily when the first plotting function is called.

Pages in this section

• Gallery: every plot, with the minimal code that draws it.
• Styling: the four named styles, palette choices, font fallbacks, and how to override.