CoxRMSTSimpson (Python)

A Python companion to the R package CoxRMSTSimpson. It predicts survival curves from a fitted lifelines.CoxPHFitter, estimates restricted mean survival time (RMST) using composite Simpson's rule, and plots survival curves with shaded areas.

Development status: This package is under development. Validate numerical results against the R implementation before assuming numerical equivalence.

Install

python -m pip install coxrmstsimpson

Example

The following example simulates survival data, fits a Cox proportional hazards model, estimates RMST up to time (\tau=10), and plots two predicted survival curves.

import numpy as np
import pandas as pd
from lifelines import CoxPHFitter
from coxrmstsimpson import cox_rmst, plot_cox_rmst

# Simulate reproducible survival data.
np.random.seed(42)
n = 200

group = np.random.binomial(1, 0.5, n)
event_time = np.random.exponential(
    scale=1 / (0.10 * np.exp(0.4 * group))
)
censor_time = np.random.exponential(scale=15, size=n)

df = pd.DataFrame({
    "time": np.minimum(event_time, censor_time),
    "status": (event_time <= censor_time).astype(int),
    "group": group,
})

# Fit the Cox proportional hazards model.
cph = CoxPHFitter()
cph.fit(df, duration_col="time", event_col="status")

# Define the two covariate profiles to compare.
profiles = pd.DataFrame({"group": [0, 1]})

# Estimate RMST up to tau = 10.
result = cox_rmst(cph, profiles, tau=10, n_grid=101)
print(result["results"])

# Plot survival curves with RMST estimates in the legend.
ax = plot_cox_rmst(
    result,
    labels=["Control", "Treatment"],
    show_rmst=True,
)

In this example, status is 1 when the event occurs and 0 for right-censored observations. For your own data, use the covariates and encodings used to fit your Cox model. Each row of profiles specifies a covariate profile to evaluate, and the labels are supplied in the same order.

Functions

• simpson_rmst(time, survival): Integrates a supplied survival curve using composite Simpson's rule.
• cox_rmst(model, newdata, tau, n_grid=101): Predicts survival curves from a fitted Cox model and estimates RMST up to tau.
• plot_cox_rmst(result, ax=None, labels=None, show_rmst=False): Plots predicted survival curves and shades the areas beneath them. Use labels for custom profile labels and show_rmst=True to include RMST estimates in the legend.

Definition

Restricted mean survival time up to time (\tau) is the area under the survival function from 0 to (\tau):

[ \operatorname{RMST}(\tau)=\int_0^\tau S(t),dt. ]

Here, (S(t)) is the predicted survival probability at time (t).

Numerical note

lifelines interpolates predicted survival probabilities at requested times not already on its prediction timeline. This can differ from the step-function evaluation commonly used by R's survival::survfit. Cross-language validation is therefore needed before claiming exact numerical equivalence.

Requirements

Python 3.10 or later. Dependencies, including NumPy, pandas, SciPy, Matplotlib, and lifelines, are installed automatically by pip.