survival-analysis-tools 0.1.1__tar.gz

survival_analysis_tools-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dina Daitchman
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

survival_analysis_tools-0.1.1/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: survival_analysis_tools
+Version: 0.1.1
+Summary: Survival analysis helpers: Kaplan–Meier plots and Cox HR utilities.
+Author-email: Dina Daitchman <ddaitchman@novocure.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: pandas>=1.3
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: lifelines>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# survival_analysis_tools
+
+Kaplan–Meier plotting and Cox HR helpers for survival analysis workflows.
+
+## Install
+
+```bash
+pip install survival_analysis_tools
+```
+
+From TestPyPI:
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ survival_analysis_tools
+```
+
+## Usage
+
+```python
+from survival_analysis_tools import plot_km, cox_over_df
+
+summary, hr, pval = plot_km(
+    df,
+    time_col="survival",
+    event_col="event",
+    group_col="usage_bin",
+)
+```
+
+## Development
+
+```powershell
+pip install -e ".[dev]"
+python -m pytest
+python -m build
+```
+
+## Publishing
+
+See [PUBLISHING.md](PUBLISHING.md) for TestPyPI and production PyPI upload steps with twine.

survival_analysis_tools-0.1.1/README.md

@@ -0,0 +1,40 @@
+# survival_analysis_tools
+
+Kaplan–Meier plotting and Cox HR helpers for survival analysis workflows.
+
+## Install
+
+```bash
+pip install survival_analysis_tools
+```
+
+From TestPyPI:
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ survival_analysis_tools
+```
+
+## Usage
+
+```python
+from survival_analysis_tools import plot_km, cox_over_df
+
+summary, hr, pval = plot_km(
+    df,
+    time_col="survival",
+    event_col="event",
+    group_col="usage_bin",
+)
+```
+
+## Development
+
+```powershell
+pip install -e ".[dev]"
+python -m pytest
+python -m build
+```
+
+## Publishing
+
+See [PUBLISHING.md](PUBLISHING.md) for TestPyPI and production PyPI upload steps with twine.

