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

pip install competing-risk-sensitivity

Command-line use

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

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:

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:

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

License

MIT