Update README.md

README.md

@@ -1,69 +1,94 @@
 ---
+language:
+- en
 license: mit
-title: Hemaclass AI Diagnostics
-emoji: 🩸
-colorFrom: red
-colorTo: gray
-sdk: gradio
-sdk_version: 4.44.1
-app_file: app.py
-pinned: false
 tags:
 - medical
-- biology
-- xai
-- malaria
-- sickle-cell
+- clinical-decision-support
+- tabular-classification
+- scikit-learn
+- xgboost
+- shap
+- ensemble-learning
+- global-health
+datasets:
+- private-western-kenya-clinical-cohort
+metrics:
+- accuracy
+- f1
+- sensitivity
+- specificity
 ---
 
-# Hemaclass AI Diagnostics: Clinical Decision Support System
+# Hemaclass XAI: Deep Stacking Ensemble for Malaria and Sickle Cell Anemia
 
-An explainable ensemble-based diagnostic tool optimized for **Malaria**, **Sickle Cell Anemia (SCA)**, and **Co-infection** classification in Western Kenya.
+## Model Description
+The **Hemaclass XAI** model is a phase-4 prototype Clinical Decision Support System (CDSS) designed to classify **Malaria, Sickle Cell Anemia (SCA), Co-infections, and Negative (Healthy/Other)** patient states. Developed specifically for deployment in resource-constrained settings in Western Kenya, the model utilizes a robust Deep Stacking Ensemble architecture coupled with SHAP (SHapley Additive exPlanations) for transparent, clinician-friendly interpretability.
 
-## 🔬 Model Details
-- **Architecture:** Stacking Ensemble (RF, SVM, XGBoost) with a Logistic Regression Meta-Learner.
-- **Explainability:** Integrated SHAP waterfall plots for local feature importance.
-- **Preprocessing:** MICE Imputation, SMOTE balancing, and Z-Score Normalization.
+- **Developer:** Mabonga Labs / Hemaclass Project
+- **Model Type:** Multi-Class Tabular Classification (Deep Stacking Ensemble)
+- **Primary Architecture:** Random Forest, Support Vector Machine (RBF), and XGBoost (Base Learners) -> Logistic Regression (Meta-Learner).
+- **Hyperparameter Tuning:** Nested Cross-Validation with Bayesian Search (`skopt`).
 
-## 🚀 Quick Usage (Inference Code)
-To use this model programmatically, ensure you have your `.pkl` artifacts in the local directory.
+## Intended Use & Target Audience
+- **Primary Use Case:** Triage and secondary diagnostic validation for clinicians operating in malaria-endemic regions with high SCA prevalence.
+- **Target Audience:** Medical doctors, clinical officers, and healthcare technicians.
+- **Out-of-Scope Uses:** This model is **not** a standalone diagnostic device. It is designed for *decision support*. It should not override human clinical judgment or be used as a replacement for definitive laboratory protocols (e.g., blood smears, Hb electrophoresis). 
 