survival_analysis_tools-0.1.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "survival_analysis_tools"
+version = "0.1.1"
+description = "Survival analysis helpers: Kaplan–Meier plots and Cox HR utilities."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Dina Daitchman", email = "ddaitchman@novocure.com" }]
+license = { text = "MIT" }
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+
+dependencies = [
+  "numpy>=1.20",
+  "pandas>=1.3",
+  "matplotlib>=3.5",
+  "lifelines>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "build>=1.0",
+  "twine>=4.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

survival_analysis_tools-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

survival_analysis_tools-0.1.1/src/survival_analysis_tools/__init__.py

@@ -0,0 +1,12 @@
+from survival_analysis_tools.plot_km import cox_over_df, plot_km
+
+
+def hello(name: str = "world") -> str:
+    return f"Hello, {name} from survival_analysis_tools!"
+
+
+__all__ = [
+    "hello",
+    "cox_over_df",
+    "plot_km",
+]

survival_analysis_tools-0.1.1/src/survival_analysis_tools/plot_km.py

@@ -0,0 +1,379 @@
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+import warnings
+
+from lifelines import KaplanMeierFitter, CoxPHFitter
+from lifelines.plotting import add_at_risk_counts
+
+
+def cox_over_df(
+    df,
+    time_col='survival',
+    event_col='event',
+    group_col='usage_bin',
+    weights_col=None,
+    cluster_col=None,
+    robust=False,
+):
+    """
+    Computes HR, 95% CI, and p-value from Cox proportional-hazards model, optionally using weights and robust variance clustering.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+    time_col : str
+    event_col : str
+    group_col : str
+    weights_col : str or None
+        Optional column of weights.
+    cluster_col : str or None
+        Optional column for robust variance clustering. If provided, passed as cluster_col to lifelines' CoxPHFitter.
+
+    Returns
+    -------
+    list: [HR, pval, ci_low, ci_high]
+        HR (hazard ratio), p-value, lower 95% CI, upper 95% CI
+    """
+    # Keep only needed columns and copy
+    needed_cols = [time_col, event_col, group_col]
+    if weights_col is not None and weights_col in df.columns:
+        needed_cols.append(weights_col)
+    if cluster_col is not None and cluster_col in df.columns:
+        needed_cols.append(cluster_col)
+    X = df[needed_cols].copy()
+
+    # Coerce time to numeric
+    X[time_col] = pd.to_numeric(X[time_col], errors='coerce')
+    # Coerce event to numeric 0/1
+    X[event_col] = pd.to_numeric(X[event_col], errors='coerce')
+    # Drop rows with missing essentials
+    missing_cols = [time_col, event_col, group_col]
+    if cluster_col is not None:
+        missing_cols.append(cluster_col)
+    X = X.dropna(subset=missing_cols)
+    # Keep only valid event codes 0/1
+    X = X[X[event_col].isin([0, 1])]
+    # Exactly two groups required
+    X[group_col] = X[group_col].astype('category')
+    if X[group_col].nunique() != 2 or len(X) < 2:
+        return [np.nan, np.nan, np.nan, np.nan]
+
+    try:
+        cph = CoxPHFitter()
+        fit_kwargs = dict(
+            duration_col=time_col,
+            event_col=event_col,
+            formula=f"C({group_col})",
+            robust=robust
+        )
+        if weights_col is not None and weights_col in X.columns:
+            fit_kwargs["weights_col"] = weights_col
+        if cluster_col is not None and cluster_col in X.columns:
+            fit_kwargs["cluster_col"] = cluster_col
+        cph.fit(X, **fit_kwargs)
+        # With 2 groups there is a single coefficient row
+        row = cph.summary.iloc[0]
+        HR = row["exp(coef)"]
+        pval = row["p"]         # Wald test p-value from the Cox model
+        ci_low = row.get("exp(coef) lower 95%", np.nan)
+        ci_high = row.get("exp(coef) upper 95%", np.nan)
+        return [HR, pval, ci_low, ci_high]
+    except Exception:
+        return [np.nan, np.nan, np.nan, np.nan]
+
+
+def median_ci(fitter):
+    """
+    Returns (lower, upper) time values such that survival probability 95% CI crosses 0.5.
+    """
+    try:
+        ci = fitter.confidence_interval_
+        times = ci.index
+        lower, upper = ci.iloc[:, 0], ci.iloc[:, 1]
+        l = times[lower < 0.5][0] if any(lower < 0.5) else np.nan
+        h = times[upper < 0.5][0] if any(upper < 0.5) else np.nan
+        return l, h
+    except Exception:
+        return np.nan, np.nan
+
+
+def fmt(m, ci):
+    if not np.isfinite(m): return "NA"
+    l, h = ci
+    if np.isfinite(l) and np.isfinite(h): return f"{m:.1f} [{l:.1f}-{h:.1f}]"
+    if np.isfinite(l): return f"{m:.1f} [{l:.1f}-NA]"
+    if np.isfinite(h): return f"{m:.1f} [NA-{h:.1f}]"
+    return f"{m:.1f}"
+
+
+def plot_km(
+    df,
+    time_col="survival",
+    event_col="event",
+    group_col="usage_bin",
+    group_order=None,
+    show_censors=True,
+    show_ci=True,
+    show_at_risk=True,
+    xlabel='Time [months]',
+    ylabel="Survival probability",
+    title="Survival probability vs. Usage Bin",
+    font_scale: float = 1.3,
+    plot_height=5,
+    xlim=False,
+    show_stats=True,
+    ax=None,
+    show=True,
+    weights_col=None,
+    cluster_col=None,
+    robust=False,
+    created_fig=True,
+    flip_legend_order=False
+):
+    """
+    Plot Kaplan-Meier curves grouped by `group_col`. If group_col is None, plot KM for all data.
+
+    Now returns a DataFrame with cols: group_name, n, median, median_ci_low, median_ci_high.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Dataframe containing the survival data.
+    time_col : str
+        Column for durations.
+    event_col : str
+        Column for event indicators.
+    group_col : str or None
+        Column for group assignment (if None, all data is treated as one group).
+    group_order : list, optional
+        List controlling the plotting order for groups.
+    show_censors : bool
+        Show censors (default True).
+    show_ci : bool
+        Show confidence intervals.
+    show_at_risk : bool
+        Add at-risk counts table.
+    xlabel, ylabel, title : str
+        Plot labels.
+    font_scale : float
+        Font scaling.
+    plot_height : float
+        Figure height.
+    xlim : float or False
+        X-axis upper bound.
+    show_stats : bool
+        Whether to show HR/p-value on plot.
+    ax : matplotlib Axes, optional
+        Axes to plot into.
+    show : bool
+        Whether to call plt.show().
+    weights_col : str or None
+        Optional column of weights to use in fitting KM curves, Cox model, and logrank test.
+    flip_legend_order : bool
+        If True, reverse the legend order.
+    robust : bool
+        Set 'robust' parameter when calling CoxPHFitter. Default False.
+    """
+
+    created_fig = False
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(8, plot_height))
+        created_fig = True
+
+    rows = []
+    fitters = []
+
+    if group_col is None:
+        # All one group; just plot one KM curve
+        kmf = KaplanMeierFitter(label="All")
+        fit_args = dict(
+            durations=df[time_col],
+            event_observed=df[event_col],
+        )
+        if weights_col is not None and weights_col in df.columns:
+            fit_args["weights"] = df[weights_col]
+        # lifelines <=0.27.5 emits warning if any weights==0, so filter those out
+        if weights_col is not None and weights_col in df.columns:
+            mask = (df[weights_col] > 0)
+            # If all weights are zero, skip plotting
+            if mask.sum() == 0:
+                # No data to plot
+                if created_fig and show:
+                    plt.tight_layout()
+                    plt.show()
+                return pd.DataFrame([])
+            for k in ["durations", "event_observed", "weights"]:
+                fit_args[k] = fit_args[k][mask]
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            kmf.fit(**fit_args)
+        kmf.plot(
+            ax=ax,
+            ci_show=show_ci,
+            lw=2,
+            show_censors=show_censors,
+            censor_styles={'ms': 6, 'marker': '+'}
+        )
+        med = kmf.median_survival_time_
+        median_low, median_high = median_ci(kmf)
+        fitters.append(kmf)
+
+        if weights_col is not None and weights_col in df.columns:
+            n = float(df[weights_col].sum())
+        else:
+            n = int(df.shape[0])
+
+        rows.append({
+            "group_name": "All",
+            "n": int(n),
+            "median": float(med) if np.isfinite(med) else np.nan,
+            "median_ci_low": float(median_low) if np.isfinite(median_low) else np.nan,
+            "median_ci_high": float(median_high) if np.isfinite(median_high) else np.nan,
+        })
+    else:
+        if group_order is None:
+            group_order = sorted(df[group_col].unique())
+        else:
+            group_order = [g for g in group_order if g in df[group_col].unique()]
+        for grp_name in group_order:
+            g = df[df[group_col] == grp_name]
+            if g.empty:
+                continue
+
+            kmf = KaplanMeierFitter(label=str(grp_name))
+
+            fit_args = dict(
+                durations=g[time_col],
+                event_observed=g[event_col],
+            )
+            if weights_col is not None and weights_col in g.columns:
+                fit_args["weights"] = g[weights_col]
+            if weights_col is not None and weights_col in g.columns:
+                mask = (g[weights_col] > 0)
+                if mask.sum() == 0:
+                    continue  # skip group with all zero weights
+                for k in ["durations", "event_observed", "weights"]:
+                    fit_args[k] = fit_args[k][mask]
+
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                kmf.fit(**fit_args)
+            kmf.plot(
+                ax=ax,
+                ci_show=show_ci,
+                lw=2,
+                show_censors=show_censors,
+                censor_styles={'ms': 6, 'marker': '+'}
+            )
+
+            med = kmf.median_survival_time_
+            median_low, median_high = median_ci(kmf)
+            fitters.append(kmf)
+
+            if weights_col is not None and weights_col in g.columns:
+                n = float(g[weights_col].sum())
+            else:
+                n = int(g.shape[0])
+
+            rows.append({
+                "group_name": str(grp_name),
+                "n": int(n),
+                "median": float(med) if np.isfinite(med) else np.nan,
+                "median_ci_low": float(median_low) if np.isfinite(median_low) else np.nan,
+                "median_ci_high": float(median_high) if np.isfinite(median_high) else np.nan,
+            })
+
+    # ---- cosmetics ----
+    if title is None:
+        title = f"Survival Probability" if group_col is None else f"Survival Probability by {group_col}"
+    ax.set_title(title, fontsize=16 * font_scale, weight="bold")
+    ax.set_xlabel(xlabel, fontsize=14 * font_scale)
+    ax.set_ylabel(ylabel, fontsize=14 * font_scale)
+    ax.tick_params(axis="both", labelsize=12 * font_scale)
+    ax.grid(True, ls="--", alpha=0.35)
+    ax.set_ylim(0, 1.0)
+
+    if xlim:
+        ax.set_xlim(0, xlim)
+
+    # ---- Legend with n & median ----
+    handles, labels = ax.get_legend_handles_labels()
+
+    medians = {r["group_name"]: r["median"] for r in rows}
+    cis = {r["group_name"]: (r["median_ci_low"], r["median_ci_high"]) for r in rows}
+
+    if handles:
+        if flip_legend_order:
+            handles = handles[::-1]
+            labels = labels[::-1]
+        ax.legend(
+            handles,
+            [f"{lab} (median={fmt(medians.get(lab, np.nan), cis.get(lab, (np.nan, np.nan)))})" for lab in labels],
+            fontsize=14 * font_scale,
+            loc='upper right',
+            frameon=False,
+        )
+
+    # ---- At-risk counts ----
+    if show_at_risk and fitters:
+        # lifelines' add_at_risk_counts ignores weights, so this may mismatch with weighted.
+        add_at_risk_counts(
+            *fitters,
+            ax=ax,
+            rows_to_show=['At risk'],
+            fontsize=10 * font_scale,
+        )
+
+    # ---- HR, CI & p-value (respect group_order, only if group_col provided) ----
+    if show_stats and group_col is not None and len(fitters) > 1:
+        df_cox = df.copy()
+        df_cox[group_col] = pd.Categorical(
+            df_cox[group_col],
+            categories=group_order,
+            ordered=True,
+        )
+        HR, pval, ci_low, ci_high = cox_over_df(
+            df_cox,
+            time_col=time_col,
+            event_col=event_col,
+            group_col=group_col,
+            weights_col=weights_col,
+            cluster_col=cluster_col,
+            robust=robust,  # <-- propagate robust!
+        )
+        if pd.notna(HR):
+            # p-value formatting: show <0.001 if smaller than 0.001
+            if pd.notna(pval) and pval < 0.001:
+                pval_str = "<0.001"
+            elif pd.notna(pval):
+                pval_str = f"{pval:.3g}"
+            else:
+                pval_str = "NA"
+            # CI formatting
+            if pd.notna(ci_low) and pd.notna(ci_high):
+                ci_str = f"{HR:.2f} [{ci_low:.2f}, {ci_high:.2f}]"
+            elif pd.notna(ci_low):
+                ci_str = f"{HR:.2f} [{ci_low:.2f}, NA]"
+            elif pd.notna(ci_high):
+                ci_str = f"{HR:.2f} [NA, {ci_high:.2f}]"
+            else:
+                ci_str = f"{HR:.2f}"
+
+            ax.text(
+                0.02, 0.2,
+                f"HR = {ci_str}\np = {pval_str}",
+                transform=ax.transAxes,
+                ha='left', va='top',
+                fontsize=12 * font_scale,
+                bbox=dict(
+                    boxstyle='round,pad=0.3',
+                    fc='white', ec='0.5', alpha=0.9,
+                ),
+            )
+
+    if created_fig and show:
+        plt.tight_layout()
+        plt.show()
+
+    return pd.DataFrame(rows), HR, pval

