Replace with clean markdown card

README.md

@@ -13,13 +13,12 @@ tags:
 
 # EEGSym
 
-EEGSym from Pérez-Velasco et al (2022) .
+EEGSym from Pérez-Velasco et al (2022) [eegsym2022].
 
-> **Architecture-only repository.** This repo documents the
+> **Architecture-only repository.** 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.
+> distributed here.** Instantiate the model and train it on your own
+> data.
 
 ## Quick start
 
@@ -38,239 +37,44 @@ model = EEGSym(
 )
 ```
 
-The signal-shape arguments above are example defaults — adjust them
-to match your recording.
+The signal-shape arguments above are illustrative defaults — adjust 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:
+- Full API reference: <https://braindecode.org/stable/generated/braindecode.models.EEGSym.html>
+- Interactive browser (live instantiation, parameter counts):
   <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
+## Architecture
 
-       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"]
+![EEGSym architecture](../../docs/_static/model/eegsym.png)
 
-       # Replace the classification head
-       model.reset_head(n_outputs=10)
 
-   **Saving and restoring full configuration:**
+## Parameters
 
-   .. code::
-       import json
+| Parameter | Type | Description |
+|---|---|---|
+| `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]. |
 
-       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)
+## References
 
-   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.
+1. 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.
+2. Pérez-Velasco, S., EEGSym source code. https://github.com/Serpeve/EEGSym
+3. 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.
 
-   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:
+Cite the original architecture paper (see *References* above) and braindecode:
 
 ```bibtex
 @article{aristimunha2025braindecode,