# codingmermaid/hospital-readmission-ml architecture

> Architecture diagram of the GitHub repository codingmermaid/hospital-readmission-ml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codingmermaid/hospital-readmission-ml
- Repository: https://github.com/codingmermaid/hospital-readmission-ml

## Overview

This repository is an educational 30-day hospital-readmission prediction project: it builds and evaluates models, then serves a risk estimate through a Streamlit app. The main user flow is patient and encounter details → engineered feature row → LightGBM probability and threshold-based risk flag. The README documents the broader cleaning, EDA, baseline-model, evaluation, and SHAP workflow. Some pipeline links reflect documented stages; the data files are not included in the tree, and source excerpts do not establish script orchestration.

Main entry points: [`scripts/lightgbm_model.py`](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/lightgbm_model.py) (LightGBM training), [`app.py`](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/app.py) (Streamlit risk estimator), [`scripts/clean.py`](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/clean.py) (Data cleaning), [`scripts/feature_engineering.py`](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/feature_engineering.py) (Feature engineering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Risk estimation app"]
  node_app["Streamlit risk estimator<br/>[app.py]"]
  node_lgb_artifact["LightGBM model"]
  node_cats_artifact["Categorical features"]
  node_threshold_artifact["Decision threshold"]
end

subgraph group_data["Data preparation"]
  node_clean["Data cleaning<br/>[clean.py]"]
  node_eda["Exploratory charts<br/>[visualize.py]"]
  node_features["Feature engineering"]
end

subgraph group_modeling["Model development"]
  node_baseline["Logistic baseline<br/>[baseline_model.py]"]
  node_lightgbm["LightGBM training<br/>[lightgbm_model.py]"]
end

subgraph group_insight["Evaluation and interpretation"]
  node_roc_pr["ROC and PR evaluation<br/>[roc_pr_curves.py]"]
  node_accuracy["Accuracy comparison"]
  node_shap["SHAP analysis<br/>[shap_analysis.py]"]
end

node_user(("App user"))
node_uci_data["UCI encounter data"]

node_user -->|"enters details"| node_app
node_app -->|"loads model"| node_lgb_artifact
node_app -->|"loads feature list"| node_cats_artifact
node_app -->|"loads cutoff"| node_threshold_artifact
node_app -->|"scores row"| node_lgb_artifact
node_app -->|"compares score"| node_threshold_artifact
node_uci_data -->|"supplies encounters"| node_clean
node_clean -->|"explores cleaned data"| node_eda
node_clean -->|"provides cleaned data"| node_features
node_features -->|"provides model features"| node_baseline
node_features -->|"provides model features"| node_lightgbm
node_lightgbm -->|"saves model"| node_lgb_artifact
node_lightgbm -->|"saves feature list"| node_cats_artifact
node_lightgbm -->|"saves cutoff"| node_threshold_artifact
node_baseline -->|"compared in curves"| node_roc_pr
node_lightgbm -->|"compared in curves"| node_roc_pr
node_baseline -->|"included in comparison"| node_accuracy
node_lightgbm -->|"included in comparison"| node_accuracy
node_lightgbm -->|"explained by"| node_shap

click node_app "https://github.com/codingmermaid/hospital-readmission-ml/blob/main/app.py"
click node_lgb_artifact "https://github.com/codingmermaid/hospital-readmission-ml/blob/main/model/lightgbm_model.joblib"
click node_cats_artifact "https://github.com/codingmermaid/hospital-readmission-ml/blob/main/model/categorical_cols.joblib"
click node_threshold_artifact "https://github.com/codingmermaid/hospital-readmission-ml/blob/main/model/lightgbm_threshold.joblib"
click node_clean "https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/clean.py"
click node_eda "https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/visualize.py"
click node_features "https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/feature_engineering.py"
click node_baseline "https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/baseline_model.py"
click node_lightgbm "https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/lightgbm_model.py"
click node_roc_pr "https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/roc_pr_curves.py"
click node_accuracy "https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/accuracy_trap_chart.py"
click node_shap "https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/shap_analysis.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_lgb_artifact,node_cats_artifact,node_threshold_artifact,node_user toneBlue
class node_clean,node_eda,node_features toneAmber
class node_baseline,node_lightgbm toneMint
class node_roc_pr,node_accuracy,node_shap toneRose
class node_uci_data toneIndigo
```

## Components

### Risk estimation app

- [Streamlit risk estimator](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/app.py): `app.py`
- [LightGBM model](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/model/lightgbm_model.joblib): `model/lightgbm_model.joblib`
- [Categorical features](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/model/categorical_cols.joblib): `model/categorical_cols.joblib`
- [Decision threshold](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/model/lightgbm_threshold.joblib): `model/lightgbm_threshold.joblib`

### Data preparation

- [Data cleaning](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/clean.py): `scripts/clean.py`
- [Exploratory charts](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/visualize.py): `scripts/visualize.py`
- [Feature engineering](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/feature_engineering.py): `scripts/feature_engineering.py`

### Model development

- [Logistic baseline](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/baseline_model.py): `scripts/baseline_model.py`
- [LightGBM training](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/lightgbm_model.py): `scripts/lightgbm_model.py`

### Evaluation and interpretation

- [ROC and PR evaluation](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/roc_pr_curves.py): `scripts/roc_pr_curves.py`
- [Accuracy comparison](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/accuracy_trap_chart.py): `scripts/accuracy_trap_chart.py`
- [SHAP analysis](https://github.com/codingmermaid/hospital-readmission-ml/blob/main/scripts/shap_analysis.py): `scripts/shap_analysis.py`

### Other components

- **App user**
- **UCI encounter data**

## Connections

- App user → Streamlit risk estimator: enters details (evidence: `README.md`)
- Streamlit risk estimator → LightGBM model: loads model (evidence: `app.py`)
- Streamlit risk estimator → Categorical features: loads feature list (evidence: `app.py`)
- Streamlit risk estimator → Decision threshold: loads cutoff (evidence: `app.py`)
- Streamlit risk estimator → LightGBM model: scores row (evidence: `app.py`)
- Streamlit risk estimator → Decision threshold: compares score (evidence: `app.py`)
- UCI encounter data → Data cleaning: supplies encounters (evidence: `scripts/clean.py`)
- Data cleaning → Exploratory charts: explores cleaned data (evidence: `scripts/visualize.py`)
- Data cleaning → Feature engineering: provides cleaned data (evidence: `scripts/feature_engineering.py`)
- Feature engineering → Logistic baseline: provides model features (evidence: `scripts/baseline_model.py`)
- Feature engineering → LightGBM training: provides model features (evidence: `scripts/lightgbm_model.py`)
- LightGBM training → LightGBM model: saves model (evidence: `scripts/lightgbm_model.py`)
- LightGBM training → Categorical features: saves feature list (evidence: `scripts/lightgbm_model.py`)
- LightGBM training → Decision threshold: saves cutoff (evidence: `scripts/lightgbm_model.py`)
- Logistic baseline → ROC and PR evaluation: compared in curves (evidence: `scripts/roc_pr_curves.py`)
- LightGBM training → ROC and PR evaluation: compared in curves (evidence: `scripts/roc_pr_curves.py`)
- Logistic baseline → Accuracy comparison: included in comparison (evidence: `README.md`)
- LightGBM training → Accuracy comparison: included in comparison (evidence: `README.md`)
- LightGBM training → SHAP analysis: explained by (evidence: `scripts/shap_analysis.py`)
