# bitfatmonkey/hospital-readmission-prediction architecture

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

- Interactive diagram: https://gitdiagram.com/bitfatmonkey/hospital-readmission-prediction
- Repository: https://github.com/bitfatmonkey/hospital-readmission-prediction

## Overview

This is an educational, reproducible hospital-readmission modelling project—not a deployed clinical service. Its main workflow loads the bundled UCI data, defines a discharge-time cohort, creates patient-separated holdouts and training folds, fits and selects models, then evaluates the selected model and explains its predictions. The graph also preserves the project’s EDA, subgroup analysis, reusable local inference, and reproducibility outputs. Edges reflect shown calls or repository references; unsampled implementation details are not expanded.

Main entry points: [`hospital_readmission/run.py`](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/run.py) (Experiment runner), [`hospital_readmission/notebooks.py`](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/notebooks.py) (Analysis notebooks), [`hospital_readmission/data.py`](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/data.py) (Dataset loader), [`hospital_readmission/config.py`](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/config.py) (Experiment settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and cohort"]
  node_loader["Dataset loader<br/>[data.py]"]
  node_cohort["Clinical cohort<br/>[cohort.py]"]
  node_splits["Patient-aware splits<br/>[splitting.py]"]
end

subgraph group_modelling["Modelling"]
  node_features["Clinical features<br/>[features.py]"]
  node_models["Model training<br/>[modelling.py]"]
end

subgraph group_analysis["Evaluation and analysis"]
  node_evaluation["Metrics and thresholding<br/>[evaluation.py]"]
  node_eda["EDA and reports<br/>[reporting.py]"]
  node_explain["SHAP explanations<br/>[explain.py]"]
  node_notebooks["Analysis notebooks<br/>[notebooks.py]"]
end

subgraph group_repro["Reproducibility and inference"]
  node_config["Experiment settings<br/>[config.py]"]
  node_runner["Experiment runner<br/>[run.py]"]
  node_inference["Local prediction<br/>[predict.py]"]
  node_documentation["Results documentation<br/>[documentation.py]"]
  node_reports["Measured reports"]
  node_artifacts["Saved model artifacts"]
end

node_uci["Bundled UCI archive"]

node_uci -->|"loads archive"| node_loader
node_runner -->|"loads data"| node_loader
node_loader -->|"provides dataset"| node_cohort
node_runner -->|"builds cohort"| node_cohort
node_runner -->|"creates splits"| node_splits
node_runner -->|"uses settings"| node_config
node_runner -->|"tunes models"| node_models
node_models -->|"uses preprocessing"| node_features
node_runner -->|"evaluates predictions"| node_evaluation
node_runner -->|"generates reports"| node_eda
node_runner -->|"explains selected model"| node_explain
node_explain -->|"uses report utilities"| node_eda
node_runner -->|"writes results"| node_reports
node_runner -->|"saves fitted models"| node_artifacts
node_inference -->|"uses project settings"| node_config
node_notebooks -->|"loads dataset"| node_loader
node_notebooks -->|"uses cohort"| node_cohort
node_notebooks -->|"uses patient splits"| node_splits
node_notebooks -->|"uses settings"| node_config
node_documentation -->|"uses project root"| node_config
node_documentation -->|"reads measured results"| node_reports

click node_uci "https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/data/raw/diabetes%2B130-us%2Bhospitals%2Bfor%2Byears%2B1999-2008.zip"
click node_loader "https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/data.py"
click node_cohort "https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/cohort.py"
click node_config "https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/config.py"
click node_splits "https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/splitting.py"
click node_features "https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/features.py"
click node_models "https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/modelling.py"
click node_runner "https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/run.py"
click node_evaluation "https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/evaluation.py"
click node_eda "https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/reporting.py"
click node_explain "https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/explain.py"
click node_inference "https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/predict.py"
click node_notebooks "https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/notebooks.py"
click node_documentation "https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/documentation.py"
click node_reports "https://github.com/bitfatmonkey/hospital-readmission-prediction/tree/main/reports"

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_loader,node_cohort,node_splits toneBlue
class node_features,node_models toneAmber
class node_evaluation,node_eda,node_explain,node_notebooks toneMint
class node_config,node_runner,node_inference,node_documentation,node_reports,node_artifacts toneRose
class node_uci toneTeal
```

## Components

### Data and cohort

- [Dataset loader](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/data.py): `hospital_readmission/data.py`
- [Clinical cohort](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/cohort.py): `hospital_readmission/cohort.py`
- [Patient-aware splits](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/splitting.py): `hospital_readmission/splitting.py`

### Modelling

- [Clinical features](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/features.py): `hospital_readmission/features.py`
- [Model training](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/modelling.py): `hospital_readmission/modelling.py`

### Evaluation and analysis

- [Metrics and thresholding](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/evaluation.py): `hospital_readmission/evaluation.py`
- [EDA and reports](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/reporting.py): `hospital_readmission/reporting.py`
- [SHAP explanations](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/explain.py): `hospital_readmission/explain.py`
- [Analysis notebooks](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/notebooks.py): `hospital_readmission/notebooks.py`

### Reproducibility and inference

- [Experiment settings](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/config.py): `hospital_readmission/config.py`
- [Experiment runner](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/run.py): `hospital_readmission/run.py`
- [Local prediction](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/predict.py): `hospital_readmission/predict.py`
- [Results documentation](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/hospital_readmission/documentation.py): `hospital_readmission/documentation.py`
- [Measured reports](https://github.com/bitfatmonkey/hospital-readmission-prediction/tree/main/reports): `reports`
- **Saved model artifacts**

### Other components

- [Bundled UCI archive](https://github.com/bitfatmonkey/hospital-readmission-prediction/blob/main/data/raw/diabetes%2B130-us%2Bhospitals%2Bfor%2Byears%2B1999-2008.zip): `data/raw/diabetes+130-us+hospitals+for+years+1999-2008.zip`

## Connections

- Bundled UCI archive → Dataset loader: loads archive (evidence: `README.md`)
- Experiment runner → Dataset loader: loads data (evidence: `hospital_readmission/run.py`)
- Dataset loader → Clinical cohort: provides dataset (evidence: `hospital_readmission/cohort.py`)
- Experiment runner → Clinical cohort: builds cohort (evidence: `hospital_readmission/run.py`)
- Experiment runner → Patient-aware splits: creates splits (evidence: `hospital_readmission/run.py`)
- Experiment runner → Experiment settings: uses settings (evidence: `hospital_readmission/run.py`)
- Experiment runner → Model training: tunes models (evidence: `hospital_readmission/run.py`)
- Model training → Clinical features: uses preprocessing (evidence: `hospital_readmission/modelling.py`)
- Experiment runner → Metrics and thresholding: evaluates predictions (evidence: `hospital_readmission/run.py`)
- Experiment runner → EDA and reports: generates reports (evidence: `hospital_readmission/run.py`)
- Experiment runner → SHAP explanations: explains selected model (evidence: `hospital_readmission/run.py`)
- SHAP explanations → EDA and reports: uses report utilities (evidence: `hospital_readmission/explain.py`)
- Experiment runner → Measured reports: writes results (evidence: `hospital_readmission/run.py`)
- Experiment runner → Saved model artifacts: saves fitted models (evidence: `hospital_readmission/run.py`)
- Local prediction → Experiment settings: uses project settings (evidence: `hospital_readmission/predict.py`)
- Analysis notebooks → Dataset loader: loads dataset (evidence: `hospital_readmission/notebooks.py`)
- Analysis notebooks → Clinical cohort: uses cohort (evidence: `hospital_readmission/notebooks.py`)
- Analysis notebooks → Patient-aware splits: uses patient splits (evidence: `hospital_readmission/notebooks.py`)
- Analysis notebooks → Experiment settings: uses settings (evidence: `hospital_readmission/notebooks.py`)
- Results documentation → Experiment settings: uses project root (evidence: `hospital_readmission/documentation.py`)
- Results documentation → Measured reports: reads measured results (evidence: `hospital_readmission/documentation.py`)