survival_analysis_tools-0.1.1/src/survival_analysis_tools.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: survival_analysis_tools
+Version: 0.1.1
+Summary: Survival analysis helpers: Kaplan–Meier plots and Cox HR utilities.
+Author-email: Dina Daitchman <ddaitchman@novocure.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: pandas>=1.3
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: lifelines>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# survival_analysis_tools
+
+Kaplan–Meier plotting and Cox HR helpers for survival analysis workflows.
+
+## Install
+
+```bash
+pip install survival_analysis_tools
+```
+
+From TestPyPI:
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ survival_analysis_tools
+```
+
+## Usage
+
+```python
+from survival_analysis_tools import plot_km, cox_over_df
+
+summary, hr, pval = plot_km(
+    df,
+    time_col="survival",
+    event_col="event",
+    group_col="usage_bin",
+)
+```
+
+## Development
+
+```powershell
+pip install -e ".[dev]"
+python -m pytest
+python -m build
+```
+
+## Publishing
+
+See [PUBLISHING.md](PUBLISHING.md) for TestPyPI and production PyPI upload steps with twine.

survival_analysis_tools-0.1.1/src/survival_analysis_tools.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/survival_analysis_tools/__init__.py
+src/survival_analysis_tools/plot_km.py
+src/survival_analysis_tools.egg-info/PKG-INFO
+src/survival_analysis_tools.egg-info/SOURCES.txt
+src/survival_analysis_tools.egg-info/dependency_links.txt
+src/survival_analysis_tools.egg-info/requires.txt
+src/survival_analysis_tools.egg-info/top_level.txt
+tests/test_hello.py

survival_analysis_tools-0.1.1/src/survival_analysis_tools.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

survival_analysis_tools-0.1.1/src/survival_analysis_tools.egg-info/requires.txt

@@ -0,0 +1,9 @@
+numpy>=1.20
+pandas>=1.3
+matplotlib>=3.5
+lifelines>=0.27
+
+[dev]
+pytest>=7.0
+build>=1.0
+twine>=4.0

survival_analysis_tools-0.1.1/src/survival_analysis_tools.egg-info/top_level.txt

@@ -0,0 +1 @@
+survival_analysis_tools

survival_analysis_tools-0.1.1/tests/test_hello.py

@@ -0,0 +1,40 @@
+import pandas as pd
+
+from survival_analysis_tools import cox_over_df, hello, plot_km
+
+
+def test_hello_default():
+    assert hello() == "Hello, world from survival_analysis_tools!"
+
+
+def test_plot_km_imports_and_runs():
+    df = pd.DataFrame(
+        {
+            "survival": [3, 5, 8, 10, 12, 15],
+            "event": [1, 1, 0, 1, 0, 1],
+            "usage_bin": ["low", "low", "low", "high", "high", "high"],
+        }
+    )
+    summary, hr, pval = plot_km(df, show=False, show_at_risk=False)
+    assert list(summary.columns) == [
+        "group_name",
+        "n",
+        "median",
+        "median_ci_low",
+        "median_ci_high",
+    ]
+    assert len(summary) == 2
+    assert pd.notna(hr)
+    assert pd.notna(pval)
+
+
+def test_cox_over_df():
+    df = pd.DataFrame(
+        {
+            "survival": [3, 5, 8, 10, 12, 15],
+            "event": [1, 1, 0, 1, 0, 1],
+            "usage_bin": ["low", "low", "low", "high", "high", "high"],
+        }
+    )
+    hr, pval, ci_low, ci_high = cox_over_df(df)
+    assert all(isinstance(x, float) for x in (hr, pval, ci_low, ci_high))