Metadata-Version: 2.4
Name: competing-risk-sensitivity
Version: 0.1.0
Summary: Competing-risk sensitivity analysis: cause-specific summary, Aalen-Johansen cumulative incidence, and Fine-Gray export/comparison.
Author: Kaylee
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/competing-risk-sensitivity/
Keywords: survival-analysis,competing-risks,fine-gray,aalen-johansen,biostatistics
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: lifelines>=0.27
Requires-Dist: matplotlib>=3.5
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# competing-risk-sensitivity

Sensitivity analysis for a competing event (e.g. death) alongside a primary
time-to-event outcome.

A primary survival analysis that censors at a competing event estimates the
**cause-specific hazard** of the event of interest: the instantaneous risk
among subjects who are alive and have not yet had the event. That is a
defensible choice, but it answers a different question from the
**subdistribution hazard** (Fine-Gray), which describes the cumulative
probability of the event actually being observed in the whole population,
including subjects who experience the competing event first. The two can
point in different directions for a covariate that raises the risk of both
events (e.g. advanced age): the cause-specific hazard can look small because
high-risk subjects are removed from the risk set by the competing event,
while the cumulative incidence of the event of interest in the full
population is substantial.

This package provides:

1. A cause-specific descriptive summary (event counts, competing-event
   counts, censoring, crude rates per 1,000 person-years).
2. Aalen-Johansen cumulative incidence functions for the event of interest
   and the competing event -- the non-parametric analogue of Kaplan-Meier
   under competing risks -- with a risk table and a plot.
3. An export of a design matrix, time, and competing-event status, ready for
   a Fine-Gray subdistribution hazard model in R via the `cmprsk` package.
   (There is no maintained Fine-Gray implementation in Python -- lifelines,
   scikit-survival and statsmodels all lack one -- so the regression itself
   is fitted in R.)
4. A comparison of cause-specific Cox coefficients against Fine-Gray
   subdistribution coefficients, once the R step has been run, to check
   whether conclusions change under a subdistribution model.

Event-status convention used throughout: `0` = censored, `1` = event of
interest, `2` = competing event.

## Install

```bash
pip install competing-risk-sensitivity
```

## Command-line use

```bash
competing-risk-sensitivity \
    --raw-file data_raw_with_dates.tsv \
    --train-file X_train_model.tsv \
    --out-dir ./results \
    --time-col time \
    --status-col CompetingEventStatus \
    --id-col PPID \
    --event-label "relapse" \
    --competing-label "death"
```

Only `--raw-file` and `--out-dir` are required; the Fine-Gray export step is
skipped if `--train-file` is omitted. Run `competing-risk-sensitivity --help`
for all options.

## Library use

```python
import pandas as pd
from competing_risk_sensitivity import (
    cause_specific_summary,
    aalen_johansen_cif,
    finegray_export,
    compare_cause_specific_vs_subdistribution,
)

df = pd.read_csv("data_raw_with_dates.tsv", sep="\t")

cause_specific_summary(df["time"], df["status"], out="summary.txt")
aalen_johansen_cif(df["time"], df["status"], out_prefix="results/aj")

X_train = pd.read_csv("X_train_model.tsv", sep="\t", index_col=0)
finegray_export(X_train, df["time"], df["status"], "results/finegray_input.tsv")
```

Then in R:

```r
d   <- read.delim("results/finegray_input.tsv")
cov <- as.matrix(d[, setdiff(names(d), c("time", "status"))])
fit <- cmprsk::crr(d$time, d$status, cov, failcode = 1, cencode = 0)
summary(fit)
```

Finally, compare the cause-specific Cox model against the Fine-Gray fit:

```python
compare_cause_specific_vs_subdistribution(
    "cox_coefficients.tsv", "finegray_coefficients.tsv", out="comparison.tsv",
)
```

## License

MIT
