survinsights is a Python framework for interpreting survival models, with support for static and longitudinal covariates, dynamic prediction settings, and Shapley-based explainability methods.

This repository provides general-purpose tools for survival model interpretation and also contains experimental code accompanying specific research papers.

survinsights is designed to support:

• Model-agnostic explanation of survival predictions
• Longitudinal and time-updated covariates
• Local (individual-level) and global (population-level) explanations
• Dynamic prediction scenarios where explanations evolve over time

The framework can be used independently of any specific publication.

This repository partially accompanies the paper:

DynSurvX: Time-Resolved Explanations for Dynamic Survival Predictions

Only a subset of the codebase is used for this paper.
In particular, the paper focuses on a Shapley-based explanation method implemented within the survinsights framework, referred to as DynSurvX.

DynSurvX is an experimental method that:

• Explains survival models with longitudinal covariates
• Attributes predictions to both feature values and time intervals
• Supports real-time explanations as new observations become available

These capabilities are implemented on top of the general survinsights infrastructure.

The following components are used to reproduce the results reported in the DynSurvX paper:

• src/survinsights/local_explaination/_survlongishap/
  Core implementation of DynSurvX (longitudinal SHAP explanations)

• src/survinsights/longi_prediction.py
  Utilities for dynamic survival prediction

• examples/learner/
  Survival models used in the paper (CoxSig, Dynamic DeepHit)

• examples/data/
  Simulated and clinical datasets

• (dataset)_(mean|med)_(model).py
  Scripts to generate explanations using:

  • Expected remaining survival time (mean)
  • Median residual survival time (median)

• (dataset)_figure_reproduce/*.ipynb
  Jupyter notebooks to reproduce figures reported in the paper

• PBCseq
  Publicly available via the R package JMbayes

• MSK-Chord
  Available through the cBioPortal platform
  (data access approval required)

Simulated datasets are included in the repository and are used to:

• Validate temporal attribution accuracy
• Study robustness to prediction targets
• Provide ground-truth temporal importance patterns

Beyond the DynSurvX paper, the tutorial notebooks tutorial_(dataset)_(mean|med)_(model).ipynb demonstrating how to use survinsights for:

• Longitudinal survival prediction
• Feature attribution
• Dynamic explanations

virtualenv -p python3.12 .venv_survinsights
source .venv_survinsights/bin/activate
pip install -r pip_requirements.txt