Zanarino/praevius-hospitalization-1year

Praevius — 1-year hospitalisation risk (elderly patients)

⚠️ Research prototype — NOT for clinical use. This model is trained on 117 visits from 30 patients. It informs clinical judgment; it does not replace it, and must never be the sole basis of a care decision. See the ethics statement.

This repository hosts the champion 1-year model of Praevius: a scikit-learn Pipeline (unified preprocessing + tuned Gradient Boosting) that estimates the risk of hospitalisation within one year for elderly patients, from routine geriatric data (gait speed, medications, frailty, cognition, falls, …).

▶️ Try it interactively: https://huggingface.co/spaces/Zanarino/praevius-demo

Note: this model embeds a custom preprocessing class from the praevius package, so the Hub's hosted inference widget cannot run it. Use the Space above, or load it locally with the snippet below.

Honest performance

The AUC comes from nested cross-validation (the hyperparameter search runs inside each outer fold; the model is scored on patients it never saw) — not an optimistic in-sample number. Variance is high (± 0.28), which is honest for this sample size.

Probabilities are not calibrated (this was measured): read the risk band (low / moderate / high), not the literal percentage. The 3-year horizon scores below chance and is deliberately not published as a usable model.

How to use

Recommended — via the `praevius` package (loads this same model, bundled):

pip install praevius        # or: pip install "git+https://github.com/Zanarino/praevius.git"

import praevius
models = praevius.load_pipelines()
df = praevius.patient_to_dataframe({"age": 79, "gender": "F", "fried": "Pre-frail",
                                     "gait_speed_4m": 0.75, "falls_one_year": 1})
scores = praevius.score_patient(models, df)
prob = scores["1year"]["Gradient Boosting"]
band = praevius.risk_band(prob)     # 'low' | 'moderate' | 'high'

Direct load from this repo (skops): the custom preprocessing class lives in the praevius package, so install it first (pip install praevius), then:

from huggingface_hub import hf_hub_download
from skops.io import load, get_untrusted_types
import praevius  # registers praevius.preprocessing.ClinicalPreprocessor

f = hf_hub_download("Zanarino/praevius-hospitalization-1year", "praevius_gb_tuned_1year.skops")
# Review the types before trusting them (they are this project's classes):
trusted = get_untrusted_types(file=f)
pipeline = load(f, trusted=trusted)

The exact types you are asked to trust are:

trusted = [
    "praevius.preprocessing.ClinicalPreprocessor",
]

Limitations

• —Small, single-population sample — validate on your own data before any real use.
• —Subgroup fairness (sex, age band) is not yet assessable at this sample size.
• —The model finds correlation, not causation; SHAP explains the model, not the patient.
• —scikit-learn pickles/skops are version-sensitive; this model was trained with scikit-learn 1.4.2, Python 3.10.6.

Files

• —praevius_gb_tuned_1year.skops — the champion 1-year pipeline (skops format).
• —model_card.json — the full machine-readable card (all horizons, honest metrics, calibration decision).

License & citation

GPL-3.0-or-later. Project: <https://github.com/Zanarino/praevius> · Maintainer: Rafael Zanarino (rafael@nodnex.com.br).