braindecode.models.DeepSOZ#

class braindecode.models.DeepSOZ(n_outputs=None, n_chans=None, chs_info=None, n_times=None, input_window_seconds=None, sfreq=None, *, patch_size=256, num_heads=8, dim_feedforward=256, lstm_hidden_size=100, drop_prob=0.25, on_non_divisible='pad', activation=<class 'torch.nn.modules.activation.ReLU'>)[source]#

DeepSOZ from Shama et al. (2023) [Shama2023].

Attention/Transformer Recurrent

Added in version 2.1.

DeepSOZ detects seizures second by second in multichannel scalp EEG and localizes their onset zone (SOZ) channel by channel [Shama2023]. DeepSOZ-HEM [Niranjan2025], the same network retrained with hard example mining, came fourth in the 2025 seizure detection challenge, which was scored with the SzCORE framework [Dan2025]. This class is written from the paper; with the DeepSOZ-HEM weights it gives the outputs of the authors’ code.

Architecture Overview

The one-second segments of each channel are the tokens, without a convolutional front end. One Transformer encoder layer mixes the channel tokens of each second with a learned global token, a bidirectional LSTM follows the global tokens over the seconds, and a linear layer gives the seizure logits of every second:

(batch, n_chans, n_times)
-> tokens + channel embedding (batch, n_patches, n_chans, patch_size)
-> + global token (batch, n_patches, n_chans + 1, patch_size)
-> encoder, each second alone (batch, n_patches, n_chans + 1, patch_size)
-> lstm over the global tokens (batch, n_patches, 2 * lstm_hidden_size)
-> final_layer (batch, n_outputs, n_patches)

With return_soz=True, the channel tokens are also scored and pooled over time into one logit per channel:

encoded channel tokens (batch, n_patches, n_chans, patch_size)
-> soz_layer (batch, n_patches, n_chans)
-> mean over time weighted by the seizure logit (batch, n_chans)

n_patches is n_times / patch_size, rounded as on_non_divisible says.

Macro Components

DeepSOZ.channel_embedding

Operations. An Embedding with one row per channel, added to that channel’s tokens, and a last row that is the global token of every second (detector.pos_encoder in the reference). The paper writes it as a linear map of one-hot channel indices.

Role. Tells the encoder which electrode a token comes from.

DeepSOZ.encoder

Operations. A post-norm TransformerEncoderLayer of width patch_size, with num_heads heads and a feed-forward block of width dim_feedforward, applied to the n_chans + 1 tokens of each second (detector.tx_encoder).

Role. Mixes the channels of each second into a global encoding and channel encodings.

DeepSOZ.lstm

Operations. A one-layer bidirectional LSTM with lstm_hidden_size units per direction, over the sequence of global encodings (detector.multi_lstm).

Role. Follows how the activity evolves from second to second.

DeepSOZ.soz_layer

Operations. A Linear layer, shared by the channels, from each channel encoding to a score (hc_linear).

Role. Scores each channel and second for the onset zone; used only with return_soz=True.

DeepSOZ.final_layer

Operations. A Linear layer from the LSTM outputs to n_outputs logits for every second (detector.multi_linear).

Role. The seizure detection head, without the softmax of the reference.

Temporal, Spatial, and Spectral Encoding

  • Temporal: the raw samples of a channel within one second form its token; across seconds, the bidirectional LSTM reads the whole window in both directions, so the logit of a second also depends on the seconds after it.

  • Spatial: the encoder’s self-attention mixes the channels of each second; the channel embedding fixes the channel order of training.

  • Spectral: not modelled; the authors band-pass the EEG between 1.6 and 30 Hz before the model.

Additional Mechanisms

  • Onset zone pooling. The SOZ logit of channel \(c\) is \(\sum_t w_t s_{t,c}\), with \(s_{t,c}\) the soz_layer score of second \(t\) and \(w = \mathrm{softmax}_t(z_t)\) the softmax over time of the seizure logit \(z_t\) (the last output). The reference code computes it this way; Equation 3 of the paper normalizes the seizure probabilities instead.

  • Reference parity. With the DeepSOZ-HEM weights, the logits, the SOZ probabilities and the input gradients equal those of the reference txlstm_szpool in float64 and float32 on CPU, and the parameter gradients differ by at most 2e-15 relative in float64. The differences are in the interface: logits with a channel axis instead of (batch, n_patches, 2) probabilities, SOZ logits instead of probabilities and only on request, sizes as parameters, and on_non_divisible for inputs that are not a whole number of tokens.

Pretrained Weights

The authors released one trained model, DeepSOZ-HEM (GPL-3.0), as deepsoz-hem/src/deepsoz/deepsoz_fold4.pth_4.tar in [Niranjan2025]. It uses the defaults with n_chans=19 and n_outputs=2 (the second output is the seizure class), was trained with a cross-entropy weighted 0.185 and 0.815, and expects this input, which the model does not prepare:

  • 19 channels in the order Fp1, Fp2, F7, F3, Fz, F4, F8, T3, C3, Cz, C4, T4, T5, P3, Pz, P4, T6, O1, O2, average reference, sampled at 256 Hz, as in the SzCORE BIDS datasets such as SIENA;

  • in microvolts (braindecode datasets hold volts), each channel filtered over the whole recording by a zero-phase fourth-order Butterworth low-pass at 30 Hz then high-pass at 1.6 Hz, and clipped to its mean plus or minus two standard deviations;

  • 10 min windows (n_times=153600) every 8 min, the last one padded with zeros.

