coxrmstsimpson 0.2.2__tar.gz

coxrmstsimpson-0.2.2/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+build/
+dist/
+*.egg-info/

coxrmstsimpson-0.2.2/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 Ian Forde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

coxrmstsimpson-0.2.2/PKG-INFO

@@ -0,0 +1,99 @@
+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.

coxrmstsimpson-0.2.2/README.md

@@ -0,0 +1,82 @@
+# 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.

coxrmstsimpson-0.2.2/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "coxrmstsimpson"
+version = "0.2.2"
+description = "Restricted mean survival time from Cox models using composite Simpson's rule"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Ian Forde", email = "fordeia@appstate.edu" }]
+dependencies = ["numpy>=1.23", "pandas>=1.5", "scipy>=1.10", "matplotlib>=3.6", "lifelines>=0.28"]
+
+[project.urls]
+Homepage = "https://github.com/fordeia/CoxRMSTSimpson"
+Repository = "https://github.com/fordeia/CoxRMSTSimpson"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/coxrmstsimpson"]
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "src/coxrmstsimpson",
+    "README.md",
+    "pyproject.toml",
+    "LICENSE",
+]

coxrmstsimpson-0.2.2/src/coxrmstsimpson/__init__.py

@@ -0,0 +1,6 @@
+"""RMST from Cox models using composite Simpson's rule."""
+from .core import cox_rmst, simpson_rmst
+from .plotting import plot_cox_rmst
+
+__version__ = "0.2.2"
+__all__ = ["cox_rmst", "simpson_rmst", "plot_cox_rmst"]

coxrmstsimpson-0.2.2/src/coxrmstsimpson/core.py

