Deep4Net / README.md

Add architecture-only model card

15510f7 verified 3 months ago

6.6 kB

license: bsd-3-clause
library_name: braindecode
pipeline_tag: feature-extraction
tags:
  - eeg
  - biosignal
  - pytorch
  - neuroscience
  - braindecode
  - convolutional

Deep4Net

Deep ConvNet model from Schirrmeister et al (2017) .

Architecture-only repository. This repo documents the braindecode.models.Deep4Net 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

pip install braindecode

from braindecode.models import Deep4Net

model = Deep4Net(
    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.Deep4Net.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/deep4.py#L19

Architecture description

The block below is the rendered class docstring (parameters, references, architecture figure where available).

Deep ConvNet model from Schirrmeister et al (2017) [Schirrmeister2017]_.

Convolution

.. figure:: https://onlinelibrary.wiley.com/cms/asset/fc200ccc-d8c4-45b4-8577-56ce4d15999a/hbm23730-fig-0001-m.jpg :align: center :alt: Deep4Net Architecture :width: 600px

Model described in [Schirrmeister2017]_.

Parameters

final_conv_length: int | str Length of the final convolution layer. If set to "auto", n_times must not be None. Default: "auto". n_filters_time: int Number of temporal filters. n_filters_spat: int Number of spatial filters. filter_time_length: int Length of the temporal filter in layer 1. pool_time_length: int Length of temporal pooling filter. pool_time_stride: int Length of stride between temporal pooling filters. n_filters_2: int Number of temporal filters in layer 2. filter_length_2: int Length of the temporal filter in layer 2. n_filters_3: int Number of temporal filters in layer 3. filter_length_3: int Length of the temporal filter in layer 3. n_filters_4: int Number of temporal filters in layer 4. filter_length_4: int Length of the temporal filter in layer 4. activation_first_conv_nonlin: nn.Module, default is nn.ELU Non-linear activation function to be used after convolution in layer 1. first_pool_mode: str Pooling mode in layer 1. "max" or "mean". first_pool_nonlin: callable Non-linear activation function to be used after pooling in layer 1. activation_later_conv_nonlin: nn.Module, default is nn.ELU Non-linear activation function to be used after convolution in later layers. later_pool_mode: str Pooling mode in later layers. "max" or "mean". later_pool_nonlin: callable Non-linear activation function to be used after pooling in later layers. drop_prob: float Dropout probability. split_first_layer: bool Split first layer into temporal and spatial layers (True) or just use temporal (False). There would be no non-linearity between the split layers. batch_norm: bool Whether to use batch normalisation. batch_norm_alpha: float Momentum for BatchNorm2d. stride_before_pool: bool Stride before pooling.

References

.. [Schirrmeister2017] Schirrmeister, R. T., Springenberg, J. T., Fiederer, L. D. J., Glasstetter, M., Eggensperger, K., Tangermann, M., Hutter, F. & Ball, T. (2017). Deep learning with convolutional neural networks for EEG decoding and visualization. Human Brain Mapping , Aug. 2017. Online: http://dx.doi.org/10.1002/hbm.23730

.. 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 Deep4Net

 # Train your model
 model = Deep4Net(n_chans=22, n_outputs=4, n_times=1000)
 # ... training code ...

 # Push to the Hub
 model.push_to_hub(
     repo_id="username/my-deep4net-model",
     commit_message="Initial model upload",
 )

Loading a model from the Hub:

.. code:: from braindecode.models import Deep4Net

 # Load pretrained model
 model = Deep4Net.from_pretrained("username/my-deep4net-model")

 # Load with a different number of outputs (head is rebuilt automatically)
 model = Deep4Net.from_pretrained("username/my-deep4net-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 = Deep4Net.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.

Citation

Please cite both the original paper for this architecture (see the References section above) and braindecode:

@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.