# abdelrahman-badawy-utah/nhanes-cvd-risk-prediction architecture

> Architecture diagram of the GitHub repository abdelrahman-badawy-utah/nhanes-cvd-risk-prediction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction
- Repository: https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction

## Overview

This is a research-oriented NHANES cardiovascular-risk prediction project with a Streamlit demo. Its principal user flow is entering hypothetical clinical, behavioral, and dietary values, receiving a calibrated risk estimate, and viewing a SHAP explanation. The notebook is the documented analysis and model-production workflow, covering leakage-safe modeling, calibration, and subgroup fairness evaluation. The app excerpt shows its prediction and explanation functions; the notebook’s internal implementation was not sampled, so its analysis stages are represented as documented capabilities rather than inferred code-level calls.

Main entry points: [`app/streamlit_app.py`](https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/app/streamlit_app.py) (Streamlit input and results), [`CVD_Risk_Prediction.ipynb`](https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/CVD_Risk_Prediction.ipynb) (NHANES risk analysis), [`app/model/best_model_artifact.pkl`](https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/app/model/best_model_artifact.pkl) (Trained model artifact), [`data/nhanes_cvd_extract.xlsx`](https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/data/nhanes_cvd_extract.xlsx) (NHANES extract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Analysis and modeling"]
  node_analysis["NHANES risk analysis"]
  node_modeling["Model evaluation and calibration"]
  node_fairness["Subgroup fairness audit"]
end

subgraph group_demo["Interactive risk demo"]
  node_interface["Streamlit input and results<br/>[streamlit_app.py]"]
  node_predictor["Calibrated risk prediction<br/>[streamlit_app.py]"]
  node_explainer["SHAP explanation<br/>[streamlit_app.py]"]
end

subgraph group_artifacts["Model and data"]
  node_survey[("NHANES extract")]
  node_artifact["Trained model artifact"]
end

node_user(("Hypothetical patient"))

node_survey -->|"provides data"| node_analysis
node_analysis -->|"evaluates models"| node_modeling
node_analysis -->|"audits subgroups"| node_fairness
node_analysis -->|"saves trained model"| node_artifact
node_user -->|"enters values"| node_interface
node_interface -->|"loads model"| node_artifact
node_interface -->|"calls prediction"| node_predictor
node_predictor -->|"returns risk"| node_interface
node_interface -->|"requests explanation"| node_explainer
node_explainer -->|"returns SHAP values"| node_interface

click node_analysis "https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/CVD_Risk_Prediction.ipynb"
click node_modeling "https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/CVD_Risk_Prediction.ipynb"
click node_fairness "https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/CVD_Risk_Prediction.ipynb"
click node_survey "https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/data/nhanes_cvd_extract.xlsx"
click node_artifact "https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/app/model/best_model_artifact.pkl"
click node_interface "https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/app/streamlit_app.py"
click node_predictor "https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/app/streamlit_app.py"
click node_explainer "https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/app/streamlit_app.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_analysis,node_modeling,node_fairness toneBlue
class node_interface,node_predictor,node_explainer toneAmber
class node_survey,node_artifact toneMint
class node_user toneIndigo
```

## Components

### Analysis and modeling

- [NHANES risk analysis](https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/CVD_Risk_Prediction.ipynb): `CVD_Risk_Prediction.ipynb`
- [Model evaluation and calibration](https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/CVD_Risk_Prediction.ipynb): `CVD_Risk_Prediction.ipynb`
- [Subgroup fairness audit](https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/CVD_Risk_Prediction.ipynb): `CVD_Risk_Prediction.ipynb`

### Interactive risk demo

- [Streamlit input and results](https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/app/streamlit_app.py): `app/streamlit_app.py`
- [Calibrated risk prediction](https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/app/streamlit_app.py): `app/streamlit_app.py`
- [SHAP explanation](https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/app/streamlit_app.py): `app/streamlit_app.py`

### Model and data

- [NHANES extract](https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/data/nhanes_cvd_extract.xlsx): `data/nhanes_cvd_extract.xlsx`
- [Trained model artifact](https://github.com/abdelrahman-badawy-utah/nhanes-cvd-risk-prediction/blob/main/app/model/best_model_artifact.pkl): `app/model/best_model_artifact.pkl`

### Other components

- **Hypothetical patient**

## Connections

- NHANES extract → NHANES risk analysis: provides data (evidence: `README.md`)
- NHANES risk analysis → Model evaluation and calibration: evaluates models (evidence: `README.md`)
- NHANES risk analysis → Subgroup fairness audit: audits subgroups (evidence: `README.md`)
- NHANES risk analysis → Trained model artifact: saves trained model (evidence: `README.md`)
- Hypothetical patient → Streamlit input and results: enters values (evidence: `README.md`)
- Streamlit input and results → Trained model artifact: loads model (evidence: `app/streamlit_app.py`)
- Streamlit input and results → Calibrated risk prediction: calls prediction (evidence: `app/streamlit_app.py`)
- Calibrated risk prediction → Streamlit input and results: returns risk (evidence: `app/streamlit_app.py`)
- Streamlit input and results → SHAP explanation: requests explanation (evidence: `app/streamlit_app.py`)
- SHAP explanation → Streamlit input and results: returns SHAP values (evidence: `app/streamlit_app.py`)