---
language:
- en
license: mit
tags:
- medical
- 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 XAI: Deep Stacking Ensemble for Malaria and Sickle Cell Anemia

## 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.

- **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`).

## 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

# 1. Load Artifacts
model = joblib.load('ensemble_model.pkl')
scaler = joblib.load('scaler.pkl')
imputer = joblib.load('imputer.pkl')

# 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)