Metadata-Version: 2.4
Name: survfm-rmst
Version: 0.2.0
Summary: An RMST target interface for tabular models in right-censored survival prediction.
Author: Yue Lyu, Steven H. Lin, Xuelin Huang, Ziyi Li
License-Expression: MIT
Project-URL: Homepage, https://yuelyu21.github.io/SurvFM/
Project-URL: Documentation, https://yuelyu21.github.io/SurvFM/
Project-URL: Repository, https://github.com/yuelyu21/SurvFM
Project-URL: Issues, https://github.com/yuelyu21/SurvFM/issues
Keywords: survival analysis,restricted mean survival time,pseudo-observations,tabular foundation models,right censoring
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Science/Research
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: pandas>=2.0
Provides-Extra: sklearn
Requires-Dist: scikit-learn>=1.2; extra == "sklearn"
Provides-Extra: tabpfn
Requires-Dist: scikit-learn>=1.2; extra == "tabpfn"
Requires-Dist: tabpfn; extra == "tabpfn"
Provides-Extra: tabicl
Requires-Dist: scikit-learn>=1.2; extra == "tabicl"
Requires-Dist: tabicl; extra == "tabicl"
Provides-Extra: tabdpt
Requires-Dist: scikit-learn>=1.2; extra == "tabdpt"
Requires-Dist: tabdpt; extra == "tabdpt"
Provides-Extra: tabh2o
Requires-Dist: scikit-learn>=1.2; extra == "tabh2o"
Requires-Dist: requests>=2.31; extra == "tabh2o"
Provides-Extra: mitra
Requires-Dist: scikit-learn>=1.2; extra == "mitra"
Requires-Dist: autogluon.tabular>=1.5; extra == "mitra"
Provides-Extra: metrics
Requires-Dist: scikit-survival; extra == "metrics"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file

# SurvFM

[![Tests](https://github.com/yuelyu21/SurvFM/actions/workflows/test.yml/badge.svg)](https://github.com/yuelyu21/SurvFM/actions/workflows/test.yml)
[![Documentation](https://github.com/yuelyu21/SurvFM/actions/workflows/docs.yml/badge.svg)](https://yuelyu21.github.io/SurvFM/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## Reusable tabular prediction for right-censored survival outcomes

SurvFM is a model-agnostic framework that adapts tabular prediction models to
right-censored survival outcomes. It constructs exact jackknife
pseudo-observations for restricted mean survival time (RMST) and supplies the
same horizon-specific regression target to interchangeable tabular backbones.
Backbone-specific configurations are named SurvFM-TabPFN, SurvFM-TabICL,
SurvFM-TabDPT, SurvFM-TabH2O and SurvFM-MITRA.

> **Research software.** SurvFM is intended for methodological research and
> retrospective evaluation. It has not been validated for clinical
> decision-making.

## Installation

Clone the repository and install the core package with a lightweight local
backbone:

```bash
git clone https://github.com/yuelyu21/SurvFM.git
cd SurvFM
python -m pip install -e ".[sklearn]"
```

See the [installation guide](https://yuelyu21.github.io/SurvFM/installation/)
for isolated environments and optional backbone dependencies.

## Quick start

```python
from survfm import fit_survfm

model = fit_survfm(
    X_train,
    time_train,
    event_train,
    backbone="random_forest",
    tau=365.0,
)

predicted_rmst = model.predict(X_test)
risk_score = model.predict_risk(X_test)  # negative predicted RMST
```

The default backbone is TabPFN:

```python
model = fit_survfm(
    X_train,
    time_train,
    event_train,
    backbone="tabpfn",
    tau=365.0,
)
```

Install the corresponding optional dependency first with
`python -m pip install -e ".[tabpfn]"`. The package also exposes `tabicl`,
`tabdpt`, `tabh2o`, `mitra`, `linear`, `random_forest` and
`gradient_boosting`. List the complete registry with:

```bash
survfm-rmst backbones
survfm-rmst diagnose
```

## What the estimator does

1. Validates right-censored training outcomes (`event=1`, `censored=0`).
2. Uses an explicit RMST horizon or selects a training-fold event-time
   quantile when `tau=None`.
3. Fits train-only numeric and categorical preprocessing for pandas inputs.
4. Constructs exact, memory-bounded jackknife pseudo-RMST targets.
5. Fits the selected regression backbone and returns predictions in `[0, tau]`.

The output is a horizon-specific prediction targeting covariate-conditional
RMST. It is not a full survival curve, treatment effect or deployment-ready
clinical decision rule.

## Documentation

Read the complete documentation at
[yuelyu21.github.io/SurvFM](https://yuelyu21.github.io/SurvFM/).

To build and serve it locally:

```bash
python -m pip install -e ".[docs]"
mkdocs serve --dev-addr 127.0.0.1:8000
```

## Development

```bash
python -m pip install -e ".[sklearn,dev]"
python -m pytest
python -m build
```

## Citation

Citation metadata are provided in [`CITATION.cff`](CITATION.cff). The citation
record will be updated with the article DOI when available.

## License

SurvFM is released under the [MIT License](LICENSE).
