How ai-in-cardiovascular-medicine/interpretable-ml-classification works
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