The authors keep the larger softmax seizure probability where two windows overlap, smooth it with a 25 s moving average and mark the seconds above 0.65 as seizure. On SIENA, which was part of its training data, this gives the eight SzCORE scores the challenge published for the model (event F1 0.820), in results/amruth1234-deepsoz-hem-v0-1-3 of esl-epfl/szcore.

The released model was trained for detection only: its soz_layer was not trained, and on the 47 seizures of Siena its top channel is in the annotated onset zone less often than a random channel. Train that layer before using the SOZ output, as in the paper’s second stage: freeze the LSTM and minimize a binary cross-entropy on the sigmoid of the SOZ logits, plus 0.1 times the detection loss and an L1 penalty on the SOZ probabilities [Shama2023].

Parameters:
  • n_outputs (int) – Number of outputs of the model. This is the number of classes in the case of classification.

  • n_chans (int) – Number of EEG channels.

  • chs_info (list of dict) – Information about each individual EEG channel. This should be filled with info["chs"]. Refer to mne.Info for more details.

  • n_times (int) – Number of time samples of the input window.

  • input_window_seconds (float) – Length of the input window in seconds.

  • sfreq (float) – Sampling frequency of the EEG recordings.

  • patch_size (int) – Samples per token, one second: the sampling rate (200 Hz in the paper, 256 Hz for DeepSOZ-HEM). It is also the width of the Transformer.

  • num_heads (int) – Attention heads of the encoder. Must divide patch_size.

  • dim_feedforward (int) – Width of the encoder’s feed-forward block. With patch_size=200 the defaults give the 510K parameters of the paper’s model.

  • lstm_hidden_size (int) – Units of each direction of the LSTM.

  • drop_prob (float) – Dropout of the encoder (0.25 in DeepSOZ-HEM, 0.15 in the paper).

  • on_non_divisible (str) – How an input that is not a whole number of tokens is handled: right zero-padding, cropping, or a ValueError.

  • activation (type[Module]) – Non-linearity of the encoder’s feed-forward block.

Raises:

ValueError – If some input signal-related parameters are not specified: and can not be inferred.

Notes

If some input signal-related parameters are not specified, there will be an attempt to infer them from the other parameters.

References

[Shama2023] (1,2,3)

Shama, D. M., Jing, J., & Venkataraman, A. (2023). DeepSOZ: A robust deep model for joint temporal and spatial seizure onset localization from multichannel EEG data. In Medical Image Computing and Computer Assisted Intervention (MICCAI 2023), LNCS 14222, 184-194. https://doi.org/10.1007/978-3-031-43993-3_18

[Niranjan2025] (1,2)

Niranjan, A., Shama, D. M., & Venkataraman, A. (2025). DeepSOZ-HEM. Submission to the 2025 seizure detection challenge. amruth-sn/deepsoz-hem

[Dan2025]

Dan, J., Pale, U., Amirshahi, A., Cappelletti, W., Ingolfsson, T. M., Wang, X., Cossettini, A., Bernini, A., Benini, L., Beniczky, S., Atienza, D., & Ryvlin, P. (2025). SzCORE: Seizure Community Open-Source Research Evaluation framework for the validation of electroencephalography-based automated seizure detection algorithms. Epilepsia, 66(S3), 14-24. https://doi.org/10.1111/epi.18113

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:

from braindecode.models import DeepSOZ

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

# Push to the Hub; ``datasets`` and ``base_model`` go to the card
model.push_to_hub(
    repo_id="username/my-deepsoz-model",
    commit_message="Initial model upload",
    model_card_kwargs={"datasets": ["BNCI2014_001"]},
)

Loading a model from the Hub:

from braindecode.models import DeepSOZ

# Load pretrained model
model = DeepSOZ.from_pretrained("username/my-deepsoz-model")
# Data the weights were trained on, from the Hub model card
print(model.card_data.datasets if model.card_data else None)

# Load with a different number of outputs (head is rebuilt automatically)
model = DeepSOZ.from_pretrained("username/my-deepsoz-model", n_outputs=4)

Extracting features and replacing the head:

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:

import json

config = model.get_config()            # all __init__ params
with open("config.json", "w") as f:
    json.dump(config, f)

model2 = DeepSOZ.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 Loading and Adapting Pretrained Foundation Models for a complete tutorial.

Methods

forward(x, return_soz=False)[source]#

Predict seizure logits for every segment of patch_size samples.

Parameters:
  • x (Tensor) – Input of shape (batch, n_chans, n_times).

  • return_soz (bool) – Also return the seizure onset zone logits, pooled over time with a softmax of the last output (the seizure logit of the released model). A scripted model ignores this flag.

Returns:

Logits of shape (batch, n_outputs, n_patches), and with return_soz=True also the SOZ logits of shape (batch, n_chans).

Return type:

torch.Tensor or tuple of torch.Tensor

reset_head(n_outputs)[source]#

Replace the detection head for a new number of outputs.

Parameters:

n_outputs (int) – New number of output classes.

Return type:

None

Examples

>>> from braindecode.models import BENDR
>>> model = BENDR(n_chans=22, n_times=1000, n_outputs=4)
>>> model.reset_head(10)
>>> model.n_outputs
10

Added in version 1.4.