Open-sourcing FEMBA

README.md

@@ -1,3 +1,216 @@
----
-license: mit
----
+---
+license: cc-by-nd-4.0
+language:
+- en
+---
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/pulp-bio/BioFoundation/refs/heads/main/docs/model/logo/FEMBA_logo.png" alt="FEMBA Logo" width="800"/>
+  <h1>FEMBA: Foundational Encoder Model with Bidirectional Mamba for EEG</h1>
+</div>
+<p align="center">
+  <a href="https://github.com/pulp-bio/BioFoundation">
+    <img src ="https://img.shields.io/github/stars/pulp-bio/BioFoundation?color=ccf" alt="Github">
+  </a>
+  <a href="https://creativecommons.org/licenses/by-nd/4.0/">
+    <img src="https://img.shields.io/badge/License-CC_BY--ND_4.0-lightgrey.svg" alt="License">
+  </a>
+  <a href="https://arxiv.org/abs/2502.06438">
+    <img src="https://img.shields.io/badge/arXiv-2502.06438-b31b1b.svg" alt="Paper">
+  </a>
+</p>
+
+**FEMBA** is a powerful and efficient foundation model for **EEG signal analysis**, built upon a **bidirectional Mamba** state-space architecture. It supports **self-supervised pre-training** via masked reconstruction and **end-to-end supervised fine-tuning** for multiple downstream tasks (abnormal EEG, artifact detection, slowing classification). By using linear-time state-space modeling instead of quadratic attention, FEMBA scales to long EEG sequences and constrained hardware while remaining performant.
+
+---
+
+## 🔒 License & Usage Policy (Weights)
+
+**Weights license:** The released model weights are licensed under **Creative Commons Attribution–NoDerivatives 4.0 (CC BY-ND 4.0)**. This section summarizes the practical implications for users. *This is not legal advice; please read the full license text.*
+
+### ✅ You may
+- **Use** and **redistribute** the **unmodified** FEMBA weights (including in commercial settings) **with proper attribution** to the FEMBA authors.
+- **Fine-tune / adapt** the weights **for your internal use** (research or production) **without redistributing** the modified weights.
+- **Publish your code, configs, logs, and papers** describing experiments with FEMBA (please cite the paper).
+
+### 🚫 You may not
+- **Share, host, or redistribute any modified weights** (including LoRA/adapter/delta checkpoints or pruned/quantized variants). Any parameter set that encodes an adaptation is considered a derivative and cannot be shared under CC BY-ND 4.0.
+- **Imply endorsement** by the FEMBA authors for any derivative or evaluation without our written permission.
+- **Use the FEMBA name** in a way that suggests your modified model is an official FEMBA release.
+
+### 🤝 How to contribute improvements (PR-gated releases)
+We welcome community improvements via a **pull-request (PR)** workflow. If you believe your improvements should become an **official FEMBA release**:
+1. **Open a PR** in the [BioFoundation repository](https://github.com/pulp-bio/BioFoundation) describing the change (architecture/head/training recipe, datasets, preprocessing, compute).
+2. Include **reproducibility artifacts**: configs, seeds, scripts, environment details, training/validation logs, and the **evaluation protocol** (e.g., TUAB/TUAR/TUSL) with exact splits.
+3. Provide **comprehensive results** (AUROC/AUPR/BA, FLOPs, memory) vs. the baselines reported in the FEMBA paper.
+4. After **maintainer review**, approved changes will be **retrained/validated** and, if accepted, **released by the maintainers** as a new **official FEMBA** checkpoint under **CC BY-ND 4.0**.
+
+> Rationale: CC BY-ND protects users from fragmented, lower-quality “FEMBA variants,” while still enabling internal fine-tuning and a path for the community to upstream improvements through review.
+
+---
+
+## 🔎 Model Summary
+
+- **Architecture:** Bidirectional Mamba encoder with a 2D-conv tokenizer (patching over channels × time), random masking (60%) for SSL, and either a lightweight linear head or a Mamba-enhanced head for downstream tasks. Hidden state size is fixed at 80 across variants.
+- **Scaling:** Linear time & memory in sequence length (state-space model), enabling efficient long-context EEG modeling and on-device scenarios.
+- **Pre-training data:** >21,000 hours of unlabeled clinical EEG from Temple University Hospital (TUEG). Subjects overlapping with TUAB/TUAR/TUSL are removed to prevent leakage.
+- **Downstream tasks:** TUAB abnormal/normal (binary), TUAR artifact detection (BC/MC/MMC/MCC), TUSL slowing (4-class). TUAB uses its predefined split; TUAR/TUSL use 80/10/10 splits.
+- **Optimization (typical):** Pre-training with Smooth L1 masked-patch reconstruction; fine-tuning with Adam (LR 1e-4), cosine decay, early stopping; layer-wise LR decay factor 0.75.
+
+---
+
+## 🚀 Model Variants
+
+| Variant | Parameters | (num_blocks, embed_dim) |
+| :--- | :--- | :--- |
+| **FEMBA-tiny** | 7.8M | (2, 35) |
+| **FEMBA-base** | 47.7M | (12, 35) |
+| **FEMBA-large** | 77.8M | (4, 79) |
+| **FEMBA-huge** | 386M | (20, 79) |
+
+*Hidden state size is 80 for all variants; blocks correspond to Bi-Mamba layers in the encoder.*
+
+---
+
+## 🧠 Intended Use & Limitations
+
+**Intended use.** Research on EEG representation learning and downstream classification (e.g., abnormal EEG detection, artifact detection, slowing classification). FEMBA is particularly useful when long sequences or limited compute/memory preclude quadratic-cost attention.
+
+**Out-of-scope / limitations.**
+- **Not a medical device.** Outputs are research signals and **must not** be used for clinical decision-making without appropriate validation and regulatory processes.
+- **Domain shift.** Performance can degrade across cohorts (e.g., neonatal vs. adult EEG) and label protocols; domain adaptation is encouraged.
+- **Class imbalance.** On some tasks (e.g., TUSL), AUROC may be strong while AUPR can trail attention baselines, highlighting sensitivity to class imbalance and protocol specifics.
+
+---
+
+## 🏗️ Architecture & Training Details
+
+**Tokenizer & patches.** Raw EEG (C×T) is quartile-normalized per channel (IQR scaling) and tokenized with a 2D convolution over channel×time patches (e.g., 4×32) with learnable positional embeddings.
+
+**Self-supervised objective.** Randomly mask **60%** of patches; reconstruct masked content with a lightweight decoder using **Smooth L1** loss (computed on masked patches only).
+
+**Encoder.** Stacked **Bidirectional Mamba** blocks (forward + backward over a reversed copy), merged and residually connected; hidden size fixed to 80.
+
+**Fine-tuning heads.**
+- *Linear classifier:* small MLP (≈0.5M params).
+- *Mamba-enhanced classifier:* adds one Mamba block before the linear layer (up to ≈0.7M params).
+
+**Optimization notes.** Layer-wise LR decay (0.75); fine-tuning with Adam (initial LR 1e-4), cosine decay, early stopping; end-to-end updates (encoder + head).
+
+---
+
+## 📚 Training Data
+
+- **Pre-training:** Temple University Hospital EEG (TUEG), ~21k hours, ~15k subjects; broad clinical coverage. Overlaps with TUAB/TUAR/TUSL removed to avoid leakage.
+- **Downstream:**  
+  - **TUAB** (abnormal vs normal; predefined split).  
+  - **TUAR** (artifact detection, BC/MC/MMC/MCC protocols; randomized 80/10/10).  
+  - **TUSL** (4-class slowing/seizure/complex/normal; randomized 80/10/10).
+
+*See paper for dataset licenses and curation details; users are responsible for complying with source dataset terms.*
+
+---
+
+## 🔧 How to Use
+
+FEMBA weights are organized by downstream task:
+
+- **`TUAB/`** → base/large variants pre-trained on TUEG (excluding TUAB), for TUAB abnormal EEG.  
+- **`TUAR/`** → tiny/base/large variants pre-trained on TUEG (excluding TUAR), for TUAR artifact detection.  
+- **`TUSL/`** → variants pre-trained on TUEG (excluding TUSL), for TUSL slowing classification.
+
+**Example:** fine-tune TUAR with the base checkpoint:
+
+```
+TUAR/base.safetensors
+```
+
+Open `run_train.py` from the [BioFoundation GitHub repository](https://github.com/pulp-bio/BioFoundation.git) and configure:
+
+```python
+# Set paths (example)
+os.environ['DATA_PATH'] = "/path/to/dataset"
+os.environ['CHECKPOINT_DIR'] = "/my_directory/TUAR/base.safetensors"
+```
+
+Then launch fine-tuning (Hydra):
+
+```bash
+python -u run_train.py +experiment=FEMBA_finetune
+```
+
+**Environment variables**  
+- `DATA_PATH`: directory of the fine-tuning dataset.  
+- `CHECKPOINT_DIR`: path to the chosen task-specific checkpoint.
+
+---
+
+## 📊 Results (Key Highlights)
+
+**TUAB (Abnormal EEG Detection)**  
+- **FEMBA-Huge:** **81.82%** balanced accuracy, **0.892** AUROC.
+
+**TUAR (Artifact Detection)**  
+- **Binary (BC):** **FEMBA-Base** AUROC **0.949**, AUPR **0.932**.
+
+**TUSL (Slowing Classification, 4-class)**  
+- **FEMBA-Base:** AUROC **0.731**.
+
+> Full metrics, protocols, and comparisons—including MC/MMC on TUAR and multiple FEMBA sizes—are reported in the paper.
+
+---
+
+## ⚡ Efficiency
+
+FEMBA provides strong accuracy with reduced compute/memory relative to Transformer baselines:
+
+- **FEMBA-Huge (386M):** ~**58.7B FLOPs**, ~**30% less** memory than comparable Transformer baselines, with competitive TUAB accuracy.
+- **FEMBA-Tiny (7.8M):** ~**1.31B FLOPs**—substantially fewer than large Transformer baselines—while achieving strong TUAR MCC performance.
+- **FEMBA-Base (47.7M):** ~**7.52B FLOPs**, markedly lower than many attention-based baselines.
+
+See the paper for details on measurement setup and baseline references.
+
+---
+
+## ✅ Responsible AI, Risks & Biases
+
+- **Clinical safety:** This model is **not** a certified medical device and should **not** be used for diagnosis. Human oversight is required.  
+- **Bias & drift:** Clinical EEG cohorts vary by device, montage, age, and pathology. Expect distribution shift and validate locally; consider domain adaptation (e.g., neonatal vs adult).  
+- **Artifacts:** While artifact detection is strong, rare/complex artifacts may still be misclassified; use robust pre-processing and QC procedures.
+
+---
+
+## 🔗 Sources
+
+- **Code:** https://github.com/pulp-bio/BioFoundation  
+- **Paper:** FEMBA: Efficient and Scalable EEG Analysis with a Bidirectional Mamba Foundation Model (arXiv:2502.06438).
+
+---
+
+## 📜 Citation
+
+If you use FEMBA in your research, please cite:
+
+```bibtex
+@misc{tegon2025fembaefficientscalableeeg,
+      title={FEMBA: Efficient and Scalable EEG Analysis with a Bidirectional Mamba Foundation Model}, 
+      author={Anna Tegon and Thorir Mar Ingolfsson and Xiaying Wang and Luca Benini and Yawei Li},
+      year={2025},
+      eprint={2502.06438},
+      archivePrefix={arXiv},
+      primaryClass={cs.LG},
+      url={https://arxiv.org/abs/2502.06438}
+}
+```
+
+---
+
+## 🛠️ Maintenance & Contact
+
+- **Issues & support:** please open a GitHub issue in the BioFoundation repository.
+
+---
+
+## 🗒️ Changelog
+
+- **v1.0:** Initial release of FEMBA model card with task-specific checkpoints and instructions.