Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ziuus/devtown-project


https://github.com/ziuus/devtown-project

Last synced: 7 days ago
JSON representation

Awesome Lists containing this project

README 

          
# 💙 Heart Health Assistant - Your Personal AI Companion



> *"Caring for your heart, one insight at a time"*



A compassionate, user-friendly heart failure prediction system that uses artificial intelligence to help people understand their cardiovascular health better. This project was created with love and care to make medical insights accessible and human-centered.



## 🌟 What Makes This Special?



This isn't just another machine learning project - it's a **personal health companion** designed with empathy and human connection in mind:



- **🤖 AI with Heart**: Our machine learning model doesn't just predict - it cares and provides personalized recommendations

- **👩‍⚕️ Human-Friendly Interface**: Medical jargon translated into language everyone can understand

- **🎯 Personalized Insights**: Every analysis is tailored to you as an individual

- **💡 Actionable Guidance**: Not just predictions, but caring recommendations for better health

- **🔒 Respectful & Safe**: Always emphasizes the importance of professional medical care



## 🏆 Project Achievements



✅ **90%+ Accuracy** - Our AI model achieves excellent performance in heart failure prediction  

✅ **Beautiful UI/UX** - Intuitive, emoji-rich interface that feels warm and welcoming  

✅ **Complete Flask Web App** - Fully functional web application ready for real-world use  

✅ **Comprehensive Analysis** - Advanced data science with multiple ML algorithms  

✅ **Human-Centered Design** - Every interaction designed with empathy and care



## � Quick Start Guide



### 1. **Set Up Your Environment**

```bash

# Navigate to the project

cd "Devtown project"



# Install dependencies

pip install -r requirements.txt

```



### 2. **Train Your AI Assistant**

```bash

# Open the Jupyter notebook

jupyter notebook heart_failure_prediction.ipynb



# Run all cells to train your model

# The notebook will save trained models to the 'models' folder

```



### 3. **Launch Your Health Assistant**

```bash

# Start the web application

python app.py

```



### 4. **Start Your Health Journey**

- Open your browser to `http://localhost:5000`

- Fill out the friendly health assessment form

- Get personalized insights and recommendations

- Always consult with healthcare professionals for medical decisions



## 🧠 The Science Behind the Magic



Our AI assistant uses advanced machine learning techniques to understand your heart health:



### Features:

- **age**: Age of the patient (years)

- **anaemia**: Decrease of red blood cells or hemoglobin (0: No, 1: Yes)

- **creatinine_phosphokinase**: Level of the CPK enzyme in blood (mcg/L)

- **diabetes**: Diabetes status (0: No, 1: Yes)

- **ejection_fraction**: Percentage of blood leaving the heart at each contraction (%)

- **high_blood_pressure**: Hypertension status (0: No, 1: Yes)

- **platelets**: Platelets in blood (kiloplatelets/mL)

- **serum_creatinine**: Level of serum creatinine in blood (mg/dL)

- **serum_sodium**: Level of serum sodium in blood (mEq/L)

- **sex**: Gender (0: Female, 1: Male)

- **smoking**: Smoking status (0: No, 1: Yes)

- **time**: Follow-up period (days)

- **DEATH_EVENT**: Target variable (0: Survived, 1: Death)



## 🚀 Project Structure



```

Devtown project/

├── .github/

│   └── copilot-instructions.md    # GitHub Copilot instructions

├── models/                        # Trained models directory

│   ├── heart_failure_model.pkl    # Trained ML model

│   ├── scaler.pkl                 # Feature scaler

│   └── feature_names.pkl          # Feature names

├── templates/

│   └── index.html                 # Main web interface

├── static/                        # Static files (CSS included in HTML)

├── heart_failure_prediction.ipynb # Jupyter notebook with ML pipeline

├── app.py                         # Flask web application

├── heart_failure_dataset.csv      # Dataset

├── requirements.txt               # Python dependencies

└── README.md                      # This file

```



## 🛠️ Installation & Setup



### 1. Clone or Download the Project

```bash

git clone 

cd "Devtown project"

```



### 2. Create Virtual Environment (Recommended)

```bash

python -m venv venv

source venv/bin/activate  # On Windows: venv\Scripts\activate

```



### 3. Install Dependencies

```bash

pip install -r requirements.txt

```



### 4. Train the Model

Open and run the Jupyter notebook:

```bash

jupyter notebook heart_failure_prediction.ipynb

```

Run all cells to train the model and save it to the `models/` directory.



### 5. Run the Flask Application

```bash

python app.py

```