@@ -0,0 +1,197 @@
+"""Core restricted mean survival time calculations."""
+import numpy as np
+import pandas as pd
+from scipy.integrate import simpson
+
+
+def simpson_rmst(time, survival) -> float:
+    """Integrate survival probabilities over time using composite Simpson's rule."""
+    t = np.asarray(time, dtype=float)
+    s = np.asarray(survival, dtype=float)
+    if t.ndim != 1 or s.ndim != 1 or len(t) != len(s):
+        raise ValueError("time and survival must be 1D arrays of equal length.")
+    if len(t) < 3:
+        raise ValueError("At least three time points are required.")
+    if not np.all(np.isfinite(t)) or not np.all(np.isfinite(s)):
+        raise ValueError("time and survival must contain only finite values.")
+    if np.any(np.diff(t) <= 0):
+        raise ValueError("time must be strictly increasing.")
+    if np.any((s < 0) | (s > 1)):
+        raise ValueError("survival probabilities must lie between 0 and 1.")
+    return float(simpson(s, x=t))
+
+
+def _validate_model(model):
+    """Validate that model is a fitted lifelines CoxPHFitter."""
+    from lifelines import CoxPHFitter
+
+    if not isinstance(model, CoxPHFitter):
+        raise TypeError("model must be a fitted lifelines.CoxPHFitter.")
+    if not hasattr(model, "params_"):
+        raise ValueError("model must be fitted before calling cox_rmst().")
+
+
+def _mean_profile(model, covariates):
+    """Return the model's fitted covariate means for prediction."""
+    means = getattr(model, "_norm_mean", None)
+    if means is not None:
+        profile = means.to_dict()
+    else:
+        profile = {}
+    for name in covariates:
+        if name not in profile or not np.isfinite(profile[name]):
+            profile[name] = 0.0
+    return profile
+
+
+def cox_rmst(
+    model,
+    newdata: pd.DataFrame = None,
+    tau: float = None,
+    n_grid: int = 101,
+    *,
+    treatment: str = None,
+    labels=None,
+    title: str = None,
+    show_plot: bool = True,
+    show_rmst: bool = True,
+) -> dict:
+    """Estimate RMST from a fitted lifelines CoxPHFitter model.
+
+    Two usage patterns are supported.
+
+    Automatic binary-treatment mode:
+        cox_rmst(model, treatment="group", tau=10,
+                 labels=["Control", "Treatment"], title="RMST by group")
+
+    Existing explicit-profile mode:
+        cox_rmst(model, newdata, tau=10)
+
+    In automatic mode, ``treatment`` must be a numeric 0/1 covariate included
+    in the fitted model. Other model covariates are set to their fitted means
+    (lifelines' model normalization means). The package plots the curves by
+    default. Set ``show_plot=False`` to calculate without displaying a plot.
+
+    Parameters
+    ----------
+    model : lifelines.CoxPHFitter
+        A fitted Cox proportional hazards model.
+    newdata : pandas.DataFrame, optional
+        Explicit covariate profiles for the existing API.
+    tau : float
+        Positive restriction time.
+    n_grid : int, default 101
+        Odd number of time-grid points, at least 3.
+    treatment : str, optional
+        Name of a numeric 0/1 covariate in the fitted model. When supplied,
+        profiles for treatment=0 and treatment=1 are created automatically.
+    labels : sequence of str, optional
+        Two legend/result labels in automatic mode, or one label per row of
+        ``newdata`` in explicit-profile mode.
+    title : str, optional
+        Custom plot title.
+    show_plot : bool, default True
+        Display the plot before returning.
+    show_rmst : bool, default True
+        Include RMST values in the plot legend.
+
+    Returns
+    -------
+    dict
+        Includes ``curves`` (predicted survival curves), ``results`` (RMST
+        table), ``newdata``, ``tau``, and model metadata.
+    """
+    _validate_model(model)
+
+    if tau is None or not np.isscalar(tau) or not np.isfinite(tau) or tau <= 0:
+        raise ValueError("tau must be a positive finite number.")
+    if not isinstance(n_grid, (int, np.integer)) or isinstance(n_grid, bool) or n_grid < 3 or n_grid % 2 == 0:
+        raise ValueError("n_grid must be an odd integer >= 3.")
+
+    covariates = list(model.params_.index)
+
+    if treatment is not None:
+        if newdata is not None:
+            raise ValueError("Provide either treatment= or newdata, not both.")
+        if not isinstance(treatment, str) or treatment not in covariates:
+            raise ValueError(
+                "treatment must name a covariate included in the fitted model "
+                f"({covariates}). For automatic mode, use a numeric 0/1 covariate."
+            )
+        profile = _mean_profile(model, covariates)
+        try:
+            profile0 = dict(profile)
+            profile1 = dict(profile)
+            profile0[treatment] = 0.0
+            profile1[treatment] = 1.0
+            newdata = pd.DataFrame([profile0, profile1], columns=covariates)
+        except Exception as exc:
+            raise ValueError("Could not construct the treatment profiles.") from exc
+
+        if labels is None:
+            labels = ["Control", "Treatment"]
+        else:
+            labels = list(labels)
+            if len(labels) != 2:
+                raise ValueError("labels must contain exactly two labels.")
+        newdata.index = [str(labels[0]), str(labels[1])]
+    else:
+        if not isinstance(newdata, pd.DataFrame) or newdata.empty:
+            raise ValueError(
+                "Provide a nonempty newdata DataFrame or use treatment='binary_covariate'."
+            )
+        missing = set(covariates) - set(newdata.columns)
+        if missing:
+            raise ValueError(f"newdata is missing covariates: {sorted(missing)}")
+        newdata = newdata.loc[:, covariates].copy()
+        if labels is not None:
+            labels = list(labels)
+            if len(labels) != len(newdata):
+                raise ValueError(
+                    f"Provide one custom label for each profile ({len(newdata)} required)."
+                )
+            newdata.index = [str(label) for label in labels]
+
+    grid = np.linspace(0.0, float(tau), int(n_grid))
+    predicted = model.predict_survival_function(newdata, times=grid)
+    profile_labels = [str(x) if str(x).strip() else f"Profile {i+1}"
+                      for i, x in enumerate(newdata.index)]
+    curves, values = [], []
+    for i, label in enumerate(profile_labels):
+        surv = predicted.iloc[:, i].to_numpy(dtype=float)
+        curves.append(pd.DataFrame({
+            "time": grid,
+            "survival": surv,
+            "profile": label,
+        }))
+        values.append(simpson_rmst(grid, surv))
+
+    curve_df = pd.concat(curves, ignore_index=True)
+    results = pd.DataFrame({
+        "profile": profile_labels,
+        "tau": float(tau),
+        "RMST": values,
+    })
+    result = {
+        "model": model,
+        "newdata": newdata.copy(),
+        "tau": float(tau),
+        "time_grid": grid,
+        "curves": curve_df,
+        "results": results,
+        "treatment": treatment,
+    }
+
+    if show_plot:
+        from .plotting import plot_cox_rmst
+        ax = plot_cox_rmst(
+            result,
+            labels=profile_labels,
+            title=title,
+            show_rmst=show_rmst,
+            show=True,
+        )
+        result["ax"] = ax
+        result["figure"] = ax.figure
+
+    return result

