Initial deploy: braindecode model architecture browser

README.md

@@ -1,12 +1,89 @@
 ---
-title: Model Explorer
-emoji: 🦀
-colorFrom: purple
-colorTo: red
+title: Braindecode Model Explorer
+emoji: 🧠
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.13.0
+sdk_version: 4.44.0
 app_file: app.py
 pinned: false
+license: bsd-3-clause
+short_description: Browse 57 EEG / biosignal architectures from braindecode
+tags:
+  - eeg
+  - meg
+  - ecog
+  - biosignal
+  - pytorch
+  - neuroscience
+  - brain-computer-interface
+  - deep-learning
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Braindecode Model Explorer
+
+Interactive browser for **57 EEG / biosignal model architectures** from
+[`braindecode`](https://braindecode.org).
+
+For each model you can:
+
+- read the rendered docstring (architecture figure, parameters, references);
+- configure the input signal shape (`n_chans`, `sfreq`, `input_window_seconds`, `n_outputs`);
+- instantiate the model live and inspect parameter count, layer summary
+  (via `torchinfo`), and output shape on a dummy forward pass.
+
+> **No pretrained weights are loaded** — this Space is a pure architecture
+> explorer, runs on the free CPU tier, and never downloads checkpoints.
+> For curated foundation-model weights, see
+> [`huggingface.co/braindecode`](https://huggingface.co/braindecode).
+
+## Models included
+
+All classes that subclass `braindecode.models.base.EEGModuleMixin`,
+auto-discovered at startup. Examples by family:
+
+| Family | Examples |
+|---|---|
+| Foundation models | BIOT, BENDR, SignalJEPA, Labram, EEGPT, CodeBrain, LUNA |
+| Convolutional | EEGNet, Deep4Net, ShallowFBCSPNet, EEGITNet, EEGNeX |
+| Transformer | EEGConformer, ATCNet, MSVTNet, MEDFormer, CTNet |
+| Sleep staging | USleep, SleepStagerChambon2018, AttnSleep, DeepSleepNet |
+| Filter-bank | FBCNet, FBLightConvNet, FBMSNet, IFNet |
+| Other | DGCNN, TSception, SyncNet, REVE, SCCNet |
+
+## Local development
+
+```bash
+pip install -r requirements.txt
+python app.py
+```
+
+Open <http://localhost:7860>.
+
+## How docstrings are rendered
+
+Braindecode docstrings use NumpyDoc + Sphinx extensions (`.. figure::`,
+`:bdg-danger:`, `.. versionadded::`). The `docstring_renderer` module
+maps Sphinx-only directives to plain rST, then renders to HTML via
+`docutils`. No Sphinx build is needed at runtime — the Space stays
+dependency-light and rebuilds in seconds.
+
+## Citation
+
+```bibtex
+@article{HBM:HBM23730,
+  author  = {Schirrmeister, Robin Tibor and Springenberg, Jost Tobias
+             and Fiederer, Lukas Dominique Josef and Glasstetter, Martin
+             and Eggensperger, Katharina and Tangermann, Michael and Hutter,
+             Frank and Burgard, Wolfram and Ball, Tonio},
+  title   = {Deep learning with convolutional neural networks for EEG
+             decoding and visualization},
+  journal = {Human Brain Mapping},
+  year    = {2017},
+  doi     = {10.1002/hbm.23730},
+}
+```
+
+## License
+
+BSD-3-Clause, matching the upstream braindecode library.

app.py

@@ -0,0 +1,272 @@
+"""Braindecode Model Explorer — interactive architecture browser.
+
+This Hugging Face Space lets users browse all 57 EEG model architectures
+in braindecode, read the rendered docstring (parameters, references,
+architecture figure), and instantiate any model with custom signal
+shape to inspect its parameter count and layer summary.
+
+No pretrained weights are loaded — this is a pure architecture explorer.
+
+Run locally:
+    pip install -r requirements.txt
+    python app.py
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+import gradio as gr
+import torch
+from torchinfo import summary
+
+import braindecode.models as M
+from braindecode.models.base import EEGModuleMixin
+
+from docstring_renderer import (
+    get_signature_str,
+    get_source_link,
+    render_docstring_html,
+)
+
+# ---------------------------------------------------------------------------
+# Catalog: discover every EEGModuleMixin subclass exported by braindecode.
+# ---------------------------------------------------------------------------
+
+def _discover_models() -> dict[str, type]:
+    catalog: dict[str, type] = {}
+    for name in sorted(getattr(M, "__all__", []) or dir(M)):
+        if name.startswith("_"):
+            continue
+        obj = getattr(M, name, None)
+        if (
+            inspect.isclass(obj)
+            and issubclass(obj, EEGModuleMixin)
+            and obj is not EEGModuleMixin
+        ):
+            catalog[name] = obj
+    return catalog
+
+
+MODELS: dict[str, type] = _discover_models()
+MODEL_NAMES: list[str] = sorted(MODELS.keys())
+
+# ---------------------------------------------------------------------------
+# Heuristic defaults for the signal-shape form. Different model families
+# expect very different inputs (sleep stagers want 30 s @ 100 Hz; motor-
+# imagery models want ~4 s @ 250 Hz). Pick a reasonable default per family.
+# ---------------------------------------------------------------------------
+
+DEFAULTS = {
+    "sleep": dict(n_chans=2, sfreq=100, input_window_seconds=30.0, n_outputs=5),
+    "biot": dict(n_chans=16, sfreq=200, input_window_seconds=10.0, n_outputs=2),
+    "bendr": dict(n_chans=20, sfreq=256, input_window_seconds=4.0, n_outputs=2),
+    "labram": dict(n_chans=22, sfreq=200, input_window_seconds=4.0, n_outputs=2),
+    "default": dict(n_chans=22, sfreq=250, input_window_seconds=4.0, n_outputs=4),
+}
+
+
+def _defaults_for(name: str) -> dict[str, Any]:
+    lower = name.lower()
+    if "sleep" in lower or name in {"USleep", "AttnSleep", "DeepSleepNet"}:
+        return DEFAULTS["sleep"]
+    if "biot" in lower:
+        return DEFAULTS["biot"]
+    if "bendr" in lower:
+        return DEFAULTS["bendr"]
+    if "labram" in lower or "cbramod" in lower or "eegpt" in lower:
+        return DEFAULTS["labram"]
+    return DEFAULTS["default"]
+
+
+# ---------------------------------------------------------------------------
+# Rendering helpers
+# ---------------------------------------------------------------------------
+
+def _info_card(name: str) -> str:
+    cls = MODELS[name]
+    sig = get_signature_str(cls)
+    link = get_source_link(cls)
+    link_html = (
+        f'<a href="{link}" target="_blank" '
+        f'style="color:#0072B2;text-decoration:none;">View source on GitHub →</a>'
+        if link
+        else ""
+    )
+    return (
+        f"<div style='background:#f6f8fa;padding:12px 16px;border-radius:8px;"
+        f"border:1px solid #d0d7de;margin-bottom:12px;'>"
+        f"<div style='font-size:1.3em;font-weight:600;color:#0072B2;"
+        f"margin-bottom:4px;'>{name}</div>"
+        f"<div style='font-family:Menlo,Consolas,monospace;font-size:0.82em;"
+        f"color:#475569;margin-bottom:6px;word-break:break-all;'>{sig}</div>"
+        f"<div style='font-size:0.9em;'>{link_html}</div>"
+        f"</div>"
+    )
+
+
+def show_model(name: str) -> tuple[str, str, dict, dict, dict, dict]:
+    """Update info card, rendered docstring, and form defaults."""
+    if name not in MODELS:
+        return "", "", {}, {}, {}, {}
+    info = _info_card(name)
+    doc_html = render_docstring_html(MODELS[name].__doc__)
+    d = _defaults_for(name)
+    return (
+        info,
+        doc_html,
+        gr.update(value=d["n_chans"]),
+        gr.update(value=d["sfreq"]),
+        gr.update(value=d["input_window_seconds"]),
+        gr.update(value=d["n_outputs"]),
+    )
+
+
+def instantiate(
+    name: str,
+    n_chans: int,
+    sfreq: float,
+    window_s: float,
+    n_outputs: int,
+) -> tuple[str, str]:
+    """Instantiate the selected model and run a dummy forward pass."""
+    if name not in MODELS:
+        return "Pick a model first.", ""
+
+    cls = MODELS[name]
+    n_times = int(round(window_s * sfreq))
+
+    kwargs = dict(
+        n_chans=int(n_chans),
+        sfreq=float(sfreq),
+        input_window_seconds=float(window_s),
+        n_outputs=int(n_outputs),
+    )
+
+    # Drop kwargs the class does not accept (some models do not take all
+    # of these in __init__; the mixin infers what it can).
+    sig_params = set(inspect.signature(cls.__init__).parameters)
+    kwargs = {k: v for k, v in kwargs.items() if k in sig_params}
+
+    try:
+        model = cls(**kwargs)
+    except Exception as exc:  # noqa: BLE001 — surface any constructor error
+        return f"❌ **Failed to instantiate `{name}`** with `{kwargs}`:\n```\n{exc}\n```", ""
+
+    n_params = sum(p.numel() for p in model.parameters())
+    n_train = sum(p.numel() for p in model.parameters() if p.requires_grad)
+
+    try:
+        info = summary(
+            model,
+            input_size=(1, int(n_chans), n_times),
+            depth=3,
+            verbose=0,
+            col_names=("output_size", "num_params"),
+        )
+        summary_str = str(info)
+    except Exception as exc:  # noqa: BLE001
+        summary_str = f"(torchinfo summary unavailable: {exc})"
+
+    try:
+        x = torch.randn(2, int(n_chans), n_times)
+        with torch.no_grad():
+            y = model(x)
+        out_shape = tuple(y.shape) if hasattr(y, "shape") else type(y).__name__
+    except Exception as exc:  # noqa: BLE001
+        out_shape = f"forward failed: {exc}"
+
+    header = (
+        f"### `{name}` instantiated\n\n"
+        f"| metric | value |\n|---|---|\n"
+        f"| total parameters | **{n_params:,}** |\n"
+        f"| trainable parameters | {n_train:,} |\n"
+        f"| input shape | `(batch, {n_chans}, {n_times})` |\n"
+        f"| output shape | `{out_shape}` |\n"
+        f"| input window | {window_s} s @ {sfreq} Hz |\n"
+    )
+    return header, f"```\n{summary_str}\n```"
+
+
+# ---------------------------------------------------------------------------
+# UI
+# ---------------------------------------------------------------------------
+
+INTRO = """
+# Braindecode Model Explorer
+
+Browse **57 EEG / biosignal model architectures** from
+[braindecode](https://braindecode.org). Read the rendered docstring,
+configure signal shape, and instantiate any model live to inspect its
+parameter count and layer summary.
+
+> No pretrained weights are loaded — this is a pure architecture browser.
+> For weights, see [`huggingface.co/braindecode`](https://huggingface.co/braindecode).
+"""
+
+
+def build_app() -> gr.Blocks:
+    with gr.Blocks(
+        title="Braindecode Model Explorer",
+        theme=gr.themes.Soft(primary_hue="blue"),
+    ) as app:
+        gr.Markdown(INTRO)
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                model_dd = gr.Dropdown(
+                    choices=MODEL_NAMES,
+                    value="EEGNetv4",
+                    label="Architecture",
+                    interactive=True,
+                )
+                info_html = gr.HTML(_info_card("EEGNetv4"))
+
+                gr.Markdown("### Signal configuration")
+                with gr.Group():
+                    n_chans = gr.Number(value=22, label="n_chans", precision=0)
+                    sfreq = gr.Number(value=250, label="sfreq (Hz)")
+                    window_s = gr.Number(
+                        value=4.0, label="input_window_seconds"
+                    )
+                    n_outputs = gr.Number(
+                        value=4, label="n_outputs", precision=0
+                    )
+                run_btn = gr.Button("Instantiate model", variant="primary")
+
+            with gr.Column(scale=2):
+                with gr.Tabs():
+                    with gr.TabItem("Documentation"):
+                        doc_html = gr.HTML(
+                            render_docstring_html(MODELS["EEGNetv4"].__doc__)
+                        )
+                    with gr.TabItem("Live instance"):
+                        result_md = gr.Markdown(
+                            "_Press **Instantiate model** to build the network._"
+                        )
+                        summary_md = gr.Markdown()
+
+        # wiring
+        model_dd.change(
+            show_model,
+            inputs=model_dd,
+            outputs=[info_html, doc_html, n_chans, sfreq, window_s, n_outputs],
+        )
+        run_btn.click(
+            instantiate,
+            inputs=[model_dd, n_chans, sfreq, window_s, n_outputs],
+            outputs=[result_md, summary_md],
+        )
+
+        gr.Markdown(
+            "---\nMade with [braindecode](https://braindecode.org) · "
+            "Source: [github.com/braindecode/braindecode]"
+            "(https://github.com/braindecode/braindecode)"
+        )
+
+    return app
+
+
+if __name__ == "__main__":
+    build_app().launch()

docstring_renderer.py

@@ -0,0 +1,196 @@
+"""Render braindecode rST docstrings to HTML for the model-explorer Space.
+
+Braindecode docstrings use NumpyDoc + Sphinx extensions:
+  .. figure::          (architecture image)
+  :bdg-danger:         (sphinx-design colored badges)
+  .. versionadded::    (Sphinx admonition)
+  .. important::       (admonition)
+  .. code-block::      (highlighted code)
+  [ref]_               (NumpyDoc citation reference)
+
+Pure docutils does not know about the Sphinx directives. Rather than
+spinning up a full Sphinx build inside the Space, we:
+
+1. Pre-process the docstring with regex substitutions that map
+   Sphinx-only directives to plain rST equivalents docutils can parse.
+2. Hand the result to docutils.publish_parts for rST -> HTML.
+3. Wrap with a small CSS style block that matches braindecode.org colors.
+
+This keeps the Space dependency-light (no sphinx at runtime) while still
+rendering figures, headings, parameter tables, and references.
+"""
+
+from __future__ import annotations
+
+import inspect
+import re
+from textwrap import dedent
+
+from docutils.core import publish_parts
+from docutils.utils import SystemMessage
+
+_BADGE_COLORS = {
+    "bdg-danger": "#d9534f",
+    "bdg-success": "#5cb85c",
+    "bdg-primary": "#0072B2",
+    "bdg-info": "#56B4E9",
+    "bdg-warning": "#E69F00",
+    "bdg-secondary": "#6c757d",
+    "bdg-light": "#f0f0f0",
+    "bdg-dark": "#343a40",
+}
+
+_BADGE_RE = re.compile(r":(bdg-[a-z]+):`([^`]+)`")
+_VERSIONADDED_RE = re.compile(r"^\.\. versionadded::\s*(.+)$", re.MULTILINE)
+_VERSIONCHANGED_RE = re.compile(r"^\.\. versionchanged::\s*(.+)$", re.MULTILINE)
+_CODE_BLOCK_RE = re.compile(r"^(\s*)\.\. code-block::\s*(\w+)?\s*$", re.MULTILINE)
+
+
+def _replace_badges(text: str) -> str:
+    """Convert :bdg-danger:`Foundation Model` to inline raw HTML."""
+
+    def repl(match: re.Match) -> str:
+        cls, label = match.group(1), match.group(2)
+        color = _BADGE_COLORS.get(cls, "#888")
+        # Use rST raw HTML inline pass-through.
+        return (
+            f"\n\n.. raw:: html\n\n"
+            f"   <span style=\"display:inline-block;padding:2px 8px;"
+            f"border-radius:4px;background:{color};color:white;"
+            f"font-size:11px;font-weight:600;margin-right:4px;\">{label}</span>\n\n"
+        )
+
+    return _BADGE_RE.sub(repl, text)
+
+
+def _replace_versionadded(text: str) -> str:
+    """Convert Sphinx versionadded/versionchanged to plain admonitions."""
+    text = _VERSIONADDED_RE.sub(
+        r".. note::\n\n   *New in version \1.*", text
+    )
+    text = _VERSIONCHANGED_RE.sub(
+        r".. note::\n\n   *Changed in version \1.*", text
+    )
+    return text
+
+
+def _normalize_code_block(text: str) -> str:
+    """Convert `.. code-block:: python` to vanilla `.. code::` (docutils-OK)."""
+
+    def repl(match: re.Match) -> str:
+        indent, lang = match.group(1), match.group(2) or ""
+        return f"{indent}.. code:: {lang}".rstrip()
+
+    return _CODE_BLOCK_RE.sub(repl, text)
+
+
+def _strip_unsupported_directives(text: str) -> str:
+    """Drop directives that docutils cannot parse and we do not want rendered.
+
+    Currently: rubric (treated as a small heading) and bibliography-only items.
+    """
+    text = re.sub(r"^\.\. rubric::\s*(.+)$", r"\n**\1**\n", text, flags=re.MULTILINE)
+    return text
+
+
+def preprocess_docstring(doc: str) -> str:
+    """Apply all rST → docutils-friendly transformations."""
+    if not doc:
+        return ""
+    doc = dedent(doc)
+    doc = _replace_badges(doc)
+    doc = _replace_versionadded(doc)
+    doc = _normalize_code_block(doc)
+    doc = _strip_unsupported_directives(doc)
+    return doc
+
+
+_STYLE = """
+<style>
+  .bd-doc { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
+            sans-serif; line-height: 1.55; color: #1f2937; }
+  .bd-doc h1, .bd-doc h2, .bd-doc h3 { color: #0072B2; margin-top: 1.2em; }
+  .bd-doc h1 { font-size: 1.5em; border-bottom: 2px solid #0072B2; padding-bottom: 4px; }
+  .bd-doc h2 { font-size: 1.2em; }
+  .bd-doc h3 { font-size: 1.05em; }
+  .bd-doc pre { background: #f6f8fa; padding: 10px 12px; border-radius: 6px;
+                font-size: 0.9em; overflow-x: auto; }
+  .bd-doc code { background: #f0f0f5; padding: 1px 5px; border-radius: 3px;
+                 font-size: 0.9em; }
+  .bd-doc pre code { background: transparent; padding: 0; }
+  .bd-doc img { max-width: 480px; display: block; margin: 12px auto;
+                border-radius: 6px; }
+  .bd-doc table { border-collapse: collapse; margin: 8px 0; }
+  .bd-doc th, .bd-doc td { border: 1px solid #d0d7de; padding: 4px 10px;
+                           text-align: left; }
+  .bd-doc th { background: #f6f8fa; }
+  .bd-doc .admonition { border-left: 4px solid #0072B2; background: #f0f7ff;
+                        padding: 8px 14px; margin: 12px 0; border-radius: 4px; }
+  .bd-doc .admonition.important { border-color: #D55E00; background: #fdf6ec; }
+  .bd-doc .admonition.note { border-color: #009E73; background: #effaf3; }
+  .bd-doc .admonition-title { font-weight: 600; margin-bottom: 4px; }
+  .bd-doc dl.field-list { display: grid; grid-template-columns: max-content auto;
+                          gap: 4px 12px; }
+  .bd-doc dl.field-list dt { font-weight: 600; color: #475569; }
+</style>
+"""
+
+
+def render_docstring_html(doc: str | None) -> str:
+    """Render an rST docstring to a self-contained HTML fragment.
+
+    Returns a string with embedded <style> + <div class="bd-doc">…</div>.
+    Failures fall back to a <pre> dump so the Space never blanks out.
+    """
+    if not doc:
+        return _STYLE + "<div class='bd-doc'><em>No docstring available.</em></div>"
+
+    processed = preprocess_docstring(doc)
+    try:
+        parts = publish_parts(
+            source=processed,
+            writer_name="html5",
+            settings_overrides={
+                "report_level": 5,  # suppress all docutils warnings
+                "halt_level": 5,
+                "embed_stylesheet": False,
+                "input_encoding": "unicode",
+                "output_encoding": "unicode",
+                "doctitle_xform": False,
+                "initial_header_level": 2,
+            },
+        )
+        body = parts["html_body"]
+    except SystemMessage as exc:  # pragma: no cover — defensive
+        body = f"<pre>{processed}</pre><p><em>(rST parse error: {exc})</em></p>"
+
+    return _STYLE + f"<div class='bd-doc'>{body}</div>"
+
+
+def get_signature_str(cls: type) -> str:
+    """Return the formatted __init__ signature for display."""
+    try:
+        sig = inspect.signature(cls.__init__)
+        return f"{cls.__name__}{sig}"
+    except (ValueError, TypeError):
+        return f"{cls.__name__}(...)"
+
+
+def get_source_link(cls: type, branch: str = "master") -> str | None:
+    """Return a github link to the class definition."""
+    try:
+        module = inspect.getmodule(cls)
+        if module is None or not hasattr(module, "__file__"):
+            return None
+        rel_path = module.__file__.split("braindecode/", 1)[-1]
+        rel_path = "braindecode/" + rel_path
+        try:
+            _, lineno = inspect.getsourcelines(cls)
+        except OSError:
+            lineno = 1
+        return (
+            f"https://github.com/braindecode/braindecode/blob/{branch}/"
+            f"{rel_path}#L{lineno}"
+        )
+    except Exception:
+        return None

requirements.txt

@@ -0,0 +1,7 @@
+braindecode>=1.5
+torch>=2.0
+torchinfo>=1.8
+gradio>=4.44
+docutils>=0.20
+mne>=1.11
+huggingface_hub>=0.20