+## Clinical Protocol & Hardcoded Overrides
+To prioritize patient safety, the inference pipeline integrates hardcoded clinical rules that override the AI's probability outputs in critical, life-threatening scenarios:
+1. **Severe Hyperhemolytic Crisis:** Hemoglobin (Hb) < 5.0 g/dL.
+2. **Acute Hemolytic Malarial Crisis:** Reticulocyte Count > 8.0% + Positive Malaria RDT.
+3. **Rapidly Progressing Vaso-occlusive Malarial Crisis:** Rapid Hb decline (>1.5g/dL in 48h) + Positive Malaria RDT + Presence of HbS genotype.
+*When triggered, the system flags the diagnosis as "Co-infection" with 100% confidence and alerts the clinician to admit the patient to a high-dependency unit.*
+
+## Model Input Features
+The model ingests 24 clinical biomarkers and autonomously engineers 3 derived features:
+* **Demographics:** Age, Sex
+* **Vitals & Symptoms:** Body Temperature, Fever, Chills, Headache, Muscle Aches, Fatigue, Loss of Appetite, Jaundice, Abdominal Pain, Joint Pain, Splenomegaly, Severe Pallor, Lymphadenopathy.
+* **Laboratory Markers:** Malaria RDT (Binary), Hemoglobin (Hb), WBC Count, Platelet Count, Reticulocyte Count, Rapid Hb Decline Alert.
+* **Hemoglobin Fractions:** HbA, HbS, HbF.
+* **Engineered Features:** Symptom Severity Score, Age Group (Categorical), Infection-to-Anemia Ratio (WBC / Hb).
+
+## Data Preprocessing & Augmentation
+* **Missing Data:** Handled using Multiple Imputation by Chained Equations (MICE) up to 30 iterations to preserve complex clinical covariances.
+* **Class Imbalance:** The foundational dataset (~350 retrospective patient records from Western Kenya) was highly imbalanced. **Extreme SMOTE** (Synthetic Minority Over-sampling Technique) was applied to map boundaries and synthesize a robust, balanced training matrix of 6,000 clinical profiles (1,500 per target class).
+* **Encoding:** Deterministic Ordinal Encoding for categorical values; Z-Score Normalization for numerical features.
+
+## Explainability (XAI)
+The system integrates **SHAP (TreeExplainer)** applied to the XGBoost component of the stacking ensemble. Local explanations (Waterfall plots) are generated for every inference, providing clinicians with exact quantification of how individual biomarkers (e.g., *HbS%* or *Symptom Severity*) contributed to the final predicted risk score.
+
+## Evaluation & Metrics
+The model was evaluated on an isolated, unseen clinical test set prior to SMOTE augmentation.
+* **Metrics Tracked:** Macro-F1 Score, Macro-Sensitivity (Recall), Macro-Specificity, and overall Accuracy. 
+* **Statistical Significance:** Friedman/Nemenyi post-hoc testing confirmed the Stacking Ensemble significantly outperforms isolated baseline models (p < 0.05).
+*(Note: Refer to the specific model logs or the connected Gradio dashboard for live metrics).*
+
+## Ethical Considerations & Limitations
+* **Geographic Bias:** The base dataset reflects the epidemiology of Western Kenya. Prevalence features (like overlapping splenomegaly in SCA and Malaria) may not generalize accurately to populations outside of Sub-Saharan Africa or regions with varying Plasmodium falciparum endemicity.
+* **Synthetic Data Artifacts:** Because SMOTE was used extensively to augment the data for deep learning convergence, extreme edge-case boundaries may occasionally display synthetic bias. Prospective validation on a large-scale real-world clinical trial is required before Phase 5 medical device certification.
+* **Explainability Proxy:** The SHAP explanations are derived from the XGBoost sub-estimator rather than the entire Stacking Classifier boundary, serving as a highly accurate proxy rather than an absolute mathematical reflection of the meta-learner.
+
+## How to Get Started
+To interact with the model via the UI, please visit the connected [Hugging Face Space](#). 
+
+For programmatic inference using Python:
 ```python
 import joblib
 import pandas as pd
-import numpy as np
 
 # 1. Load Artifacts
 model = joblib.load('ensemble_model.pkl')
 scaler = joblib.load('scaler.pkl')
 imputer = joblib.load('imputer.pkl')
-FEATURES = joblib.load('feature_names.pkl')
-target_names = ['Negative', 'Malaria', 'SCA', 'Co-infection']
-
-def predict_patient(data_dict):
-    """
-    Input: Dictionary of patient vitals/labs
-    Output: Predicted Diagnosis and Confidence
-    """
-    # Create DataFrame and align features
-    df = pd.DataFrame([data_dict])
-    for col in set(FEATURES) - set(df.columns):
-        df[col] = np.nan
-    df = df[FEATURES]
-
-    # Preprocess
-    X_imp = imputer.transform(df)
-    X_scaled = scaler.transform(X_imp)
-
-    # Inference
-    pred = model.predict(X_scaled)
-    prob = np.max(model.predict_proba(X_scaled))
-    
-    return {
-        "Diagnosis": target_names[pred],
-        "Confidence": f"{prob*100:.2f}%"
-    }
-
-# Example Usage:
-patient_data = {'age': 25, 'hb': 10.5, 'temp': 38.5, 'malaria_rdt': 1}
-print(predict_patient(patient_data))
+
+# 2. Prepare patient data (ensure columns match FEATURE_NAMES)
+# patient_df = pd.DataFrame({...})
+
+# 3. Preprocess
+# X_imp = imputer.transform(patient_df)
+# X_scaled = scaler.transform(X_imp)
+
+# 4. Predict
+# predictions = model.predict(X_scaled)
+# probabilities = model.predict_proba(X_scaled)