coxrmstsimpson-0.2.2/src/coxrmstsimpson/plotting.py

@@ -0,0 +1,80 @@
+"""Plot predicted survival curves and shaded RMST areas."""
+import matplotlib.pyplot as plt
+
+
+def plot_cox_rmst(
+    result,
+    ax=None,
+    labels=None,
+    show_rmst=False,
+    title=None,
+    show=True,
+):
+    """Plot predicted survival curves and shade their RMST areas.
+
+    Parameters
+    ----------
+    result : dict
+        Result returned by cox_rmst().
+    ax : matplotlib.axes.Axes, optional
+        Existing axes on which to draw the plot.
+    labels : sequence of str, optional
+        Custom labels for profiles in the order plotted.
+    show_rmst : bool, default False
+        Include each profile's RMST estimate in the legend.
+    title : str, optional
+        Custom title. Defaults to a title containing tau.
+    show : bool, default True
+        Call matplotlib.pyplot.show() before returning.
+    """
+    if not isinstance(result, dict) or "curves" not in result or "tau" not in result:
+        raise TypeError("result must be returned by cox_rmst().")
+
+    curves = result["curves"]
+    profiles = list(curves.groupby("profile", sort=False))
+
+    if labels is not None:
+        labels = list(labels)
+        if len(labels) != len(profiles):
+            raise ValueError(
+                f"Provide one custom label for each profile ({len(profiles)} required)."
+            )
+
+    results_table = result.get("results")
+    if show_rmst:
+        if results_table is None or not {"profile", "RMST"}.issubset(results_table.columns):
+            raise ValueError("RMST results are unavailable in result['results'].")
+
+    if ax is None:
+        _, ax = plt.subplots()
+
+    for i, (profile, data) in enumerate(profiles):
+        data = data.sort_values("time")
+        curve_label = str(labels[i]) if labels is not None else str(profile)
+
+        if show_rmst:
+            matching = results_table.loc[
+                results_table["profile"] == profile, "RMST"
+            ]
+            if matching.empty:
+                raise ValueError(f"Could not find an RMST estimate for profile {profile!r}.")
+            curve_label = f"{curve_label} (RMST = {matching.iloc[0]:.3f})"
+
+        ax.plot(data["time"], data["survival"], label=curve_label)
+        ax.fill_between(data["time"], data["survival"], 0, alpha=0.18)
+
+    default_title = f"Restricted mean survival time (tau = {result['tau']:g})"
+    ax.set(
+        xlim=(0, result["tau"]),
+        ylim=(0, 1.02),
+        xlabel="Time",
+        ylabel="Predicted survival probability",
+        title=title if title is not None else default_title,
+    )
+    ax.legend()
+    ax.grid(alpha=0.25)
+
+    if show:
+        plt.show()
+
+    return ax