Hospital Readmission 30d — ML & Fairness Audit

Dal CSV grezzo a predict_readmission_risk(): cleaning, ICD-9 macro-grouping, feature engineering clinico, group-aware split, LogReg vs Random Forest, ottimizzazione soglia su matrice costi e audit di equità con Fairlearn su race e age.

:::tip In una riga Classificazione binaria del rischio di readmission a 30 giorni con fairness audit obbligatorio su race/age. :::

In sintesi

Progetto del percorso Machine Learning Engineer di DataMasters/Skiller dedicato alla classificazione binaria del rischio di riammissione ospedaliera entro 30 giorni su pazienti diabetici (dataset Diabetes 130-US Hospitals, UCI 296). Tre scelte metodologiche guidano l'intero progetto:

• Binarizzazione <30 vs resto della target multiclasse, allineata al tutorial Fairlearn ufficiale e all'ottica HRRP (programma USA che penalizza ospedali con riammissioni a 30 giorni superiori alla media).
• Group-aware split sul patient_nbr: lo stesso paziente non finisce mai contemporaneamente in train e test, evitando leakage subdolo dovuto agli encounter multipli (~30% del dataset).
• Fairness audit obbligatorio su race e age con Fairlearn, con discussione esplicita dei trade-off fra demographic parity, equalized odds e predictive parity in contesto clinico.

Repository GitHub

Item	Link
Repo	fedcal/Predizione-della-riammissione-ospedaliera-a-30-Giorni
Documentazione	https://fedcal.github.io/Predizione-della-riammissione-ospedaliera-a-30-Giorni/
Licenza	MIT
Stack docs	Docusaurus 3 + TypeScript + KaTeX

note

Le metriche predittive sono placeholder onesti allineati alla letteratura (Strack et al. 2014, tutorial Fairlearn). Il dataset UCI 296 non è incluso nel repository per motivi di policy: va scaricato manualmente e i numeri reali variano in funzione del seed e delle scelte di modellazione.

Quick start

git clone https://github.com/fedcal/Predizione-della-riammissione-ospedaliera-a-30-Giorni.git
cd Predizione-della-riammissione-ospedaliera-a-30-Giorni
python3 -m venv venv && source venv/bin/activate
pip install -e ".[notebooks]"

# Scarica diabetic_data.csv + IDS_mapping.csv da UCI 296
# (https://archive.ics.uci.edu/dataset/296) ed estraili in data/raw/

readmit-train              # full tuning ~5-15 min
readmit-train --quick      # smoke test ~1 min

Inferenza programmatica:

from readmit_pipeline.inference import predict_readmission_risk

paziente = {
    "race": "Caucasian",
    "gender": "Female",
    "age": "[60-70)",
    "time_in_hospital": 4,
    "num_medications": 15,
    "A1Cresult": ">7",
    "diag_1": "428",
    "insulin": "Steady",
}
proba = predict_readmission_risk(paziente)
print(f"Rischio readmission 30d: {proba:.1%}")

Oppure da CLI:

echo '{"race":"Caucasian","age":"[60-70)","num_medications":15,"insulin":"Steady"}' > paziente.json
readmit-predict --input paziente.json --threshold 0.3

suggerimento

Una soglia inferiore a 0.5 è ragionevole quando la matrice dei costi penalizza i falsi negativi (paziente ad alto rischio non intercettato) molto più dei falsi positivi (paziente che riceve un follow-up non strettamente necessario). La scelta della soglia è documentata in Teoria → 05 Metriche su classi sbilanciate.

Mappa della documentazione

Teoria

Sette capitoli che costruiscono progressivamente il razionale clinico, metodologico ed etico del progetto:

1. Problem framing clinico — readmission a 30 giorni, HRRP, matrice costi asimmetrica.
2. EDA clinica — distribuzione target, demografia, missing non standard, encounter multipli.
3. Preprocessing dati clinici — ICD-9 grouping, IDS mapping, encoding farmaci, scaling.
4. Modelli classificazione binaria — LogReg vs Random Forest su classi sbilanciate.
5. Metriche su classi sbilanciate — AUC-PR, recall, F-beta, soglia ottima.
6. Fairness audit in sanità — demographic parity, equalized odds, predictive parity.
7. Interpretabilità & limiti — coefficienti, errori, automation bias, limiti del dataset.

Scelte tecniche

Decisioni architetturali e di modellazione documentate con trade-off espliciti:

• Architettura — moduli src/readmit_pipeline/, flusso dati, CLI.
• Scelte di modellazione — LogReg vs Ensemble, gestione sbilanciamento, soglia, fairness.

Stack tecnologico

Layer	Tecnologie
Linguaggio	Python 3.10+
ML	scikit-learn, (opzionale) xgboost
Fairness	Fairlearn
Data	pandas, numpy, scipy
Plotting	matplotlib, seaborn
Notebook	jupyter, jupytext, nbformat
Persistenza	joblib
Documentazione	Docusaurus 3 + TypeScript + KaTeX
CI/CD	GitHub Actions + GitHub Pages

Autore

Progetto realizzato da Federico Calò come parte del percorso Machine Learning Engineer di DataMasters/Skiller.

Per altri progetti, articoli e contatti: federicocalo.dev.