Metadata-Version: 2.4
Name: kesurv
Version: 0.1.0
Summary: Kernel ensemble survival estimation with forest neighborhoods
Author: Rahul Goswami
License-Expression: MIT
Project-URL: Homepage, https://kesurv.statml.in
Project-URL: Documentation, https://kesurv.statml.in
Project-URL: Source, https://github.com/yuvrajiro/kesurv
Project-URL: Issues, https://github.com/yuvrajiro/kesurv/issues
Keywords: survival analysis,random survival forest,kaplan-meier,ensemble,scikit-survival
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scikit-survival>=0.22
Provides-Extra: speed
Requires-Dist: numba>=0.59; extra == "speed"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: numba>=0.59; extra == "test"
Requires-Dist: pandas>=1.5; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx<9,>=7.2; extra == "docs"
Requires-Dist: furo>=2024.8.6; extra == "docs"
Requires-Dist: myst-nb<2,>=1.1; extra == "docs"
Requires-Dist: sphinx-copybutton<1,>=0.5; extra == "docs"
Provides-Extra: demo
Requires-Dist: matplotlib>=3.8; extra == "demo"
Requires-Dist: nbclient>=0.10; extra == "demo"
Requires-Dist: nbformat>=5; extra == "demo"
Requires-Dist: ipykernel>=6; extra == "demo"
Dynamic: license-file

# KESurv

[![PyPI](https://img.shields.io/pypi/v/kesurv.svg)](https://pypi.org/project/kesurv/)
[![Tests](https://github.com/yuvrajiro/kesurv/actions/workflows/ci.yml/badge.svg)](https://github.com/yuvrajiro/kesurv/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-kesurv.statml.in-111111)](https://kesurv.statml.in)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/yuvrajiro/kesurv/blob/main/LICENSE)

KESurv estimates patient-specific survival curves from right-censored data. A survival forest supplies adaptive neighbor weights; user-selected survival models vote on which neighbors have similar predicted survival trajectories; a weighted Kaplan–Meier estimator produces the final curve.

**Documentation:** <https://kesurv.statml.in>

## Install

```bash
pip install kesurv
pip install "kesurv[speed]"   # optional Numba acceleration
```

## Quick start

```python
from kesurv import KESurv
from sksurv.ensemble import RandomSurvivalForest
from sksurv.linear_model import CoxPHSurvivalAnalysis
from sksurv.tree import SurvivalTree

model = KESurv(
    base_estimators=[
        ("ridge", CoxPHSurvivalAnalysis(alpha=1.0)),
        ("tree", SurvivalTree(max_depth=4, random_state=1)),
    ],
    forest=RandomSurvivalForest(n_estimators=100, random_state=1),
    epsilon=0.05,
    min_agreement=1,
    n_timepoints=128,
    random_state=1,
)
model.fit(X_train, y_train)

model.predict_survival(X_test, times=[1, 3, 5])   # survival probabilities
model.predict_survival_function(X_test)           # step functions
model.predict_neighbor_info(X_test)               # forest weights, votes, fallbacks
```

`X` must be finite and numeric (encode categories and impute upstream). `y` is a structured `(event, time)` array, as built by `sksurv.util.Surv.from_arrays`. Any base learner with `fit(X, y)` and `predict_survival_function(X)` works; see [the custom learner template](https://github.com/yuvrajiro/kesurv/blob/main/examples/custom_estimator.py).

## Features

- **Any base learners.** Use scikit-survival estimators or your own class.
- **Inspectable.** `predict_weights`, `predict_neighbor_info` and `kneighbors` show exactly which training subjects shaped each curve.
- **Configurable similarity grid.** Use `similarity_time`, `n_timepoints` or an explicit `similarity_times` grid.
- **Fast.** Training leaves, bootstrap multiplicities and curves are cached at fit time. Queries run in batches over forest-supported candidates only. Numba kernels are optional.
- **Extra outputs.** RMST (`predict_rmst`), risk scores (`predict`) and Harrell's C (`score`).

The weighted counting kernel builds on [fastkme](https://github.com/yuvrajiro/fastkme).

## Development

```bash
pip install -e ".[test,docs]"
python -m pytest -q
python -m sphinx -b html -W --keep-going docs docs/_build/html
```

## Citation

If you use KESurv, please cite *KESurv: A Kernel Ensemble Method for Patient-Specific Survival Prediction*, Proceedings of Machine Learning Research (ACML 2026).

## License

MIT
