# lettezuart/xgboost-modelgpu architecture

> Architecture diagram of the GitHub repository lettezuart/xgboost-modelgpu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lettezuart/xgboost-modelgpu
- Repository: https://github.com/lettezuart/xgboost-modelgpu

## Overview

##### Project Type and Purpose
- This is a data-science/ML pipeline project for time-series prediction of patient glucose levels (not a web app or microservice).
- It ingests raw CSV data, applies a Kalman filter, trains XGBoost models for two horizons (30 min, 60 min), then runs a final validation to produce metrics and plots.

##### High-Level Components
a. Data Sources
- Raw CSV files under Data/Raw/<patient_id>
b. Data Ingestion & Preprocessing
- utils/data_loader.py loads CSVs
- utils/data_processing.py & utils/features.py apply data cleaning, feature extraction
- utils/filter.py (Kalman filter only)
c. Dataset Abstraction
- utils/datasets.py constructs train/test splits
d. Offline Model Training
- models/training.py orchestrates training loops per patient & horizon
- models/offline_model.py defines XGBoost model workflows
- Outputs: model artifacts (model_param.json, scaler.pkl, metadata.json) written to Trained_model_outputs
e. Final Validation
- utils/final_validation.py loads saved models + scalers, predicts test sets
f. Evaluation
- utils/evaluation.py computes RMSE, MAE, R²
- utils/clarke.py computes Clarke error zones
g. Reporting & Visualization
- Training_metrics/*.txt and Validation_metrics/*.txt summary tables
- Training_plots/ and Validation_plots/ PNG graphs
h. Orchestration
- main.py invokes the full pipeline in sequence

##### Relationships and Data Flow
- → Dataset Abstraction → Offline Model Training
- → Trained_model_outputs (artifact store)
- → Final Validation → Evaluation → Reporting & Visualization
- main.py spans all stages, controlling the sequence

##### Architectural Patterns and Principles
- Pipeline pattern: discrete stages with well-defined inputs/outputs
- Modular utilities: separate filter, loader, processing, evaluation
- Separation of concerns: model definition vs. training vs. validation
- Artifact management: separate storage per patient/horizon

##### Technologies & Frameworks to Annotate
- Python 3.x
- pandas, numpy for data handling
- XGBoost (models/offline_model.py)
- joblib or pickle (scaler.pkl)
- matplotlib for plots
- tabulate for text tables

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Layer"
        DS["Raw CSV Data<br/>(Data/Raw/&lt;patient_id&gt;)"]:::datastore
    end

    subgraph "Compute Layer"
        subgraph "Data Ingestion & Preprocessing"
            DL["utils/data_loader.py"]:::code_module
            DP["utils/data_processing.py"]:::code_module
            FT["utils/features.py"]:::code_module
            KF["utils/filter.py<br/>(Kalman filter)"]:::code_module
        end
        subgraph "Dataset Abstraction"
            DA["utils/datasets.py"]:::code_module
        end
        subgraph "Offline Model Training"
            TM["models/training.py"]:::process
            OM["models/offline_model.py"]:::process
        end
        Artifacts["Trained_model_outputs/"]:::datastore
    end

    subgraph "Validation & Evaluation"
        FV["utils/final_validation.py"]:::process
        EV["utils/evaluation.py"]:::process
        CL["utils/clarke.py"]:::process
    end

    subgraph "Storage & Reports"
        TMET["Training_metrics/"]:::datastore
        VMET["Validation_metrics/"]:::datastore
        TP["Training_plots/"]:::datastore
        VP["Validation_plots/"]:::datastore
    end

    Main["main.py"]:::process

    DS -->|"1 raw time-series"| DL
    DL -->|"2 clean data"| DP
    DP -->|"3 extract features"| FT
    FT -->|"4 apply Kalman filter"| KF
    KF -->|"5 features"| DA
    DA -->|"6 train splits"| TM
    TM -->|"7 train XGBoost"| OM
    OM -->|"8 model artifacts"| Artifacts
    Artifacts -->|"9 load models"| FV
    FV -->|"10 predictions"| EV
    EV -->|"11 metrics"| CL
    CL -->|"12 metrics output"| TMET
    CL -->|"12 metrics output"| VMET
    CL -->|"13 plots"| TP
    CL -->|"13 plots"| VP
    Main -->|"orchestrates pipeline"| DL
    Main -->|"orchestrates pipeline"| TM
    Main -->|"orchestrates pipeline"| FV
    Main -->|"orchestrates pipeline"| CL

    click DS "https://github.com/lettezuart/xgboost-modelgpu/tree/OnlyGPU/Data/Raw/<patient_id>"
    click DL "https://github.com/lettezuart/xgboost-modelgpu/blob/OnlyGPU/utils/data_loader.py"
    click DP "https://github.com/lettezuart/xgboost-modelgpu/blob/OnlyGPU/utils/data_processing.py"
    click FT "https://github.com/lettezuart/xgboost-modelgpu/blob/OnlyGPU/utils/features.py"
    click KF "https://github.com/lettezuart/xgboost-modelgpu/blob/OnlyGPU/utils/filter.py"
    click DA "https://github.com/lettezuart/xgboost-modelgpu/blob/OnlyGPU/utils/datasets.py"
    click TM "https://github.com/lettezuart/xgboost-modelgpu/blob/OnlyGPU/models/training.py"
    click OM "https://github.com/lettezuart/xgboost-modelgpu/blob/OnlyGPU/models/offline_model.py"
    click Artifacts "https://github.com/lettezuart/xgboost-modelgpu/tree/OnlyGPU/Trained_model_outputs/"
    click FV "https://github.com/lettezuart/xgboost-modelgpu/blob/OnlyGPU/utils/final_validation.py"
    click EV "https://github.com/lettezuart/xgboost-modelgpu/blob/OnlyGPU/utils/evaluation.py"
    click CL "https://github.com/lettezuart/xgboost-modelgpu/blob/OnlyGPU/utils/clarke.py"
    click TMET "https://github.com/lettezuart/xgboost-modelgpu/tree/OnlyGPU/Training_metrics/"
    click VMET "https://github.com/lettezuart/xgboost-modelgpu/tree/OnlyGPU/Validation_metrics/"
    click TP "https://github.com/lettezuart/xgboost-modelgpu/tree/OnlyGPU/Training_plots/"
    click VP "https://github.com/lettezuart/xgboost-modelgpu/tree/OnlyGPU/Validation_plots/"
    click Main "https://github.com/lettezuart/xgboost-modelgpu/blob/OnlyGPU/main.py"

    classDef code_module fill:#D6EAF8,stroke:#1B4F72,color:#154360
    classDef process fill:#FAD7A0,stroke:#B9770E,color:#7D6608
    classDef datastore fill:#ABEBC6,stroke:#196F3D,color:#145A32
```
