Add model card (README.md)

README.md

@@ -0,0 +1,189 @@
+---
+license: mit
+tags:
+  - eeg
+  - depression
+  - mental-health
+  - mdd
+  - biosignals
+  - ensemble
+  - pytorch
+  - xgboost
+  - svm
+  - neuroscience
+datasets:
+  - figshare-eeg-depression
+metrics:
+  - accuracy
+  - roc_auc
+  - f1
+language: []
+model-index:
+  - name: EEG Depression Detection V4
+    results:
+      - task:
+          type: classification
+          name: EEG-based MDD Detection
+        dataset:
+          name: Figshare EEG Depression (64 subjects, LOSO CV)
+          type: figshare-eeg-depression
+        metrics:
+          - type: accuracy
+            value: 0.9062
+            name: Subject Accuracy (threshold=0.5)
+          - type: accuracy
+            value: 0.9688
+            name: Subject Accuracy (threshold=0.575)
+          - type: roc_auc
+            value: 0.9980
+            name: AUC-ROC
+          - type: f1
+            value: 0.9714
+            name: F1 Score (threshold=0.575)
+---
+
+# EEG-Based Depression (MDD) Detection — V4 Ensemble
+
+**Leave-One-Subject-Out (LOSO) cross-validated EEG classifier for Major Depressive
+Disorder, achieving 96.88 % subject-level accuracy and 99.80 % AUC-ROC on 64 subjects
+from the public figshare EEG dataset.**
+
+---
+
+## Model Architecture
+
+This is a **3-model heterogeneous ensemble**:
+
+| Component | Details |
+|-----------|---------|
+| **1D-CNN** (weight=0.60) | Multi-scale convolution stem → 4 × ResBlock1D + SEBlock1D → GlobalAvgPool → MLP. Input: raw EEG (19 ch × 1000 samples). |
+| **XGBoost** (weight=0.25) | 800 estimators, max_depth=6, trained on 1047-dim handcrafted features. |
+| **SVM** (weight=0.15) | RBF kernel (C=10, γ=scale), trained on the same 1047-dim features. |
+
+Epoch-level probabilities from each model are aggregated as a weighted sum, then
+subject-level probability is the trimmed mean (5 % trim) of epoch probabilities.
+
+### Handcrafted Feature Set (1047 dimensions)
+
+| Group | Dims | Description |
+|-------|------|-------------|
+| Spectral power | 95 | Band power per channel (δ/θ/α/β/γ) |
+| Temporal stats | 171 | Mean, variance, skewness, kurtosis, Hjorth params, zero-crossing rate |
+| Wavelet / WPD | 304 | Wavelet Packet Decomposition energy + entropy |
+| Connectivity | 342 | Phase Locking Value + coherence between all channel pairs |
+| Asymmetry | 40 | Frontal/temporal α asymmetry (8 electrode pairs) |
+| Band ratios | 95 | Cross-band power ratios per channel |
+
+---
+
+## Performance (LOSO Cross-Validation, 64 subjects)
+
+| Metric | Threshold=0.50 | Threshold=0.575 |
+|--------|---------------|-----------------|
+| Subject Accuracy | **90.62 %** (58/64) | **96.88 %** (62/64) |
+| AUC-ROC | **99.80 %** | **99.80 %** |
+| Sensitivity (MDD recall) | 100 % | 100 % |
+| Specificity (Healthy recall) | 80.0 % | 93.3 % |
+| F1 Score | 93.15 % | 97.14 % |
+
+*Post-hoc threshold optimisation on LOSO predictions (threshold=0.575) yields 96.88 %
+accuracy while maintaining 100 % sensitivity — no MDD subject is ever missed.*
+
+---
+
+## Dataset
+
+- **Source**: [figshare EEG dataset](https://figshare.com/articles/dataset/EEG_Data_New/4244171)
+- **Subjects**: 64 (34 MDD, 30 Healthy Controls)
+- **EDF files**: 181
+- **Channels**: 19 (standard 10-20 system)
+- **Signal**: Bandpass 1–45 Hz, notch 50/60 Hz, resampled to 250 Hz
+- **Epochs**: 4 s, 50 % overlap → ~570 epochs/subject on average
+- **Total epochs**: 36,247
+
+---
+
+## Repository Files
+
+```
+models/
+  final/
+    cnn_final.pt                  # CNN state dict (trained on all 64 subjects)
+    xgboost_final.json            # XGBoost model (all 64 subjects)
+    svm_and_scaler_final.pkl      # SVM + StandardScaler (all 64 subjects)
+  fold_NN_SID/                    # One directory per LOSO fold (64 total)
+    cnn_weights.pt
+    xgboost.json
+    svm_and_scaler.pkl
+checkpoints/
+  fold_NN_SID.pkl                 # Per-fold LOSO results (probs, labels, metrics)
+config/
+  model_config.yaml
+  data_config.yaml
+  training_config.yaml
+results_best.json                 # Full LOSO metrics from training
+test_loso_results.json            # Metrics from test_loso.py
+```
+
+---
+
+## Usage
+
+### Load CNN
+
+```python
+import torch
+from eeg_depression_detection.models.full_model import EEG1DCNN  # adjust import path
+
+CNN_CONFIG = dict(
+    n_channels=19,
+    n_samples=1000,
+    n_classes=2,
+)
+model = EEG1DCNN(**CNN_CONFIG)
+state = torch.load("models/final/cnn_final.pt", map_location="cpu")
+model.load_state_dict(state)
+model.eval()
+```
+
+### Load XGBoost
+
+```python
+import xgboost as xgb
+xgb_model = xgb.XGBClassifier()
+xgb_model.load_model("models/final/xgboost_final.json")
+```
+
+### Load SVM + Scaler
+
+```python
+import pickle
+with open("models/final/svm_and_scaler_final.pkl", "rb") as f:
+    bundle = pickle.load(f)
+svm_model = bundle["svm"]
+scaler    = bundle["scaler"]
+```
+
+---
+
+## Citation
+
+If you use this model or dataset pipeline in your research, please cite:
+
+```bibtex
+@misc{eeg_depression_v4,
+  author       = {Pranav},
+  title        = {EEG Depression Detection V4 Ensemble},
+  year         = {2026},
+  publisher    = {HuggingFace},
+  howpublished = {\url{https://huggingface.co/lebiraja/eeg-depression-v4}},
+}
+```
+
+---
+
+## Licence
+
+MIT — see [LICENSE](https://github.com/pranov888/eeg-depression/blob/main/LICENSE)
+
+*Generated 2026-03-11*