Add architecture-only model card

README.md

@@ -0,0 +1,289 @@
+---
+license: bsd-3-clause
+library_name: braindecode
+pipeline_tag: feature-extraction
+tags:
+  - eeg
+  - biosignal
+  - pytorch
+  - neuroscience
+  - braindecode
+  - convolutional
+---
+
+# EEGSym
+
+EEGSym from Pérez-Velasco et al (2022) .
+
+> **Architecture-only repository.** This repo documents the
+> `braindecode.models.EEGSym` class. **No pretrained weights are
+> distributed here** — instantiate the model and train it on your own
+> data, or fine-tune from a published foundation-model checkpoint
+> separately.
+
+## Quick start
+
+```bash
+pip install braindecode
+```
+
+```python
+from braindecode.models import EEGSym
+
+model = EEGSym(
+    n_chans=22,
+    sfreq=250,
+    input_window_seconds=4.0,
+    n_outputs=4,
+)
+```
+
+The signal-shape arguments above are example defaults — adjust them
+to match your recording.
+
+## Documentation
+
+- Full API reference (parameters, references, architecture figure):
+  <https://braindecode.org/stable/generated/braindecode.models.EEGSym.html>
+- Interactive browser with live instantiation:
+  <https://huggingface.co/spaces/braindecode/model-explorer>
+- Source on GitHub: <https://github.com/braindecode/braindecode/blob/master/braindecode/models/eegsym.py#L16>
+
+## Architecture description
+
+The block below is the rendered class docstring (parameters,
+references, architecture figure where available).
+
+<div class='bd-doc'><main>
+<p>EEGSym from Pérez-Velasco et al (2022) [eegsym2022]_.</p>
+  <span style="display:inline-block;padding:2px 8px;border-radius:4px;background:#5cb85c;color:white;font-size:11px;font-weight:600;margin-right:4px;">Convolution</span>
+
+:bdg-dark-line:`Channel`
+
+   .. figure:: ../../docs/_static/model/eegsym.png
+       :align: center
+       :alt: EEGSym Architecture
+
+
+   The **EEGSym** is a novel Convolutional Neural Network (CNN) architecture designed for
+   Motor Imagery (MI) based Brain-Computer Interfaces (BCIs), primarily aimed at
+   **overcoming inter-subject variability** and significantly **reducing BCI inefficiency**
+   [eegsym2022]_.
+
+   The architecture integrates advances from Deep Learning (DL), complemented by
+   Transfer Learning (TL) techniques and Data Augmentation (DA), to achieve strong
+   performance in inter-subject MI classification [eegsym2022]_.
+
+   .. rubric:: Architectural Overview
+
+   EEGSym systematically incorporates three core features:
+
+   #. **Inception Modules** for multi-scale temporal analysis [eegsym2022]_.
+   #. **Residual Connections** maintain spatio-temporal signal structure and
+      enable deeper feature extraction [eegsym2022]_.
+   #. A **Siamese-network design** exploits the inherent symmetry of the brain
+      across the mid-sagittal plane [eegsym2022]_.
+
+   .. rubric:: Macro Components
+
+   - `EEGSym.symmetric_division` **(Input Processing)**
+       - *Operations.* The input is virtually split into left, right, and middle channels.
+          Middle (central) channels are duplicated and concatenated to both left
+          and right lateralized electrodes to form the two hemisphere inputs [eegsym2022]_.
+       - *Role.* Prepares the data for the siamese-network approach,
+          reducing the number of parameters in the spatial filters
+          for the tempospatial analysis stage [eegsym2022]_.
+
+   - `EEGSym.inception_block` **(Tempospatial Analysis - Temporal Feature Extraction)**
+       - *Operations.* Uses :class:`_InceptionBlock` modules, which apply parallel
+         temporal convolutions with different kernel sizes (scales) [eegsym2022]_.
+         This is followed by concatenation, residual connections, and average
+         pooling for temporal dimensionality reduction [eegsym2022]_.
+       - *Role.* Captures detailed temporal relationships in the architecture,
+         similarly to :class:`~braindecode.models.eeginception_mi.EEGInceptionMI`
+         [eeginception2020]_. The first block uses large temporal kernels
+         (e.g., 500 ms, 250 ms, 125 ms) [eegsym2022]_.
+
+   - `EEGSym.residual_blocks` **(Tempospatial Analysis - Spatial Feature Extraction)**
+       - *Operations.* Composed of multiple :class:`_ResidualBlock` modules (typically three instances)
+         [eegsym2022]_. Each block applies temporal convolution, pooling, and a spatial analysis layer
+         (convolution or grouped convolution) [eegsym2022]_.
+       - *Role.* Enhances spatial feature extraction by incorporating residual
+          connections across all CNN stages, which helps maintain the spatio-temporal
+          structure of the signal through deeper layers [eegsym2022]_.
+
+   - `EEGSym.channel_merging` **(Hemisphere Merging)**
+       - *Operations.* The :class:`_ChannelMergingBlock` reduces the spatial dimensionality
+         (Z and C) to 1, performing two residual convolutions followed by a final grouped
+         convolution that merges the feature information from the two hemispheres [eegsym2022]_.
+       - *Role.* Extracts complex relationships between channels of both hemispheres as part of the
+         symmetry exploitation [eegsym2022]_.
+
+   - `EEGSym.temporal_merging` **(Temporal Collapse)**
+       - *Operations.* The :class:`_TemporalMergingBlock` uses residual convolution
+         followed by grouped convolution to reduce the temporal dimension (S) to 1 [eegsym2022]_.
+       - *Role.* Final step of temporal aggregation before the output module [eegsym2022]_.
+
+   - `EEGSym.output_blocks` **(Output Processing)**
+       - *Operations.* The :class:`_OutputBlock` applies four residual convolution iterations
+         (1x1x1 convolutions) followed by flattening [eegsym2022]_.
+       - *Role.* Final feature refinement through residual connections before the
+         fully connected classification layer [eegsym2022]_.
+
+   .. rubric:: How the information is encoded temporally, spatially, and spectrally
+
+   * **Temporal.**
+       Temporal features are extracted across multiple scales in the inception modules
+       using different temporal convolution kernel sizes (e.g., corresponding to
+       500 ms, 250 ms, and 125 ms windows for a 128 Hz sampling rate), very similar to [eeginception2020]_.
+       Subsequent pooling operations and residual blocks continue to reduce the temporal dimension
+       [eegsym2022]_.
+
+   * **Spatial.**
+
+       Spatial features are extracted via two main mechanisms:
+
+       - (1) The **siamese-network design** implicitly introduces brain symmetry by treating the two hemispheres
+         equally during feature extraction [eegsym2022]_.
+       - (2) **Residual connections** are utilized in the Tempospatial Analysis stage to enhance the extraction of
+         spatial correlations between electrodes [eegsym2022]_.
+
+   * **Spectral.**
+       Spectral information is implicitly captured by the varying kernel sizes of the temporal convolutions
+       in the inception modules [eegsym2022]_. These kernels filter the signal across different temporal windows,
+       corresponding to different frequency characteristics.
+
+   Notes
+   -----
+   * EEGSym achieved competitive accuracies across five large MI datasets [eegsym2022]_.
+   * The model maintained high accuracy using a reduced set of electrodes (8 or 16 channels)
+     [eegsym2022]_.
+   * This is PyTorch implementation of the EEGSym model of the TensorFlow original [eegsym2022code]_.
+
+   Parameters
+   ----------
+   filters_per_branch : int, optional
+       Number of filters in each inception branch. Should be a multiple of 8.
+       Default is 12 [eegsym2022]_.
+   scales_time : tuple of int, optional
+       Temporal scales (in milliseconds) for the temporal convolutions in the first
+       inception module. Default is (500, 250, 125) [eegsym2022]_.
+   drop_prob : float, optional
+       Dropout probability. Default is 0.25 [eegsym2022]_.
+   activation : type[nn.Module], optional
+       Activation function class to use. Default is :class:`nn.ELU` [eegsym2022]_.
+   spatial_resnet_repetitions : int, optional
+       Number of repetitions of the spatial analysis operations at each step.
+       Default is 5 [eegsym2022]_.
+   left_right_chs : list of tuple of str, optional
+       List of tuples pairing left and right hemisphere channel names,
+       e.g., ``[('C3', 'C4'), ('FC5', 'FC6')]``. If not provided, channels
+       are automatically split into left/right hemispheres using
+       :func:`~braindecode.datautil.channel_utils.division_channels_idx` and
+       :func:`~braindecode.datautil.channel_utils.match_hemisphere_chans`.
+       Must be provided together with ``middle_chs`` [eegsym2022]_.
+   middle_chs : list of str, optional
+       List of midline (central) channel names that lie on the mid-sagittal plane,
+       e.g., ``['FZ', 'CZ', 'PZ']``. These channels are duplicated and concatenated
+       to both hemispheres. If not provided, channels are automatically identified
+       using :func:`~braindecode.datautil.channel_utils.division_channels_idx`.
+       Must be provided together with ``left_right_chs`` [eegsym2022]_.
+
+   References
+   ----------
+   .. [eegsym2022] Pérez-Velasco, S., Santamaría-Vázquez, E., Martínez-Cagigal, V.,
+      Marcos-Martínez, D., & Hornero, R. (2022). EEGSym: Overcoming inter-subject
+      variability in motor imagery based BCIs with deep learning. IEEE Transactions
+      on Neural Systems and Rehabilitation Engineering, 30, 1766-1775.
+   .. [eegsym2022code] Pérez-Velasco, S., EEGSym source code.
+       https://github.com/Serpeve/EEGSym
+   .. [eeginception2020] Santamaría-Vázquez, E., Martínez-Cagigal, V.,
+      Vaquerizo-Villar, F., & Hornero, R. (2020). EEG-Inception: A novel deep
+      convolutional neural network for assistive ERP-based brain-computer interfaces.
+      IEEE Transactions on Neural Systems and Rehabilitation Engineering, 28, 2773-2782.
+
+   .. rubric:: Hugging Face Hub integration
+
+   When the optional ``huggingface_hub`` package is installed, all models
+   automatically gain the ability to be pushed to and loaded from the
+   Hugging Face Hub. Install with::
+
+       pip install braindecode[hub]
+
+   **Pushing a model to the Hub:**
+
+   .. code::
+       from braindecode.models import EEGSym
+
+       # Train your model
+       model = EEGSym(n_chans=22, n_outputs=4, n_times=1000)
+       # ... training code ...
+
+       # Push to the Hub
+       model.push_to_hub(
+           repo_id="username/my-eegsym-model",
+           commit_message="Initial model upload",
+       )
+
+   **Loading a model from the Hub:**
+
+   .. code::
+       from braindecode.models import EEGSym
+
+       # Load pretrained model
+       model = EEGSym.from_pretrained("username/my-eegsym-model")
+
+       # Load with a different number of outputs (head is rebuilt automatically)
+       model = EEGSym.from_pretrained("username/my-eegsym-model", n_outputs=4)
+
+   **Extracting features and replacing the head:**
+
+   .. code::
+       import torch
+
+       x = torch.randn(1, model.n_chans, model.n_times)
+       # Extract encoder features (consistent dict across all models)
+       out = model(x, return_features=True)
+       features = out["features"]
+
+       # Replace the classification head
+       model.reset_head(n_outputs=10)
+
+   **Saving and restoring full configuration:**
+
+   .. code::
+       import json
+
+       config = model.get_config()            # all __init__ params
+       with open("config.json", "w") as f:
+           json.dump(config, f)
+
+       model2 = EEGSym.from_config(config)    # reconstruct (no weights)
+
+   All model parameters (both EEG-specific and model-specific such as
+   dropout rates, activation functions, number of filters) are automatically
+   saved to the Hub and restored when loading.
+
+   See :ref:`load-pretrained-models` for a complete tutorial.</main>
+</div>
+
+## Citation
+
+Please cite both the original paper for this architecture (see the
+*References* section above) and braindecode:
+
+```bibtex
+@article{aristimunha2025braindecode,
+  title   = {Braindecode: a deep learning library for raw electrophysiological data},
+  author  = {Aristimunha, Bruno and others},
+  journal = {Zenodo},
+  year    = {2025},
+  doi     = {10.5281/zenodo.17699192},
+}
+```
+
+## License
+
+BSD-3-Clause for the model code (matching braindecode).
+Pretraining-derived weights, if you fine-tune from a checkpoint,
+inherit the licence of that checkpoint and its training corpus.