Metadata-Version: 2.4
Name: survival_analysis_tools
Version: 0.1.7
Summary: Survival analysis helpers: Kaplan–Meier plots and Cox HR utilities.
Author-email: dinka3737 <dinka3737@gmail.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
```

## Usage

Example from `tests/test_plot_km.ipynb`:

```python
import numpy as np
import pandas as pd

from survival_analysis_tools import plot_km

# Dummy survival data: two groups with different survival patterns
rng = np.random.default_rng(42)
n_per_group = 40

control = pd.DataFrame({
    "survival": rng.exponential(scale=8, size=n_per_group).clip(0.5, 36),
    "event": rng.binomial(1, 0.7, size=n_per_group),
    "treatment": "control",
})
treated = pd.DataFrame({
    "survival": rng.exponential(scale=14, size=n_per_group).clip(0.5, 36),
    "event": rng.binomial(1, 0.55, size=n_per_group),
    "treatment": "treated",
})

df = pd.concat([control, treated], ignore_index=True)
df.head()
```

```
    survival  event treatment
0  19.233669      1   control
1  18.689517      0   control
2  19.078088      0   control
3   2.238354      1   control
4   0.691499      0   control
```

```python
summary, hr, pval = plot_km(
    df,
    time_col="survival",
    event_col="event",
    group_col="treatment",
    group_order=["control", "treated"],
    title="Dummy KM: control vs treated",
    font_scale = 1.1,

    # default parameters:
    xlabel='Time [months]',
    ylabel="Survival probability",
    plot_height=5,
    xlim=False,
    flip_legend_order=False,

    show_censors=True,
    show_ci=True,
    show_at_risk=True,
    show_stats=True,

    weights_col=None,
    cluster_col=None
)
```

![Kaplan–Meier example: control vs treated](https://files.catbox.moe/yle0ta.png)

## Parameters

`plot_km` plots Kaplan–Meier curves grouped by `group_col`. If `group_col` is `None`, it plots KM for all data.

Returns a DataFrame with columns: `group_name`, `n`, `median`, `median_ci_low`, `median_ci_high` (plus HR and p-value).

| Parameter | Type | Description |
| --- | --- | --- |
| `df` | `pd.DataFrame` | Dataframe containing the survival data. |
| `time_col` | `str` | Column for durations (float). | 
| `event_col` | `str` | Column for event indicators (bool). |
| `group_col` | `str` or `None` | Column for group assignment (str) (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. |
| `show_stats` | `bool` | Whether to show HR/p-value on plot. |
| `xlabel`, `ylabel`, `title` | `str` | Plot labels. |
| `font_scale` | `float` | Font scaling. |
| `plot_height` | `float` | Figure height. |
| `xlim` | `float` or `False` | X-axis upper bound. |
| `flip_legend_order` | `bool` | If `True`, reverse the legend order. |
| `weights_col` | `str` or `None` | Optional column of weights (float) to use in fitting KM curves, Cox model, and logrank test. |

## 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.
