# ai-in-cardiovascular-medicine/interpretable-ml-classification architecture

> Architecture diagram of the GitHub repository ai-in-cardiovascular-medicine/interpretable-ml-classification, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ai-in-cardiovascular-medicine/interpretable-ml-classification
- Repository: https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification

## Overview

##### Project Type and Purpose
- This is a Python-based machine-learning pipeline focused on interpretable cardiac anomaly detection.
- Data flows from raw CSVs (rest/stress) through preprocessing, feature engineering, model training, and interpretability (SHAP) steps.
- Outputs include serialized models (.pkl) and result artifacts (plots, metrics).

##### File Structure
- Top-level folders:
- File/Code: All Python modules and run script
- File/Files: Input CSV datasets (df_rest.csv, df_stress.csv)
- File/Results: Generated outputs (plots, metrics)
- File/pkl_files: Serialized model objects
- Key modules in File/Code:
- DataReading.py – load raw CSVs
- DataClean.py, Imputation.py, Scaling.py – preprocessing
- FeatureSelector.py, DataIdentifier.py – feature engineering and labeling
- Classifiers.py, Search.py – model training and hyperparameter search
- Interpretability.py – SHAP-based explainability
- Plotting.py – visualization utilities
- Pickle_file_read.py – model loading
- run.py – orchestrates end-to-end pipeline

##### README Insights
- You install dependencies from requirements.txt.
- You kick off the pipeline via run.py (select rest vs. stress data).
- Results and .pkl files are automatically saved.
- For SHAP plots, you configure Interpretability.py with paths to train/test CSVs and a .pkl model.

a. Main Components
1. Data Ingestion Layer
– File/Files: df_rest.csv, df_stress.csv
– DataReading.py
2. Preprocessing Layer
– DataClean.py → Imputation.py → Scaling.py
3. Feature Engineering Layer
– DataIdentifier.py → FeatureSelector.py
4. Model Training Layer
– Classifiers.py & Search.py
– Outputs .pkl models into File/pkl_files
5. Interpretability Layer
– Interpretability.py → consumes .pkl and CSVs
6. Visualization & Results
– Plotting.py → writes to File/Results

b. Relationships & Data Flow
- Model Training → “Model Store” (.pkl)
- Branch: Model Store + Input CSVs → Interpretability
- Interpretability → Results (SHAP plots)

c. Architectural Patterns & Principles
- Pipeline pattern: linear, stage-based processing
- Modular design: one module per responsibility
- Reproducibility: run.py orchestrates deterministic workflow
- Extensibility: add new classifiers or preprocessing steps as separate modules

d. Technologies & Libraries
- Python 3.x
- pandas, scikit-learn, SHAP, matplotlib/seaborn
- pickle for model serialization

## Diagram (Mermaid)

```mermaid
flowchart TD
    run["run.py"]:::orches
    subgraph "Data Ingestion"
        files[(df_rest.csv<br/>df_stress.csv)]:::data
        DataReading["DataReading.py"]:::data
    end
    run --> DataReading
    files --> DataReading

    subgraph "Preprocessing"
        DataClean["DataClean.py"]:::pre
        Imputation["Imputation.py"]:::pre
        Scaling["Scaling.py"]:::pre
    end
    DataReading --> DataClean --> Imputation --> Scaling

    subgraph "Feature Engineering"
        DataIdentifier["DataIdentifier.py"]:::feat
        FeatureSelector["FeatureSelector.py"]:::feat
    end
    Scaling --> DataIdentifier --> FeatureSelector

    subgraph "Model Training"
        Classifiers["Classifiers.py"]:::model
        Search["Search.py"]:::model
    end
    FeatureSelector --> Classifiers --> Search --> ModelStore

    ModelStore[(Model Store<br/>.pkl files)]:::storage

    subgraph "Interpretability"
        PickleRead["Pickle_file_read.py"]:::interpret
        Interpretability["Interpretability.py"]:::interpret
    end
    ModelStore --> PickleRead --> Interpretability
    files --> Interpretability

    subgraph "Visualization & Results"
        Plotting["Plotting.py"]:::viz
        Results[(Results<br/>Plots & Metrics)]:::storage
    end
    Interpretability --> Plotting --> Results
    Search --> Plotting

    run --> Classifiers
    run --> Interpretability

    click DataReading "https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification/blob/main/File/Code/Data_Reading.py"
    click files "https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification/tree/main/File/Files"
    click DataClean "https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification/blob/main/File/Code/DataClean.py"
    click Imputation "https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification/blob/main/File/Code/Imputation.py"
    click Scaling "https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification/blob/main/File/Code/Scaling.py"
    click DataIdentifier "https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification/blob/main/File/Code/DataIdentifier.py"
    click FeatureSelector "https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification/blob/main/File/Code/FeatureSelector.py"
    click Classifiers "https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification/blob/main/File/Code/Classifiers.py"
    click Search "https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification/blob/main/File/Code/Search.py"
    click ModelStore "https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification/tree/main/File/pkl_files"
    click PickleRead "https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification/blob/main/File/Code/Pickle_file_read.py"
    click Interpretability "https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification/blob/main/File/Code/Interpretability.py"
    click Plotting "https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification/blob/main/File/Code/Plotting.py"
    click Results "https://github.com/ai-in-cardiovascular-medicine/interpretable-ml-classification/tree/main/File/Results"

    classDef data fill:#D6EAF8,stroke:#1B4F72;
    classDef pre fill:#D5F5E3,stroke:#145A32;
    classDef feat fill:#FCF3CF,stroke:#7D6608;
    classDef model fill:#FADBD8,stroke:#A93226;
    classDef interpret fill:#E8DAEF,stroke:#6C3483;
    classDef viz fill:#FDEBD0,stroke:#B9770E;
    classDef orches fill:#E5E7E9,stroke:#566573;
    classDef storage fill:#EBDEF0,stroke:#4A235A;
```
