Update README.md

README.md

@@ -1,3 +1,255 @@
 ---
 license: apache-2.0
+tags:
+- sklearn
+- ensemble
+- heart-disease
+- cardiovascular-risk
+- imbalanced-data
+- explainable-ai
+metrics:
+- roc_auc
+- accuracy
+- recall
+- precision
+- f1
+language:
+- en
 ---
+
+# Model Card for Heart Risk AI - Cardiovascular Risk Prediction v3
+
+This is an advanced ensemble model designed to predict the risk of cardiovascular disease, optimized for high sensitivity to minimize missed diagnoses in medical screening scenarios.
+
+## Model Details
+
+### Model Description
+
+This model combines four powerful machine learning algorithms (Random Forest, XGBoost, Gradient Boosting, and Logistic Regression) in an ensemble approach to predict cardiovascular disease risk. The model is specifically optimized for high sensitivity (recall), making it suitable for initial screening where detecting all potential cases is prioritized over minimizing false positives.
+
+- **Developed by:** [Juan Manuel Infante Quiroga]
+- **Model type:** Ensemble Classification (Random Forest + XGBoost + Gradient Boosting + Logistic Regression)
+- **Language(s):** Python (scikit-learn)
+- **License:** Apache 2.0
+- **Version:** v3 (optimized for high sensitivity)
+
+### Model Sources
+
+- **Repository:** [https://github.com/JuanInfante122/heart-risk-ai.git]
+- **Dataset:** UCI Heart Disease Dataset (Cleveland Clinic Foundation)
+- **Framework:** scikit-learn, XGBoost
+
+## Uses
+
+### Direct Use
+
+This model is intended for **educational and research purposes only**. It can be used as a screening tool for:
+
+- Initial cardiovascular risk assessment in populations over 40 years of age
+- Triage support in emergency services
+- Risk factor monitoring for follow-up patients
+- Patient education and awareness programs
+
+**⚠️ IMPORTANT: This tool does NOT replace complete clinical evaluation, specific diagnostic tests, or professional medical judgment.**
+
+### Downstream Use
+
+The model can be integrated into:
+- Healthcare screening applications
+- Clinical decision support systems (as a supplementary tool)
+- Research studies on cardiovascular risk prediction
+- Educational platforms for medical training
+
+### Out-of-Scope Use
+
+- **Definitive diagnosis:** Never use for final diagnostic decisions
+- **Treatment decisions:** Not suitable for determining treatment protocols
+- **Standalone medical advice:** Requires professional medical interpretation
+- **Real-time emergency decisions:** Not validated for acute care settings
+
+## Bias, Risks, and Limitations
+
+### Known Limitations
+
+1. **Population Bias:** Training data primarily from Caucasian population, limiting applicability to other ethnic groups
+2. **Missing Biomarkers:** Does not include advanced biomarkers (troponins, BNP, etc.)
+3. **Medication Status:** Does not consider patient's current medication regimen
+4. **Temporal Validation:** Requires validation in prospective cohorts
+5. **High False Positive Rate:** 45.3% of healthy patients may be incorrectly flagged as at-risk
+
+### Technical Risks
+
+- **Low Specificity (54.7%):** High number of false positives may cause unnecessary anxiety and healthcare costs
+- **Dataset Size:** Limited training data (303 patients) may affect generalizability
+- **Feature Engineering:** Model relies on 7 engineered features that may not generalize to other datasets
+
+### Recommendations
+
+- Use only as a preliminary screening tool, never for final diagnosis
+- Always combine with clinical judgment and additional testing
+- Consider the high false positive rate when interpreting results
+- Validate performance on diverse populations before broader deployment
+- Implement appropriate patient counseling protocols for positive predictions
+
+## How to Get Started with the Model
+
+```python
+import joblib
+import pandas as pd
+
+# Load the model
+model_data = joblib.load('models/heart_risk_ensemble_v3.pkl')
+ensemble_model = model_data['ensemble_model']
+scaler = model_data['scaler']
+feature_names = model_data['feature_names']
+optimal_threshold = model_data['optimal_threshold']
+
+# Example patient data
+patient_data = {
+    'age': 65, 'sex': 1, 'cp': 1, 'trestbps': 150, 'chol': 280,
+    'fbs': 1, 'restecg': 1, 'thalach': 120, 'exang': 1, 'oldpeak': 3.0,
+    'slope': 1, 'ca': 2, 'thal': 7,
+    'feature_14': 0, 'feature_15': 0, 'feature_16': 0,
+    'feature_17': 0, 'feature_18': 0, 'feature_19': 0, 'feature_20': 0
+}
+
+# Prepare and predict
+patient_df = pd.DataFrame([patient_data], columns=feature_names)
+patient_scaled = scaler.transform(patient_df)
+probability = ensemble_model.predict_proba(patient_scaled)[0, 1]
+prediction = (probability >= optimal_threshold).astype(int)
+
+print(f"Risk Probability: {probability:.2f}")
+print(f"High Risk: {'Yes' if prediction else 'No'}")
+```
+
+## Training Details
+
+### Training Data
+
+- **Source:** UCI Heart Disease Dataset from Cleveland Clinic Foundation
+- **Size:** 303 patient records
+- **Features:** 13 original clinical features + 7 engineered features
+- **Target:** Binary classification (presence/absence of heart disease)
+- **Preprocessing:** SMOTE (Synthetic Minority Over-sampling Technique) applied to handle class imbalance
+
+### Training Procedure
+
+#### Preprocessing
+
+1. Feature scaling using StandardScaler
+2. SMOTE oversampling for class balance
+3. Feature engineering to create 7 additional predictive features
+4. Train/test split: 80/20
+
+#### Training Hyperparameters
+
+- **Training regime:** Standard precision (fp32)
+- **Ensemble method:** Voting classifier with soft voting
+- **Cross-validation:** 5-fold stratified cross-validation
+- **Optimization target:** Maximized sensitivity (recall)
+- **Threshold optimization:** Custom threshold tuning for high sensitivity
+
+## Evaluation
+
+### Testing Data, Factors & Metrics
+
+#### Testing Data
+
+- **Size:** 20% holdout set from UCI Heart Disease Dataset
+- **Evaluation method:** Stratified sampling to maintain class distribution
+
+#### Metrics
+
+Performance optimized for medical screening scenarios where high sensitivity is critical:
+
+- **ROC-AUC:** Area under the receiver operating characteristic curve
+- **Sensitivity (Recall):** True positive rate - primary optimization target
+- **Specificity:** True negative rate
+- **Precision:** Positive predictive value
+- **F1-Score:** Harmonic mean of precision and recall
+
+### Results
+
+| Metric | Value | Interpretation |
+|--------|-------|----------------|
+| **AUC-ROC** | 0.7986 | Good discriminative ability |
+| **Accuracy** | 0.6984 | Overall correct predictions |
+| **Sensitivity (Recall)** | 0.8503 ⭐ | Excellent - catches 85% of actual cases |
+| **Specificity** | 0.5467 | Moderate - 45% false positive rate |
+| **Precision** | 0.6520 | When model says "high risk", it's correct 65% of time |
+| **F1-Score** | 0.7381 | Balanced performance measure |
+
+#### Summary
+
+The model achieves its primary objective of high sensitivity (85.03%), making it effective for screening applications where missing a positive case is more costly than having false positives. However, the trade-off is a high false positive rate (45.3%), requiring careful implementation with appropriate follow-up protocols.
+
+## Model Examination
+
+The ensemble approach provides built-in interpretability through:
+- Feature importance rankings from tree-based models
+- Coefficient analysis from logistic regression
+- Individual model predictions for transparency
+- SHAP values can be computed for individual predictions
+
+## Environmental Impact
+
+- **Hardware Type:** Standard CPU (no GPU required)
+- **Training Time:** < 1 hour on standard hardware
+- **Model Size:** < 10 MB
+- **Inference:** Real-time prediction capability
+- **Carbon Footprint:** Minimal due to efficient algorithms and small dataset
+
+## Technical Specifications
+
+### Model Architecture and Objective
+
+- **Architecture:** Ensemble of 4 base classifiers with soft voting
+- **Objective:** Binary classification optimized for maximum sensitivity
+- **Input:** 20 numerical features (13 clinical + 7 engineered)
+- **Output:** Risk probability + binary classification with optimized threshold
+
+### Compute Infrastructure
+
+#### Hardware
+
+- Standard CPU sufficient for training and inference
+- Memory requirements: < 1 GB RAM
+- No specialized hardware needed
+
+#### Software
+
+- Python 3.7+
+- scikit-learn
+- XGBoost
+- pandas, numpy
+- joblib for model serialization
+
+## Citation
+
+**BibTeX:**
+
+```bibtex
+@misc{heart_risk_ai_v3,
+  title={Heart Risk AI: Cardiovascular Risk Prediction Model v3},
+  author={[Your Name]},
+  year={2024},
+  note={Ensemble model optimized for high sensitivity in cardiovascular screening}
+}
+```
+
+## Glossary
+
+- **Sensitivity (Recall):** Proportion of actual positive cases correctly identified
+- **Specificity:** Proportion of actual negative cases correctly identified  
+- **SMOTE:** Synthetic Minority Over-sampling Technique for handling imbalanced data
+- **Ensemble:** Combination of multiple models to improve prediction performance
+- **ROC-AUC:** Receiver Operating Characteristic - Area Under Curve, measures overall discriminative ability
+
+## Model Card Authors
+
+[Juan Manuel Infante Quiroga]
+
+## Model Card Contact
+
+[https://www.linkedin.com/in/juaninfantequiroga/]