SEO: full metadata, safetensors, model-index, cross-links, front-loaded metrics

README.md

@@ -1,23 +1,97 @@
 ---
 license: cc-by-4.0
 library_name: pytorch
+pipeline_tag: time-series-classification
 tags:
   - sleep-staging
   - polysomnography
   - eeg
   - eog
   - emg
+  - biosignals
+  - signal-processing
+  - time-series
+  - healthcare
+  - medical
+  - edge-ai
+  - tinyml
+  - on-device
+  - gru
+  - cnn
+  - depthwise-separable-convolution
+  - gabor-filter
   - sleep-edf
-  - biomedical
+  - physionet
+  - lightweight
+  - low-parameter
+datasets:
+  - siamakz/sleep_edf_expanded
+model-index:
+  - name: NeuroSleep Improved Student
+    results:
+      - task:
+          type: time-series-classification
+          name: Sleep Stage Classification
+        dataset:
+          type: sleep-edf-expanded
+          name: Sleep-EDF Expanded (15 subjects)
+        metrics:
+          - type: accuracy
+            value: 0.930
+            name: Accuracy
+          - type: kappa
+            value: 0.861
+            name: Cohen's Kappa
+          - type: f1
+            value: 0.794
+            name: Macro F1
+          - type: f1
+            value: 0.935
+            name: Weighted F1
 ---
 
 # NeuroSleep — Light-Weight Sleep Stage Model
 
-## Model Summary
+**99,477 parameters, 93% accuracy (κ=0.86) — small enough for edge/wearable deployment, scoring Wake/N1/N2/N3/REM from 4-channel PSG.**
 
