Add Braindecode-format MIRepNet checkpoint

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dingkun Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,80 @@
+---
+library_name: braindecode
+license: mit
+tags:
+- braindecode
+- eeg
+- motor-imagery
+- foundation-model
+---
+
+# MIRepNet
+
+Braindecode-format re-host of the official MIRepNet checkpoint released by
+Liu et al. The checkpoint can be loaded directly through Braindecode's standard
+Hugging Face integration:
+
+```python
+from braindecode.models import MIRepNet
+
+model = MIRepNet.from_pretrained("braindecode/mirepnet-pretrained")
+
+# Fine-tuning for another task replaces the released three-class head.
+model = MIRepNet.from_pretrained(
+    "braindecode/mirepnet-pretrained",
+    n_outputs=4,
+)
+```
+
+## Released configuration
+
+- 45 channels in the order stored in `mirepnet_channels.json`
+- 1,000 samples at 250 Hz
+- 256-dimensional embedding
+- 6 Transformer blocks with 8 heads
+- 3-output supervised pretraining head
+
+The paper's 8--30 Hz filtering, resampling, channel-template preparation, and
+Euclidean alignment are preprocessing steps and are not performed by the model.
+
+## Provenance and conversion
+
+- Official code: https://github.com/staraink/MIRepNet at revision
+  `edb80d7605f75ba8b72b417a124cc9db07385f72`
+- Official checkpoint: https://huggingface.co/starself/MIRepNet at revision
+  `9bac0439c0d3e9ffdb40ca675d61a51b439a446e`
+- Source file: `MIRepNet.pth`, SHA-256
+  `432288958007e344a5a84a9ffe9d0e5e5c0cb616aef86c85522375a3f4da9aaf`
+
+All 109 downstream tensors were converted. The 34 pretraining-only tensors
+(`mask_token`, `decoder.*`, and the upstream `embedding.chan_embed.weight`,
+which is not used by the released forward pass) were intentionally omitted.
+Against the official implementation, maximum absolute error was `2.38e-7` for
+pooled features and `1.19e-7` for logits. The conversion is reproducible with
+`convert_mirepnet_checkpoint.py`.
+
+The source code and checkpoint are distributed under the MIT License. The
+original copyright notice is preserved in `LICENSE`.
+
+## Limitations
+
+The official repository does not document the semantic ordering of the three
+pretraining-head outputs. Replace the head with `n_outputs=...` and fine-tune it
+for downstream use unless that label mapping has been independently verified.
+Dataset licenses are separate from the checkpoint's MIT license.
+
+## Citation
+
+```bibtex
+@article{LIU2026115966,
+  title = {MIRepNet: A pipeline and pre-trained model for EEG-based motor imagery classification},
+  journal = {Knowledge-Based Systems},
+  volume = {343},
+  pages = {115966},
+  year = {2026},
+  issn = {0950-7051},
+  doi = {10.1016/j.knosys.2026.115966},
+  url = {https://www.sciencedirect.com/science/article/pii/S0950705126006921},
+  author = {Dingkun Liu and Zhu Chen and Jingwei Luo and Shijie Lian and Yuheng Chen and Shaojie Hou and Xiaolian Zhu and Dongrui Wu}
+}
+```

config.json

@@ -0,0 +1,25 @@
+{
+  "n_outputs": 3,
+  "n_chans": 45,
+  "chs_info": null,
+  "n_times": 1000,
+  "input_window_seconds": null,
+  "sfreq": 250,
+  "embed_dim": 256,
+  "n_filters_time": 64,
+  "n_filters_spat": 128,
+  "filter_time_length": 25,
+  "pool_time_length": 75,
+  "pool_time_stride": 15,
+  "num_layers": 6,
+  "num_heads": 8,
+  "feedforward_expansion": 4,
+  "activation": "torch.nn.modules.activation.ELU",
+  "activation_trans": "torch.nn.modules.activation.GELU",
+  "drop_prob": 0.5,
+  "att_drop_prob": 0.5,
+  "feedforward_drop_prob": 0.5,
+  "attention_scale": null,
+  "return_features": false,
+  "braindecode_version": "1.8.0dev0"
+}

convert_mirepnet_checkpoint.py

@@ -0,0 +1,43 @@
+"""Convert the official MIRepNet checkpoint to Braindecode Hub format."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+from pathlib import Path
+
+import torch
+
+from braindecode.models import MIRepNet
+
+
+SOURCE_SHA256 = "432288958007e344a5a84a9ffe9d0e5e5c0cb616aef86c85522375a3f4da9aaf"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("source", type=Path)
+    parser.add_argument("output", type=Path)
+    args = parser.parse_args()
+
+    if hashlib.sha256(args.source.read_bytes()).hexdigest() != SOURCE_SHA256:
+        raise ValueError("Source checkpoint SHA-256 does not match the official file.")
+
+    source = torch.load(args.source, map_location="cpu", weights_only=True)
+    model = MIRepNet(n_chans=45, n_outputs=3, n_times=1000, sfreq=250)
+    incompatible = model.load_state_dict(source, strict=False)
+    expected_unexpected = {
+        "mask_token",
+        "embedding.chan_embed.weight",
+        *(key for key in source if key.startswith("decoder.")),
+    }
+    if (
+        incompatible.missing_keys
+        or set(incompatible.unexpected_keys) != expected_unexpected
+    ):
+        raise RuntimeError(f"Unexpected conversion result: {incompatible}")
+    model.save_pretrained(args.output)
+
+
+if __name__ == "__main__":
+    main()

mirepnet_channels.json

@@ -0,0 +1,47 @@
+[
+  "F7",
+  "F5",
+  "F3",
+  "F1",
+  "FZ",
+  "F2",
+  "F4",
+  "F6",
+  "F8",
+  "FT7",
+  "FC5",
+  "FC3",
+  "FC1",
+  "FCZ",
+  "FC2",
+  "FC4",
+  "FC6",
+  "FT8",
+  "T7",
+  "C5",
+  "C3",
+  "C1",
+  "CZ",
+  "C2",
+  "C4",
+  "C6",
+  "T8",
+  "TP7",
+  "CP5",
+  "CP3",
+  "CP1",
+  "CPZ",
+  "CP2",
+  "CP4",
+  "CP6",
+  "TP8",
+  "P7",
+  "P5",
+  "P3",
+  "P1",
+  "PZ",
+  "P2",
+  "P4",
+  "P6",
+  "P8"
+]

model.safetensors

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

pytorch_model.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:59aae4feec85074ba7ab7f7e492b281cb861f0e529d5bf1dbd81c0ca04b2a3aa
+size 20613566