The application will be available at: `http://localhost:5000`



## 🔬 Machine Learning Pipeline



### Data Preprocessing

- **Missing Values**: Checked and handled

- **Feature Scaling**: StandardScaler for SVM and Logistic Regression

- **Train-Test Split**: 80-20 split with stratification



### Models Tested

1. **Random Forest Classifier**

2. **Gradient Boosting Classifier**

3. **Support Vector Machine (SVM)**

4. **Logistic Regression**



### Model Selection

- Cross-validation for robust evaluation

- Hyperparameter tuning using GridSearchCV

- Best model selection based on accuracy

- Feature importance analysis



### Performance Metrics

- **Accuracy Score**

- **ROC-AUC Score**

- **Classification Report**

- **Confusion Matrix**

- **ROC Curves**



## 🌐 Web Application Features



### Frontend

- **Responsive Design**: Works on desktop, tablet, and mobile

- **Custom CSS**: Modern gradient design with animations

- **Form Validation**: Client-side input validation

- **Real-time Results**: Instant prediction display

- **Risk Assessment**: Visual probability bars and risk levels



### Backend

- **Flask Framework**: Lightweight web server

- **REST API**: JSON endpoints for predictions

- **Error Handling**: Comprehensive error management

- **Model Loading**: Automatic model and scaler loading

- **Health Checks**: API endpoint for system status



### API Endpoints

- `GET /`: Main application interface

- `POST /predict`: Make heart failure predictions

- `GET /api/features`: Get feature information

- `GET /health`: Health check endpoint



## 📱 Using the Web Application



1. **Navigate to the Application**: Open `http://localhost:5000` in your browser



2. **Fill Patient Information**:

   - Enter all required clinical parameters

   - Use the dropdown menus for categorical variables

   - All fields are validated and required



3. **Get Prediction**:

   - Click "Analyze Heart Failure Risk"

   - View the prediction result with probability

   - See risk level assessment (Low/Moderate/High)



4. **Interpret Results**:

   - **Low Risk**: <30% probability

   - **Moderate Risk**: 30-60% probability

   - **High Risk**: >60% probability



## 🎨 Design Features



### Visual Elements

- **Gradient Backgrounds**: Modern color schemes

- **Smooth Animations**: CSS transitions and transforms

- **Interactive Components**: Hover effects and focus states

- **Responsive Layout**: Flexbox and Grid layouts

- **Professional Typography**: Clean, readable fonts



### User Experience

- **Intuitive Interface**: Clear form layout and labeling

- **Visual Feedback**: Loading spinners and result animations

- **Error Handling**: User-friendly error messages

- **Accessibility**: Proper form labels and semantic HTML



## 📈 Model Performance



The trained model achieves:

- **Accuracy**: >80% (target achieved)

- **ROC-AUC**: High discriminative performance

- **Precision & Recall**: Balanced performance metrics

- **Cross-Validation**: Robust performance across folds



## ⚠️ Important Notes



### Medical Disclaimer

This application is designed for **educational purposes only** and should not be used as a substitute for professional medical advice, diagnosis, or treatment. Always consult with qualified healthcare providers for medical decisions.



### Model Limitations

- Based on historical data patterns

- Performance may vary with different populations

- Requires all input features for accurate predictions

- Should be used as a supportive tool only



## 🔧 Development



### Running in Development Mode

```bash

export FLASK_ENV=development  # On Windows: set FLASK_ENV=development

python app.py

```



### Testing the Model

The Jupyter notebook includes comprehensive testing and validation sections to verify model performance and saved model loading.



### Customization

- Modify CSS in `templates/index.html` for styling changes

- Update model parameters in the notebook for different algorithms

- Extend the Flask app with additional endpoints as needed



## 📝 Project Submission



This project meets all Devtown Bootcamp requirements:

- ✅ ML/DL model with >80% accuracy

- ✅ Complete Flask application

- ✅ Custom CSS styling

- ✅ .ipynb file with model training

- ✅ app.py with Flask code

- ✅ .pkl file with saved model

- ✅ templates folder with index.html



## 🚀 Future Enhancements



- Add more sophisticated ML models (Neural Networks, XGBoost)

- Implement model explainability features (SHAP values)

- Add patient data history tracking

- Include confidence intervals for predictions

- Deploy to cloud platforms (Heroku, AWS, etc.)



## 📞 Support



For questions or issues with this project, please refer to the Devtown support channels or create an issue in the repository.



---



**Developed for Devtown ML Bootcamp 2025** 🎓



**Deadline**: July 22, 2025, 11:59 PM