How mennatallahussein/heart_disease_project works
Purpose and Entry Points
This repository implements an offline heart-disease ML workflow using the UCI dataset: prepare data, analyze/reduce features, train and tune classifiers/clustering models, persist artifacts, and serve interactive predictions. The runtime entry points are the Streamlit application at ui/app.py and deployment launcher at deployment/deploy.py.
Data Assets and Preparation
Raw patient data originates in data/heart_disease.csv. The preprocessing stage, captured in notebooks/01_data_preprocessing.ipynb, produces cleaned data plus encoded/scaled train/test feature and target splits:
• data/heart_disease_cleaned.csv
• data/heart_disease_encoded_scaled_train.csv
• data/heart_disease_encoded_scaled_test.csv
• data/heart_disease_target_train.csv
• data/heart_disease_target_test.csv
This file-based boundary decouples notebook experimentation/training from later evaluation or UI inference.
Feature Analysis Pipeline
Feature-shaping work is staged through notebooks rather than a reusable Python package:
• PCA analysis: notebooks/02_pca_analysis.ipynb
• Feature selection: notebooks/03_feature_selection.ipynb
• PCA output datasets: data/X_train_pca.csv, data/X_test_pca.csv
These artifacts indicate alternative model-input representations: encoded/scaled features and PCA-projected features.
Supervised Training and Selection
Classification experimentation is organized in notebooks/04_supervised_learning.ipynb, with tuning in notebooks/06_hyperparameter_tuning.ipynb. Supported model families include logistic regression, decision tree, random forest, SVM, and XGBoost. Persisted tuned/best artifacts include:
• models/LogisticRegression_best_model.pkl
• models/RandomForest_best_model.pkl
• models/SVM_best_model.pkl
• models/DecisionTree_best_model.pkl
• models/XGB_best_model.pkl
Evaluation output is retained in results/evaluation_metrics.txt.
Inference Artifact Boundary
The repository contains both individual serialized estimators and alternate Joblib artifacts:
• models/Logistic_Regression.joblib
• models/Random_Forest.joblib
• models/SVM.joblib
• models/Decision_Tree.joblib
models/RandomForest_full_pipeline.pkl is architecturally important because it likely packages preprocessing with inference, avoiding input-feature transformation drift between the UI and training workflow. Consumers must select artifacts whose expected feature schema matches their own input preparation.
Unsupervised Analysis
Clustering is a separate analysis branch in notebooks/05_unsupervised_learning.ipynb, using K-Means and hierarchical clustering. Its persisted K-Means model, models/KMeans_best_model.pkl, supports segmentation/analysis rather than the primary disease-classification prediction flow.
Serving and Infrastructure
ui/app.py provides the interactive Streamlit interface and should load a serialized model to turn user-entered health attributes into predictions. deployment/deploy.py and deployment/ngrok_setup.txt establish the public-serving path: start the local Streamlit runtime, then expose it through Ngrok. Core runtime dependencies are declared in requirements.txt, including Python ML libraries, Streamlit, Joblib/Pickle serialization, and XGBoost.
Components 20
Data & features
- UCI patient data
data/heart_disease.csv - Cleaned data
data/heart_disease_cleaned.csv - Encoded/scaled splits · Train and test feature splits for model experiments.
data/heart_disease_encoded_scaled_train.csv - Target splits
data/heart_disease_target_train.csv - PCA feature splits · Alternative projected train and test features.
data/X_train_pca.csv
Offline analysis & training
- Data preprocessing · Cleans, encodes, scales, and splits patient data.
notebooks/01_data_preprocessing.ipynb - PCA analysis
notebooks/02_pca_analysis.ipynb - Feature selection
notebooks/03_feature_selection.ipynb - Classifier experiments · Evaluates logistic regression, trees, random forest, SVM, and XGBoost.
notebooks/04_supervised_learning.ipynb - Hyperparameter tuning
notebooks/06_hyperparameter_tuning.ipynb - Clustering analysis · K-Means and hierarchical segmentation branch.
notebooks/05_unsupervised_learning.ipynb
Persisted artifacts
- Evaluation metrics
results/evaluation_metrics.txt - Tuned classifier models · Best logistic regression, random forest, SVM, decision tree, and XGBoost models.
models/RandomForest_best_model.pkl - Random Forest pipeline · Bundles preprocessing with Random Forest inference to prevent feature drift.
models/RandomForest_full_pipeline.pkl - Alternate Joblib models · Require input preparation matching their training feature schema.
models/Random_Forest.joblib - K-Means model · Segmentation model, not primary diagnosis inference.
models/KMeans_best_model.pkl
Interactive serving
- Streamlit prediction UI · Collects health attributes and displays disease predictions.
ui/app.py - Deployment launcher · Starts local Streamlit serving for public exposure.
deployment/deploy.py - Ngrok exposure setup
deployment/ngrok_setup.txt - Runtime dependencies · ML, Streamlit, serialization, and XGBoost dependencies.
requirements.txt
Connections 23
- UCI patient data → Data preprocessing: prepare
- Data preprocessing → Cleaned data: writes
- Data preprocessing → Encoded/scaled splits: writes
- Data preprocessing → Target splits: writes
- Encoded/scaled splits → PCA analysis: analyze
- PCA analysis → PCA feature splits: projects
- Encoded/scaled splits → Feature selection: select from
- Encoded/scaled splits → Classifier experiments: train on
- PCA feature splits → Classifier experiments: alternative inputs
- Target splits → Classifier experiments: labels
- Classifier experiments → Hyperparameter tuning: candidates
- Hyperparameter tuning → Tuned classifier models: persists
- Hyperparameter tuning → Evaluation metrics: records
- Classifier experiments → Random Forest pipeline: packages
- Classifier experiments → Alternate Joblib models: serializes
- Encoded/scaled splits → Clustering analysis: analyze
- Clustering analysis → K-Means model: persists
- Random Forest pipeline → Streamlit prediction UI: loads for inference
- Alternate Joblib models → Streamlit prediction UI: alternate model source
- Deployment launcher → Streamlit prediction UI: launches
- Ngrok exposure setup → Deployment launcher: exposes
- Runtime dependencies → Streamlit prediction UI: dependencies
- Runtime dependencies → Deployment launcher: dependencies