-A compact PyTorch model for five-stage sleep-stage classification from four-channel polysomnography (PSG) signals. Processes 300 seconds of context (10 x 30-second epochs) and classifies each epoch into Wake, N1, N2, N3, or REM.
+> **Quick links:** [GitHub](https://github.com/shamiquekhan/neuromorphic-sleep-staging-pipeline) · [Live Demo](https://huggingface.co/spaces/shamique/neurosleep-demo) · [Kaggle](https://www.kaggle.com/shamiquekhan/neurosleep-final)
 
-99,477 parameters — designed for edge deployment.
+A compact PyTorch model for five-stage sleep-stage classification from polysomnography signals. Processes 300 seconds of context (10 × 30-second epochs) and classifies each epoch into Wake, N1, N2, N3, or REM. Designed for edge deployment on resource-constrained devices.
+
+## Quick Start
+
+```python
+import torch
+from huggingface_hub import hf_hub_download
+from safetensors.torch import load_file
+
+# Download checkpoint
+path = hf_hub_download(
+    repo_id="shamique/Light-Weight-Neuromorphic-Sleep-Stage-Model",
+    filename="student_full_finetuned.safetensors",
+)
+
+# Load model (see source repo for ImprovedStudent class definition)
+# https://github.com/shamiquekhan/neuromorphic-sleep-staging-pipeline
+from sleep_staging.models.improved_student import ImprovedStudent
+
+model = ImprovedStudent()
+model.load_state_dict(load_file(path, device="cpu"))
+model.eval()
+
+# Run inference on preprocessed PSG data
+# Input: [batch, 10, 4, 3000] — 10 epochs, 4 channels, 3000 samples @ 100Hz
+x = torch.randn(1, 10, 4, 3000)  # replace with real data
+
+with torch.inference_mode():
+    logits = model(x)              # [1, 10, 5]
+    probs = torch.softmax(logits, dim=-1)
+    preds = probs.argmax(dim=-1)   # [1, 10]
+
+STAGE_NAMES = {0: "Wake", 1: "N1", 2: "N2", 3: "N3", 4: "REM"}
+for i in range(10):
+    print(f"Epoch {i}: {STAGE_NAMES[preds[0, i].item()]} ({probs[0, i, preds[0, i]].item():.2%})")
+```
 
 ## Architecture
 
@@ -53,6 +127,7 @@ Wake / N1 / N2 / N3 / REM
 - **Epoch length:** 30 seconds (3000 samples)
 - **Sequence length:** 10 epochs
 - **Shape:** `[batch, 10, 4, 3000]`
+- **Preprocessing:** 0.5–35 Hz bandpass → 50 Hz notch → z-score normalization
 
 ## Output Labels
 
@@ -83,65 +158,12 @@ Wake / N1 / N2 / N3 / REM
 | N3 | 0.877 | 0.845 | 0.912 |
 | REM | 0.808 | 0.714 | 0.930 |
 
-> **Note:** N1 and REM have lower precision because the model over-predicts these transitional stages. This is expected given physiological overlap with Wake and N2.
-
-## How to Use
-
-### Installation
-
-```bash
-pip install torch numpy
-```
-
-### Load the Model
-
-```python
-import torch
-import sys
-from huggingface_hub import hf_hub_download
-
-# Download checkpoint
-path = hf_hub_download(
-    repo_id="shamique/Light-Weight-Neuromorphic-Sleep-Stage-Model",
-    filename="student_full_finetuned.pt",
-)
-
-# Define the model class (from the source repo)
-# You need the ImprovedStudent class — see: https://github.com/shamiquekhan/neuromorphic-sleep-staging-pipeline
-from sleep_staging.models.improved_student import ImprovedStudent
-
-model = ImprovedStudent()
-model.load_state_dict(torch.load(path, map_location="cpu", weights_only=True))
-model.eval()
-```
-
-### Run Inference
-
-```python
-import numpy as np
-
-# Dummy input: 1 batch, 10 epochs, 4 channels, 3000 samples each
-# Replace with real preprocessed PSG data (100 Hz, bandpass filtered, z-score normalized)
-x = torch.randn(1, 10, 4, 3000)
+> **Note:** N1 and REM have lower precision because the model over-predicts these transitional stages, which is expected given physiological overlap with Wake and N2.
 
-with torch.no_grad():
-    logits = model(x)           # [1, 10, 5]
-    probs = torch.softmax(logits, dim=-1)
-    preds = probs.argmax(dim=-1)  # [1, 10]
-
-# Stage names
-STAGE_NAMES = {0: "Wake", 1: "N1", 2: "N2", 3: "N3", 4: "REM"}
-
-# Print prediction for each epoch
-for i in range(10):
-    stage = STAGE_NAMES[preds[0, i].item()]
-    conf = probs[0, i, preds[0, i]].item()
-    print(f"Epoch {i}: {stage} (confidence: {conf:.3f})")
-```
-
-### Preprocessing Required
+## Preprocessing
 
 The model expects preprocessed data:
+
 1. **Bandpass filter:** 0.5–35 Hz
 2. **Notch filter:** 50 Hz
 3. **Normalization:** z-score per channel
@@ -149,11 +171,20 @@ The model expects preprocessed data:
 
 See the [source repo](https://github.com/shamiquekhan/neuromorphic-sleep-staging-pipeline) for the full preprocessing pipeline.
 
+## Training Details
+
+- **Dataset:** Sleep-EDF Expanded (15 subjects, PhysioNet)
+- **Optimizer:** AdamW (lr=3e-4, weight_decay=1e-2)
+- **Epochs:** 15
+- **Class weights:** N1=2x, REM=2x
+- **Supervision:** All-position (every epoch in 10-epoch window)
+- **Gradient clipping:** max_norm=1.0
+
 ## Intended Use
 
 - Research and educational sleep-stage classification
 - Benchmarking and comparison with other sleep staging methods
-- Edge deployment on resource-constrained devices
+- Edge deployment on resource-constrained devices (MCUs, wearables)
 
 ## Limitations
 
@@ -162,18 +193,14 @@ See the [source repo](https://github.com/shamiquekhan/neuromorphic-sleep-staging
 - Trained on Sleep-EDF Expanded (15 subjects); generalizability should be validated
 - Requires 4-channel PSG (Fpz-Cz, Pz-Oz, EOG, EMG) — single-channel EEG not supported
 
-## Training Details
-
-- **Dataset:** Sleep-EDF Expanded (15 subjects, PhysioNet)
-- **Optimizer:** AdamW (lr=3e-4, weight_decay=1e-2)
-- **Epochs:** 15
-- **Class weights:** N1=2x, REM=2x
-- **Supervision:** All-position (every epoch in 10-epoch window)
-- **Gradient clipping:** max_norm=1.0
-
-## Source
+## Resources
 
-- **GitHub:** [neuromorphic-sleep-staging-pipeline](https://github.com/shamiquekhan/neuromorphic-sleep-staging-pipeline)
+| Resource | Link |
+|----------|------|
+| **Source Code** | [GitHub](https://github.com/shamiquekhan/neuromorphic-sleep-staging-pipeline) |
+| **Live Demo** | [Hugging Face Space](https://huggingface.co/spaces/shamique/neurosleep-demo) |
+| **Reproduce** | [Kaggle Notebook](https://www.kaggle.com/shamiquekhan/neurosleep-final) |
+| **Model Weights** | This page |
 
 ## Citation
 

student_full_finetuned.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:71019269054c170b468735af3536d085b3753879ac5f9a6b9ce64eb18370ab0d
+size 401684