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_patchesisn_times / patch_size, rounded ason_non_divisiblesays.Macro Components
DeepSOZ.channel_embeddingOperations. An
Embeddingwith one row per channel, added to that channel’s tokens, and a last row that is the global token of every second (detector.pos_encoderin 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.encoderOperations. A post-norm
TransformerEncoderLayerof widthpatch_size, withnum_headsheads and a feed-forward block of widthdim_feedforward, applied to then_chans + 1tokens of each second (detector.tx_encoder).Role. Mixes the channels of each second into a global encoding and channel encodings.
DeepSOZ.lstmOperations. A one-layer bidirectional
LSTMwithlstm_hidden_sizeunits per direction, over the sequence of global encodings (detector.multi_lstm).Role. Follows how the activity evolves from second to second.
DeepSOZ.soz_layerOperations. A
Linearlayer, 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_layerOperations. A
Linearlayer from the LSTM outputs ton_outputslogits 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_layerscore 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_szpoolin 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, andon_non_divisiblefor 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.tarin [Niranjan2025]. It uses the defaults withn_chans=19andn_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), inresults/amruth1234-deepsoz-hem-v0-1-3of esl-epfl/szcore.The released model was trained for detection only: its
soz_layerwas 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 tomne.Infofor 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 dividepatch_size.dim_feedforward (
int) – Width of the encoder’s feed-forward block. Withpatch_size=200the 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 aValueError.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_hubpackage 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_sizesamples.- Parameters:
- Returns:
Logits of shape
(batch, n_outputs, n_patches), and withreturn_soz=Truealso the SOZ logits of shape(batch, n_chans).- Return type:
torch.Tensor or tuple of torch.Tensor