Metadata-Version: 2.5
Name: coxrmstsimpson
Version: 0.2.2
Summary: Restricted mean survival time from Cox models using composite Simpson's rule
Project-URL: Homepage, https://github.com/fordeia/CoxRMSTSimpson
Project-URL: Repository, https://github.com/fordeia/CoxRMSTSimpson
Author-email: Ian Forde <fordeia@appstate.edu>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: lifelines>=0.28
Requires-Dist: matplotlib>=3.6
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: scipy>=1.10
Description-Content-Type: text/markdown

# CoxRMSTSimpson (Python)

A Python companion to the R package [CoxRMSTSimpson](https://github.com/fordeia/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

```bash
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.

```python
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.