braindecode.augmentation package#

Utilities for data augmentation.

class braindecode.augmentation.AugmentedDataLoader(dataset, transforms=None, device=None, **kwargs)[source]#

Bases: DataLoader

A base dataloader class customized to applying augmentation Transforms.

Parameters:

  • dataset (BaseDataset) – The dataset containing the signals.

  • transforms (list | Transform, optional) – Transform or sequence of Transform to be applied to each batch.

  • device (str | torch.device | None, optional) – Device on which to transform the data. Defaults to None.

  • **kwargs (dict, optional) – keyword arguments to pass to standard DataLoader class.

class braindecode.augmentation.BandstopFilter(probability, sfreq, bandwidth=1, max_freq=None, random_state=None)[source]#

Bases: Transform

Apply a band-stop filter with desired bandwidth at a randomly selected frequency position between 0 and max_freq.

Suggested e.g. in [1] and [2]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • bandwidth (float) – Bandwidth of the filter, i.e. distance between the low and high cut frequencies.

  • sfreq (float, optional) – Sampling frequency of the signals to be filtered. Defaults to 100 Hz.

  • max_freq (float | None, optional) – Maximal admissible frequency. The low cut frequency will be sampled so that the corresponding high cut frequency + transition (=1Hz) are below max_freq. If omitted or None, will default to the Nyquist frequency (sfreq / 2).

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[2]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains

  • sfreqfloat

    Sampling frequency of the signals to be filtered.

  • bandwidthfloat

    Bandwidth of the filter, i.e. distance between the low and high cut frequencies.

  • freqs_to_notcharray-like | None

    Array of floats of size (batch_size,) containing the center of the frequency band to filter out for each sample in the batch. Frequencies should be greater than bandwidth/2 + transition and lower than sfreq/2 - bandwidth/2 - transition (where transition = 1 Hz).

Return type:

dict

static operation(X, y, sfreq, bandwidth, freqs_to_notch)[source]#

Apply a band-stop filter with desired bandwidth at the desired frequency position.

Suggested e.g. in [1] and [2]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • sfreq (float) – Sampling frequency of the signals to be filtered.

  • bandwidth (float) – Bandwidth of the filter, i.e. distance between the low and high cut frequencies.

  • freqs_to_notch (array-like | None) – Array of floats of size (batch_size,) containing the center of the frequency band to filter out for each sample in the batch. Frequencies should be greater than bandwidth/2 + transition and lower than sfreq/2 - bandwidth/2 - transition (where transition = 1 Hz).

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[2]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

class braindecode.augmentation.ChannelsDropout(probability, p_drop=0.2, random_state=None)[source]#

Bases: Transform

Randomly set channels to flat signal.

Part of the CMSAugment policy proposed in [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • proba_drop (float | None, optional) – Float between 0 and 1 setting the probability of dropping each channel. Defaults to 0.2.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether or not to transform given the probability argument and to sample channels to erase. Defaults to None.

References

[1]

Saeed, A., Grangier, D., Pietquin, O., & Zeghidour, N. (2020). Learning from Heterogeneous EEG Signals with Differentiable Channel Reordering. arXiv preprint arXiv:2010.13694.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains

  • p_dropfloat

    Float between 0 and 1 setting the probability of dropping each channel.

  • random_statenumpy.random.Generator

    The generator to use.

Return type:

dict

static operation(X, y, p_drop, random_state=None)[source]#

Randomly set channels to flat signal.

Part of the CMSAugment policy proposed in [1]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • p_drop (float) – Float between 0 and 1 setting the probability of dropping each channel.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Saeed, A., Grangier, D., Pietquin, O., & Zeghidour, N. (2020). Learning from Heterogeneous EEG Signals with Differentiable Channel Reordering. arXiv preprint arXiv:2010.13694.

class braindecode.augmentation.ChannelsShuffle(probability, p_shuffle=0.2, random_state=None)[source]#

Bases: Transform

Randomly shuffle channels in EEG data matrix.

Part of the CMSAugment policy proposed in [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • p_shuffle (float | None, optional) – Float between 0 and 1 setting the probability of including the channel in the set of permuted channels. Defaults to 0.2.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether or not to transform given the probability argument, to sample which channels to shuffle and to carry the shuffle. Defaults to None.

References

[1]

Saeed, A., Grangier, D., Pietquin, O., & Zeghidour, N. (2020). Learning from Heterogeneous EEG Signals with Differentiable Channel Reordering. arXiv preprint arXiv:2010.13694.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains

  • p_shufflefloat

    Float between 0 and 1 setting the probability of including the channel in the set of permuted channels.

  • random_statenumpy.random.Generator

    The generator to use.

Return type:

dict

static operation(X, y, p_shuffle, random_state=None)[source]#

Randomly shuffle channels in EEG data matrix.

Part of the CMSAugment policy proposed in [1]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • p_shuffle (float | None) – Float between 0 and 1 setting the probability of including the channel in the set of permutted channels.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to sample which channels to shuffle and to carry the shuffle. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Saeed, A., Grangier, D., Pietquin, O., & Zeghidour, N. (2020). Learning from Heterogeneous EEG Signals with Differentiable Channel Reordering. arXiv preprint arXiv:2010.13694.

class braindecode.augmentation.ChannelsSymmetry(probability, ordered_ch_names, random_state=None)[source]#

Bases: Transform

Permute EEG channels inverting left and right-side sensors.

Suggested e.g. in [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • ordered_ch_names (list) – Ordered list of strings containing the names (in 10-20 nomenclature) of the EEG channels that will be transformed. The first name should correspond the data in the first row of X, the second name in the second row and so on.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether or not to transform given the probability argument. Defaults to None.

References

[1]

Deiss, O., Biswal, S., Jin, J., Sun, H., Westover, M. B., & Sun, J. (2018). HAMLET: interpretable human and machine co-learning technique. arXiv preprint arXiv:1803.09702.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains

  • permutationfloat

    List of integers defining the new channels order.

Return type:

dict

static operation(X, y, permutation)[source]#

Permute EEG channels according to fixed permutation matrix.

Suggested e.g. in [1]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • permutation (list) – List of integers defining the new channels order.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Deiss, O., Biswal, S., Jin, J., Sun, H., Westover, M. B., & Sun, J. (2018). HAMLET: interpretable human and machine co-learning technique. arXiv preprint arXiv:1803.09702.

class braindecode.augmentation.Compose(transforms)[source]#

Bases: Transform

Transform composition.

Callable class allowing to cast a sequence of Transform objects into a single one.

Parameters:

transforms (list) – Sequence of Transforms to be composed.

forward(X, y)[source]#

General forward pass for an augmentation transform.

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor | None) – EEG labels for the example or batch. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor, optional – Transformed labels. Only returned when y is not None.

class braindecode.augmentation.FTSurrogate(probability, phase_noise_magnitude=1, channel_indep=False, random_state=None)[source]#

Bases: Transform

FT surrogate augmentation of a single EEG channel, as proposed in [1].

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • phase_noise_magnitude (float | torch.Tensor, optional) – Float between 0 and 1 setting the range over which the phase perturbation is uniformly sampled: [0, phase_noise_magnitude * 2 * pi]. Defaults to 1.

  • channel_indep (bool, optional) – Whether to sample phase perturbations independently for each channel or not. It is advised to set it to False when spatial information is important for the task, like in BCI. Default False.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether or not to transform given the probability argument. Defaults to None.

References

[1]

Schwabedal, J. T., Snyder, J. C., Cakmak, A., Nemati, S., & Clifford, G. D. (2018). Addressing Class Imbalance in Classification Problems of Noisy Signals by using Fourier Transform Surrogates. arXiv preprint arXiv:1806.08675.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains:

  • phase_noise_magnitudefloat

    The magnitude of the transformation.

  • random_statenumpy.random.Generator

    The generator to use.

Return type:

dict

static operation(X, y, phase_noise_magnitude, channel_indep, random_state=None)[source]#

FT surrogate augmentation of a single EEG channel, as proposed in [1].

Function copied from cliffordlab/sleep-convolutions-tf and modified.

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • phase_noise_magnitude (float) – Float between 0 and 1 setting the range over which the phase perturbation is uniformly sampled: [0, phase_noise_magnitude * 2 * pi].

  • channel_indep (bool) – Whether to sample phase perturbations independently for each channel or not. It is advised to set it to False when spatial information is important for the task, like in BCI.

  • random_state (int | numpy.random.Generator, optional) – Used to draw the phase perturbation. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Schwabedal, J. T., Snyder, J. C., Cakmak, A., Nemati, S., & Clifford, G. D. (2018). Addressing Class Imbalance in Classification Problems of Noisy Signals by using Fourier Transform Surrogates. arXiv preprint arXiv:1806.08675.

class braindecode.augmentation.FrequencyShift(probability, sfreq, max_delta_freq=2, random_state=None)[source]#

Bases: Transform

Add a random shift in the frequency domain to all channels.

Note that here, the shift is the same for all channels of a single example.

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • sfreq (float) – Sampling frequency of the signals to be transformed.

  • max_delta_freq (float | torch.Tensor, optional) – Maximum shift in Hz that can be sampled (in absolute value). Defaults to 2 (shift sampled between -2 and 2 Hz).

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains

  • delta_freqfloat

    The amplitude of the frequency shift (in Hz).

  • sfreqfloat

    Sampling frequency of the signals to be transformed.

Return type:

dict

static operation(X, y, delta_freq, sfreq)[source]#

Adds a shift in the frequency domain to all channels.

Note that here, the shift is the same for all channels of a single example.

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • delta_freq (float) – The amplitude of the frequency shift (in Hz).

  • sfreq (float) – Sampling frequency of the signals to be transformed.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

class braindecode.augmentation.GaussianNoise(probability, std=0.1, random_state=None)[source]#

Bases: Transform

Randomly add white noise to all channels.

Suggested e.g. in [1], [2] and [3]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • std (float, optional) – Standard deviation to use for the additive noise. Defaults to 0.1.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Wang, F., Zhong, S. H., Peng, J., Jiang, J., & Liu, Y. (2018). Data augmentation for eeg-based emotion recognition with deep convolutional neural networks. In International Conference on Multimedia Modeling (pp. 82-93).

[2]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[3]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains

  • stdfloat

    Standard deviation to use for the additive noise.

  • random_statenumpy.random.Generator

    The generator to use.

Return type:

dict

static operation(X, y, std, random_state=None)[source]#

Randomly add white Gaussian noise to all channels.

Suggested e.g. in [1], [2] and [3]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • std (float) – Standard deviation to use for the additive noise.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Wang, F., Zhong, S. H., Peng, J., Jiang, J., & Liu, Y. (2018). Data augmentation for eeg-based emotion recognition with deep convolutional neural networks. In International Conference on Multimedia Modeling (pp. 82-93).

[2]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[3]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

class braindecode.augmentation.IdentityTransform(probability=1.0, random_state=None)[source]#

Bases: Transform

Identity transform.

Transform that does not change the input.

static operation(X, y)[source]#

Identity operation.

Parameters:
Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

class braindecode.augmentation.MaskEncoding(probability, max_mask_ratio=0.1, n_segments=1, random_state=None)[source]#

Bases: Transform

MaskEncoding from [1].

Replaces randomly chosen contiguous part (or parts) of all channels by zeros (if more than one segment, it may overlap).

Implementation based on [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • max_mask_ratio (float, optional) – Signal ratio to zero out. Defaults to 0.1.

  • n_segments (int, optional) – Number of segments to zero out in each example. Defaults to 1.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1] (1,2)

Ding, Wenlong, et al. “A Novel Data Augmentation Approach Using Mask Encoding for Deep Learning-Based Asynchronous SSVEP-BCI.” IEEE Transactions on Neural Systems and Rehabilitation Engineering 32 (2024): 875-886.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains …

Return type:

dict

static operation(X, y, time_start, segment_length, n_segments)[source]#

Mark encoding from Ding et al. (2024) from [ding2024].

Replaces a contiguous part (or parts) of all channels by zeros (if more than one segment, it may overlap).

Implementation based on [ding2024]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • time_start (torch.Tensor) – Tensor of integers containing the position (in last dimension) where to start masking the signal. Should have “n_segments” times the size of the first dimension of X (i.e. “n_segments” start positions per example in the batch).

  • segment_length (int) – Length of each segment to zero out.

  • n_segments (int) – Number of segments to zero out in each example.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[ding2024] (1,2)

Ding, Wenlong, et al. A Novel Data Augmentation Approach Using Mask Encoding for Deep Learning-Based Asynchronous SSVEP-BCI. IEEE Transactions on Neural Systems and Rehabilitation Engineering 32 (2024): 875-886.

class braindecode.augmentation.Mixup(alpha, beta_per_sample=False, random_state=None)[source]#

Bases: Transform

Implements Iterator for Mixup for EEG data. See [1]. Implementation based on [2].

Parameters:

  • alpha (float) – Mixup hyperparameter.

  • beta_per_sample (bool (default=False)) – By default, one mixing coefficient per batch is drawn from a beta distribution. If True, one mixing coefficient per sample is drawn.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Hongyi Zhang, Moustapha Cisse, Yann N. Dauphin, David Lopez-Paz (2018). mixup: Beyond Empirical Risk Minimization. In 2018 International Conference on Learning Representations (ICLR) Online: https://arxiv.org/abs/1710.09412

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains the values sampled uniformly between 0 and 1 setting the linear interpolation between examples (lam) and the shuffled indices of examples that are mixed into original examples (idx_perm).

Return type:

dict

static operation(X, y, lam, idx_perm)[source]#

Mixes two channels of EEG data.

See [1] for details. Implementation based on [2].

Parameters:

  • X (torch.Tensor) – EEG data in form batch_size, n_channels, n_times

  • y (torch.Tensor) – Target of length batch_size

  • lam (torch.Tensor) – Values between 0 and 1 setting the linear interpolation between examples.

  • idx_perm (torch.Tensor) – Permuted indices of example that are mixed into original examples.

Returns:

X, y. Where X is augmented and y is a tuple of length 3 containing the labels of the two mixed channels and the mixing coefficient.

Return type:

tuple

References

[1]

Hongyi Zhang, Moustapha Cisse, Yann N. Dauphin, David Lopez-Paz (2018). mixup: Beyond Empirical Risk Minimization. In 2018 International Conference on Learning Representations (ICLR) Online: https://arxiv.org/abs/1710.09412

class braindecode.augmentation.SegmentationReconstruction(probability, n_segments=None, random_state=None)[source]#

Bases: Transform

Segmentation Reconstruction from Lotte (2015) [Lotte2015].

Applies a segmentation-reconstruction transform to the input data, as proposed in [Lotte2015]. It segments each trial in the batch and randomly mix it to generate new synthetic trials by label, preserving the original order of the segments in time domain.

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether to transform given the probability argument and to sample the segments mixing. Defaults to None.

  • n_segments (int, optional) – Number of segments to use in the batch. If None, X will be automatically segmented, getting the last element in a list of factors of the number of samples’s square root. Defaults to None.

References

[Lotte2015] (1,2)

Lotte, F. (2015). Signal processing approaches to minimize or suppress calibration time in oscillatory activity-based brain–computer interfaces. Proceedings of the IEEE, 103(6), 871-890.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains the number of segments to split the signal into.

Return type:

dict

static operation(X, y, n_segments, data_classes, rand_indices, idx_shuffle)[source]#

Segment and reconstruct EEG data from [1].

See [1] for details.

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • n_segments (int) – Number of segments to use in the batch.

  • rand_indices (array-like) – Array of indices that indicates which trial to use in each segment.

  • idx_shuffle (array-like) – Array of indices to shuffle the new generated trials.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1] (1,2)

Lotte, F. (2015). Signal processing approaches to minimize or suppress calibration time in oscillatory activity-based brain–computer interfaces. Proceedings of the IEEE, 103(6), 871-890.

class braindecode.augmentation.SensorsRotation(probability, sensors_positions_matrix, axis='z', max_degrees=15, spherical_splines=True, random_state=None)[source]#

Bases: Transform

Interpolates EEG signals over sensors rotated around the desired axis with an angle sampled uniformly between -max_degree and max_degree.

Suggested in [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • sensors_positions_matrix (numpy.ndarray) –

    Matrix giving the positions of each sensor in a 3D cartesian coordinate system. Should have shape (3, n_channels), where n_channels is the number of channels. Standard 10-20 positions can be obtained from mne through:

    >>> ten_twenty_montage = mne.channels.make_standard_montage(
...    'standard_1020'
... ).get_positions()['ch_pos']

  • axis ('x' | 'y' | 'z', optional) – Axis around which to rotate. Defaults to ‘z’.

  • max_degree (float, optional) – Maximum rotation. Rotation angles will be sampled between -max_degree and max_degree. Defaults to 15 degrees.

  • spherical_splines (bool, optional) – Whether to use spherical splines for the interpolation or not. When False, standard scipy.interpolate.Rbf (with quadratic kernel) will be used (as in the original paper). Defaults to True.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Krell, M. M., & Kim, S. K. (2017). Rotational data augmentation for electroencephalographic data. In 2017 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 471-474).

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains four elements:

  • sensors_positions_matrixnumpy.ndarray

    Matrix giving the positions of each sensor in a 3D cartesian coordinate system. Should have shape (3, n_channels), where n_channels is the number of channels.

  • axis’x’ | ‘y’ | ‘z’

    Axis around which to rotate.

  • anglesarray-like

    Array of float of shape (batch_size,) containing the rotation angles (in degrees) for each element of the input batch, sampled uniformly between -max_degrees``and ``max_degrees.

  • spherical_splinesbool

    Whether to use spherical splines for the interpolation or not. When False, standard scipy.interpolate.Rbf (with quadratic kernel) will be used (as in the original paper).

Return type:

dict

static operation(X, y, sensors_positions_matrix, axis, angles, spherical_splines)[source]#

Interpolates EEG signals over sensors rotated around the desired axis with the desired angle.

Suggested in [1]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • sensors_positions_matrix (numpy.ndarray) –

    Matrix giving the positions of each sensor in a 3D cartesian coordinate system. Should have shape (3, n_channels), where n_channels is the number of channels. Standard 10-20 positions can be obtained from mne through:

    >>> ten_twenty_montage = mne.channels.make_standard_montage(
...    'standard_1020'
... ).get_positions()['ch_pos']

  • axis ('x' | 'y' | 'z') – Axis around which to rotate.

  • angles (array-like) – Array of float of shape (batch_size,) containing the rotation angles (in degrees) for each element of the input batch.

  • spherical_splines (bool) – Whether to use spherical splines for the interpolation or not. When False, standard scipy.interpolate.Rbf (with quadratic kernel) will be used (as in the original paper).

References

[1]

Krell, M. M., & Kim, S. K. (2017). Rotational data augmentation for electroencephalographic data. In 2017 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 471-474).

class braindecode.augmentation.SensorsXRotation(probability, ordered_ch_names, max_degrees=15, spherical_splines=True, random_state=None)[source]#

Bases: SensorsRotation

Interpolates EEG signals over sensors rotated around the X axis with an angle sampled uniformly between -max_degree and max_degree.

Suggested in [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • ordered_ch_names (list) – List of strings representing the channels of the montage considered. Has to be in standard 10-20 style. The order has to be consistent with the order of channels in the input matrices that will be fed to the transform. This channel will be used to compute approximate sensors positions from a standard 10-20 montage.

  • max_degree (float, optional) – Maximum rotation. Rotation angles will be sampled between -max_degree and max_degree. Defaults to 15 degrees.

  • spherical_splines (bool, optional) – Whether to use spherical splines for the interpolation or not. When False, standard scipy.interpolate.Rbf (with quadratic kernel) will be used (as in the original paper). Defaults to True.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Krell, M. M., & Kim, S. K. (2017). Rotational data augmentation for electroencephalographic data. In 2017 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 471-474).

class braindecode.augmentation.SensorsYRotation(probability, ordered_ch_names, max_degrees=15, spherical_splines=True, random_state=None)[source]#

Bases: SensorsRotation

Interpolates EEG signals over sensors rotated around the Y axis with an angle sampled uniformly between -max_degree and max_degree.

Suggested in [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • ordered_ch_names (list) – List of strings representing the channels of the montage considered. Has to be in standard 10-20 style. The order has to be consistent with the order of channels in the input matrices that will be fed to the transform. This channel will be used to compute approximate sensors positions from a standard 10-20 montage.

  • max_degree (float, optional) – Maximum rotation. Rotation angles will be sampled between -max_degree and max_degree. Defaults to 15 degrees.

  • spherical_splines (bool, optional) – Whether to use spherical splines for the interpolation or not. When False, standard scipy.interpolate.Rbf (with quadratic kernel) will be used (as in the original paper). Defaults to True.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Krell, M. M., & Kim, S. K. (2017). Rotational data augmentation for electroencephalographic data. In 2017 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 471-474).

class braindecode.augmentation.SensorsZRotation(probability, ordered_ch_names, max_degrees=15, spherical_splines=True, random_state=None)[source]#

Bases: SensorsRotation

Interpolates EEG signals over sensors rotated around the Z axis with an angle sampled uniformly between -max_degree and max_degree.

Suggested in [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • ordered_ch_names (list) – List of strings representing the channels of the montage considered. Has to be in standard 10-20 style. The order has to be consistent with the order of channels in the input matrices that will be fed to the transform. This channel will be used to compute approximate sensors positions from a standard 10-20 montage.

  • max_degree (float, optional) – Maximum rotation. Rotation angles will be sampled between -max_degree and max_degree. Defaults to 15 degrees.

  • spherical_splines (bool, optional) – Whether to use spherical splines for the interpolation or not. When False, standard scipy.interpolate.Rbf (with quadratic kernel) will be used (as in the original paper). Defaults to True.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Krell, M. M., & Kim, S. K. (2017). Rotational data augmentation for electroencephalographic data. In 2017 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 471-474).

class braindecode.augmentation.SignFlip(probability, random_state=None)[source]#

Bases: Transform

Flip the sign axis of each input with a given probability.

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether or not to transform given the probability argument. Defaults to None.

static operation(X, y)[source]#

Flip the sign axis of each input.

Parameters:
Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

class braindecode.augmentation.SmoothTimeMask(probability, mask_len_samples=100, random_state=None)[source]#

Bases: Transform

Smoothly replace a randomly chosen contiguous part of all channels by zeros.

Suggested e.g. in [1] and [2]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • mask_len_samples (int | torch.Tensor, optional) – Number of consecutive samples to zero out. Will be ignored if magnitude is not set to None. Defaults to 100.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[2]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains two elements:

  • mask_start_per_sampletorch.tensor

    Tensor of integers containing the position (in last dimension) where to start masking the signal. Should have the same size as the first dimension of X (i.e. one start position per example in the batch).

  • mask_len_samplesint

    Number of consecutive samples to zero out.

Return type:

dict

static operation(X, y, mask_start_per_sample, mask_len_samples)[source]#

Smoothly replace a contiguous part of all channels by zeros.

Originally proposed in [1] and [2]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • mask_start_per_sample (torch.tensor) – Tensor of integers containing the position (in last dimension) where to start masking the signal. Should have the same size as the first dimension of X (i.e. one start position per example in the batch).

  • mask_len_samples (int) – Number of consecutive samples to zero out.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[2]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

class braindecode.augmentation.TimeReverse(probability, random_state=None)[source]#

Bases: Transform

Flip the time axis of each input with a given probability.

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether or not to transform given the probability argument. Defaults to None.

static operation(X, y)[source]#

Flip the time axis of each input.

Parameters:
Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

class braindecode.augmentation.Transform(probability=1.0, random_state=None)[source]#

Bases: Module

Basic transform class used for implementing data augmentation operations.

Parameters:

  • operation (callable) – A function taking arrays X, y (inputs and targets resp.) and other required arguments, and returning the transformed X and y.

  • probability (float, optional) – Float between 0 and 1 defining the uniform probability of applying the operation. Set to 1.0 by default (e.g always apply the operation).

  • random_state (int, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether or not to transform given the probability argument. Defaults to None.

forward(X: Tensor, y: Tensor | None = None) → Tensor | tuple[Tensor, Tensor | tuple[Tensor, ...]][source]#

General forward pass for an augmentation transform.

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor | None) – EEG labels for the example or batch. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor, optional – Transformed labels. Only returned when y is not None.

get_augmentation_params(*batch)[source]#
operation: Callable[[Tensor, Tensor], tuple[Tensor, Tensor | tuple[Tensor, ...]]]#
property probability#

Submodules#

braindecode.augmentation.base module#

class braindecode.augmentation.base.AugmentedDataLoader(dataset, transforms=None, device=None, **kwargs)[source]#

Bases: DataLoader

A base dataloader class customized to applying augmentation Transforms.

Parameters:

  • dataset (BaseDataset) – The dataset containing the signals.

  • transforms (list | Transform, optional) – Transform or sequence of Transform to be applied to each batch.

  • device (str | torch.device | None, optional) – Device on which to transform the data. Defaults to None.

  • **kwargs (dict, optional) – keyword arguments to pass to standard DataLoader class.

class braindecode.augmentation.base.Compose(transforms)[source]#

Bases: Transform

Transform composition.

Callable class allowing to cast a sequence of Transform objects into a single one.

Parameters:

transforms (list) – Sequence of Transforms to be composed.

forward(X, y)[source]#

General forward pass for an augmentation transform.

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor | None) – EEG labels for the example or batch. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor, optional – Transformed labels. Only returned when y is not None.

class braindecode.augmentation.base.IdentityTransform(probability=1.0, random_state=None)[source]#

Bases: Transform

Identity transform.

Transform that does not change the input.

static operation(X, y)[source]#

Identity operation.

Parameters:
Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

class braindecode.augmentation.base.Transform(probability=1.0, random_state=None)[source]#

Bases: Module

Basic transform class used for implementing data augmentation operations.

Parameters:

  • operation (callable) – A function taking arrays X, y (inputs and targets resp.) and other required arguments, and returning the transformed X and y.

  • probability (float, optional) – Float between 0 and 1 defining the uniform probability of applying the operation. Set to 1.0 by default (e.g always apply the operation).

  • random_state (int, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether or not to transform given the probability argument. Defaults to None.

forward(X: Tensor, y: Tensor | None = None) → Tensor | tuple[Tensor, Tensor | tuple[Tensor, ...]][source]#

General forward pass for an augmentation transform.

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor | None) – EEG labels for the example or batch. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor, optional – Transformed labels. Only returned when y is not None.

get_augmentation_params(*batch)[source]#
operation: Callable[[Tensor, Tensor], tuple[Tensor, Tensor | tuple[Tensor, ...]]]#
property probability#
training: bool#

braindecode.augmentation.functional module#

braindecode.augmentation.functional.bandstop_filter(X, y, sfreq, bandwidth, freqs_to_notch)[source]#

Apply a band-stop filter with desired bandwidth at the desired frequency position.

Suggested e.g. in [1] and [2]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • sfreq (float) – Sampling frequency of the signals to be filtered.

  • bandwidth (float) – Bandwidth of the filter, i.e. distance between the low and high cut frequencies.

  • freqs_to_notch (array-like | None) – Array of floats of size (batch_size,) containing the center of the frequency band to filter out for each sample in the batch. Frequencies should be greater than bandwidth/2 + transition and lower than sfreq/2 - bandwidth/2 - transition (where transition = 1 Hz).

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[2]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

braindecode.augmentation.functional.channels_dropout(X, y, p_drop, random_state=None)[source]#

Randomly set channels to flat signal.

Part of the CMSAugment policy proposed in [1]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • p_drop (float) – Float between 0 and 1 setting the probability of dropping each channel.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Saeed, A., Grangier, D., Pietquin, O., & Zeghidour, N. (2020). Learning from Heterogeneous EEG Signals with Differentiable Channel Reordering. arXiv preprint arXiv:2010.13694.

braindecode.augmentation.functional.channels_permute(X, y, permutation)[source]#

Permute EEG channels according to fixed permutation matrix.

Suggested e.g. in [1]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • permutation (list) – List of integers defining the new channels order.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Deiss, O., Biswal, S., Jin, J., Sun, H., Westover, M. B., & Sun, J. (2018). HAMLET: interpretable human and machine co-learning technique. arXiv preprint arXiv:1803.09702.

braindecode.augmentation.functional.channels_shuffle(X, y, p_shuffle, random_state=None)[source]#

Randomly shuffle channels in EEG data matrix.

Part of the CMSAugment policy proposed in [1]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • p_shuffle (float | None) – Float between 0 and 1 setting the probability of including the channel in the set of permutted channels.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to sample which channels to shuffle and to carry the shuffle. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Saeed, A., Grangier, D., Pietquin, O., & Zeghidour, N. (2020). Learning from Heterogeneous EEG Signals with Differentiable Channel Reordering. arXiv preprint arXiv:2010.13694.

braindecode.augmentation.functional.frequency_shift(X, y, delta_freq, sfreq)[source]#

Adds a shift in the frequency domain to all channels.

Note that here, the shift is the same for all channels of a single example.

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • delta_freq (float) – The amplitude of the frequency shift (in Hz).

  • sfreq (float) – Sampling frequency of the signals to be transformed.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

braindecode.augmentation.functional.ft_surrogate(X, y, phase_noise_magnitude, channel_indep, random_state=None)[source]#

FT surrogate augmentation of a single EEG channel, as proposed in [1].

Function copied from cliffordlab/sleep-convolutions-tf and modified.

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • phase_noise_magnitude (float) – Float between 0 and 1 setting the range over which the phase perturbation is uniformly sampled: [0, phase_noise_magnitude * 2 * pi].

  • channel_indep (bool) – Whether to sample phase perturbations independently for each channel or not. It is advised to set it to False when spatial information is important for the task, like in BCI.

  • random_state (int | numpy.random.Generator, optional) – Used to draw the phase perturbation. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Schwabedal, J. T., Snyder, J. C., Cakmak, A., Nemati, S., & Clifford, G. D. (2018). Addressing Class Imbalance in Classification Problems of Noisy Signals by using Fourier Transform Surrogates. arXiv preprint arXiv:1806.08675.

braindecode.augmentation.functional.gaussian_noise(X, y, std, random_state=None)[source]#

Randomly add white Gaussian noise to all channels.

Suggested e.g. in [1], [2] and [3]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • std (float) – Standard deviation to use for the additive noise.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Wang, F., Zhong, S. H., Peng, J., Jiang, J., & Liu, Y. (2018). Data augmentation for eeg-based emotion recognition with deep convolutional neural networks. In International Conference on Multimedia Modeling (pp. 82-93).

[2]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[3]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

braindecode.augmentation.functional.identity(X, y)[source]#

Identity operation.

Parameters:
Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

braindecode.augmentation.functional.mask_encoding(X, y, time_start, segment_length, n_segments)[source]#

Mark encoding from Ding et al. (2024) from [ding2024].

Replaces a contiguous part (or parts) of all channels by zeros (if more than one segment, it may overlap).

Implementation based on [ding2024]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • time_start (torch.Tensor) – Tensor of integers containing the position (in last dimension) where to start masking the signal. Should have “n_segments” times the size of the first dimension of X (i.e. “n_segments” start positions per example in the batch).

  • segment_length (int) – Length of each segment to zero out.

  • n_segments (int) – Number of segments to zero out in each example.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[ding2024] (1,2)

Ding, Wenlong, et al. A Novel Data Augmentation Approach Using Mask Encoding for Deep Learning-Based Asynchronous SSVEP-BCI. IEEE Transactions on Neural Systems and Rehabilitation Engineering 32 (2024): 875-886.

braindecode.augmentation.functional.mixup(X, y, lam, idx_perm)[source]#

Mixes two channels of EEG data.

See [1] for details. Implementation based on [2].

Parameters:

  • X (torch.Tensor) – EEG data in form batch_size, n_channels, n_times

  • y (torch.Tensor) – Target of length batch_size

  • lam (torch.Tensor) – Values between 0 and 1 setting the linear interpolation between examples.

  • idx_perm (torch.Tensor) – Permuted indices of example that are mixed into original examples.

Returns:

X, y. Where X is augmented and y is a tuple of length 3 containing the labels of the two mixed channels and the mixing coefficient.

Return type:

tuple

References

[1]

Hongyi Zhang, Moustapha Cisse, Yann N. Dauphin, David Lopez-Paz (2018). mixup: Beyond Empirical Risk Minimization. In 2018 International Conference on Learning Representations (ICLR) Online: https://arxiv.org/abs/1710.09412

braindecode.augmentation.functional.segmentation_reconstruction(X, y, n_segments, data_classes, rand_indices, idx_shuffle)[source]#

Segment and reconstruct EEG data from [1].

See [1] for details.

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • n_segments (int) – Number of segments to use in the batch.

  • rand_indices (array-like) – Array of indices that indicates which trial to use in each segment.

  • idx_shuffle (array-like) – Array of indices to shuffle the new generated trials.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1] (1,2)

Lotte, F. (2015). Signal processing approaches to minimize or suppress calibration time in oscillatory activity-based brain–computer interfaces. Proceedings of the IEEE, 103(6), 871-890.

braindecode.augmentation.functional.sensors_rotation(X, y, sensors_positions_matrix, axis, angles, spherical_splines)[source]#

Interpolates EEG signals over sensors rotated around the desired axis with the desired angle.

Suggested in [1]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • sensors_positions_matrix (numpy.ndarray) –

    Matrix giving the positions of each sensor in a 3D cartesian coordinate system. Should have shape (3, n_channels), where n_channels is the number of channels. Standard 10-20 positions can be obtained from mne through:

    >>> ten_twenty_montage = mne.channels.make_standard_montage(
...    'standard_1020'
... ).get_positions()['ch_pos']

  • axis ('x' | 'y' | 'z') – Axis around which to rotate.

  • angles (array-like) – Array of float of shape (batch_size,) containing the rotation angles (in degrees) for each element of the input batch.

  • spherical_splines (bool) – Whether to use spherical splines for the interpolation or not. When False, standard scipy.interpolate.Rbf (with quadratic kernel) will be used (as in the original paper).

References

[1]

Krell, M. M., & Kim, S. K. (2017). Rotational data augmentation for electroencephalographic data. In 2017 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 471-474).

braindecode.augmentation.functional.sign_flip(X, y)[source]#

Flip the sign axis of each input.

Parameters:
Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

braindecode.augmentation.functional.smooth_time_mask(X, y, mask_start_per_sample, mask_len_samples)[source]#

Smoothly replace a contiguous part of all channels by zeros.

Originally proposed in [1] and [2]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • mask_start_per_sample (torch.tensor) – Tensor of integers containing the position (in last dimension) where to start masking the signal. Should have the same size as the first dimension of X (i.e. one start position per example in the batch).

  • mask_len_samples (int) – Number of consecutive samples to zero out.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[2]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

braindecode.augmentation.functional.time_reverse(X, y)[source]#

Flip the time axis of each input.

Parameters:
Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

braindecode.augmentation.transforms module#

class braindecode.augmentation.transforms.BandstopFilter(probability, sfreq, bandwidth=1, max_freq=None, random_state=None)[source]#

Bases: Transform

Apply a band-stop filter with desired bandwidth at a randomly selected frequency position between 0 and max_freq.

Suggested e.g. in [1] and [2]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • bandwidth (float) – Bandwidth of the filter, i.e. distance between the low and high cut frequencies.

  • sfreq (float, optional) – Sampling frequency of the signals to be filtered. Defaults to 100 Hz.

  • max_freq (float | None, optional) – Maximal admissible frequency. The low cut frequency will be sampled so that the corresponding high cut frequency + transition (=1Hz) are below max_freq. If omitted or None, will default to the Nyquist frequency (sfreq / 2).

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[2]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains

  • sfreqfloat

    Sampling frequency of the signals to be filtered.

  • bandwidthfloat

    Bandwidth of the filter, i.e. distance between the low and high cut frequencies.

  • freqs_to_notcharray-like | None

    Array of floats of size (batch_size,) containing the center of the frequency band to filter out for each sample in the batch. Frequencies should be greater than bandwidth/2 + transition and lower than sfreq/2 - bandwidth/2 - transition (where transition = 1 Hz).

Return type:

dict

static operation(X, y, sfreq, bandwidth, freqs_to_notch)[source]#

Apply a band-stop filter with desired bandwidth at the desired frequency position.

Suggested e.g. in [1] and [2]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • sfreq (float) – Sampling frequency of the signals to be filtered.

  • bandwidth (float) – Bandwidth of the filter, i.e. distance between the low and high cut frequencies.

  • freqs_to_notch (array-like | None) – Array of floats of size (batch_size,) containing the center of the frequency band to filter out for each sample in the batch. Frequencies should be greater than bandwidth/2 + transition and lower than sfreq/2 - bandwidth/2 - transition (where transition = 1 Hz).

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[2]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

class braindecode.augmentation.transforms.ChannelsDropout(probability, p_drop=0.2, random_state=None)[source]#

Bases: Transform

Randomly set channels to flat signal.

Part of the CMSAugment policy proposed in [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • proba_drop (float | None, optional) – Float between 0 and 1 setting the probability of dropping each channel. Defaults to 0.2.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether or not to transform given the probability argument and to sample channels to erase. Defaults to None.

References

[1]

Saeed, A., Grangier, D., Pietquin, O., & Zeghidour, N. (2020). Learning from Heterogeneous EEG Signals with Differentiable Channel Reordering. arXiv preprint arXiv:2010.13694.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains

  • p_dropfloat

    Float between 0 and 1 setting the probability of dropping each channel.

  • random_statenumpy.random.Generator

    The generator to use.

Return type:

dict

static operation(X, y, p_drop, random_state=None)[source]#

Randomly set channels to flat signal.

Part of the CMSAugment policy proposed in [1]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • p_drop (float) – Float between 0 and 1 setting the probability of dropping each channel.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Saeed, A., Grangier, D., Pietquin, O., & Zeghidour, N. (2020). Learning from Heterogeneous EEG Signals with Differentiable Channel Reordering. arXiv preprint arXiv:2010.13694.

class braindecode.augmentation.transforms.ChannelsShuffle(probability, p_shuffle=0.2, random_state=None)[source]#

Bases: Transform

Randomly shuffle channels in EEG data matrix.

Part of the CMSAugment policy proposed in [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • p_shuffle (float | None, optional) – Float between 0 and 1 setting the probability of including the channel in the set of permuted channels. Defaults to 0.2.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether or not to transform given the probability argument, to sample which channels to shuffle and to carry the shuffle. Defaults to None.

References

[1]

Saeed, A., Grangier, D., Pietquin, O., & Zeghidour, N. (2020). Learning from Heterogeneous EEG Signals with Differentiable Channel Reordering. arXiv preprint arXiv:2010.13694.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains

  • p_shufflefloat

    Float between 0 and 1 setting the probability of including the channel in the set of permuted channels.

  • random_statenumpy.random.Generator

    The generator to use.

Return type:

dict

static operation(X, y, p_shuffle, random_state=None)[source]#

Randomly shuffle channels in EEG data matrix.

Part of the CMSAugment policy proposed in [1]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • p_shuffle (float | None) – Float between 0 and 1 setting the probability of including the channel in the set of permutted channels.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to sample which channels to shuffle and to carry the shuffle. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Saeed, A., Grangier, D., Pietquin, O., & Zeghidour, N. (2020). Learning from Heterogeneous EEG Signals with Differentiable Channel Reordering. arXiv preprint arXiv:2010.13694.

class braindecode.augmentation.transforms.ChannelsSymmetry(probability, ordered_ch_names, random_state=None)[source]#

Bases: Transform

Permute EEG channels inverting left and right-side sensors.

Suggested e.g. in [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • ordered_ch_names (list) – Ordered list of strings containing the names (in 10-20 nomenclature) of the EEG channels that will be transformed. The first name should correspond the data in the first row of X, the second name in the second row and so on.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether or not to transform given the probability argument. Defaults to None.

References

[1]

Deiss, O., Biswal, S., Jin, J., Sun, H., Westover, M. B., & Sun, J. (2018). HAMLET: interpretable human and machine co-learning technique. arXiv preprint arXiv:1803.09702.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains

  • permutationfloat

    List of integers defining the new channels order.

Return type:

dict

static operation(X, y, permutation)[source]#

Permute EEG channels according to fixed permutation matrix.

Suggested e.g. in [1]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • permutation (list) – List of integers defining the new channels order.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Deiss, O., Biswal, S., Jin, J., Sun, H., Westover, M. B., & Sun, J. (2018). HAMLET: interpretable human and machine co-learning technique. arXiv preprint arXiv:1803.09702.

class braindecode.augmentation.transforms.FTSurrogate(probability, phase_noise_magnitude=1, channel_indep=False, random_state=None)[source]#

Bases: Transform

FT surrogate augmentation of a single EEG channel, as proposed in [1].

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • phase_noise_magnitude (float | torch.Tensor, optional) – Float between 0 and 1 setting the range over which the phase perturbation is uniformly sampled: [0, phase_noise_magnitude * 2 * pi]. Defaults to 1.

  • channel_indep (bool, optional) – Whether to sample phase perturbations independently for each channel or not. It is advised to set it to False when spatial information is important for the task, like in BCI. Default False.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether or not to transform given the probability argument. Defaults to None.

References

[1]

Schwabedal, J. T., Snyder, J. C., Cakmak, A., Nemati, S., & Clifford, G. D. (2018). Addressing Class Imbalance in Classification Problems of Noisy Signals by using Fourier Transform Surrogates. arXiv preprint arXiv:1806.08675.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains:

  • phase_noise_magnitudefloat

    The magnitude of the transformation.

  • random_statenumpy.random.Generator

    The generator to use.

Return type:

dict

static operation(X, y, phase_noise_magnitude, channel_indep, random_state=None)[source]#

FT surrogate augmentation of a single EEG channel, as proposed in [1].

Function copied from cliffordlab/sleep-convolutions-tf and modified.

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • phase_noise_magnitude (float) – Float between 0 and 1 setting the range over which the phase perturbation is uniformly sampled: [0, phase_noise_magnitude * 2 * pi].

  • channel_indep (bool) – Whether to sample phase perturbations independently for each channel or not. It is advised to set it to False when spatial information is important for the task, like in BCI.

  • random_state (int | numpy.random.Generator, optional) – Used to draw the phase perturbation. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Schwabedal, J. T., Snyder, J. C., Cakmak, A., Nemati, S., & Clifford, G. D. (2018). Addressing Class Imbalance in Classification Problems of Noisy Signals by using Fourier Transform Surrogates. arXiv preprint arXiv:1806.08675.

class braindecode.augmentation.transforms.FrequencyShift(probability, sfreq, max_delta_freq=2, random_state=None)[source]#

Bases: Transform

Add a random shift in the frequency domain to all channels.

Note that here, the shift is the same for all channels of a single example.

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • sfreq (float) – Sampling frequency of the signals to be transformed.

  • max_delta_freq (float | torch.Tensor, optional) – Maximum shift in Hz that can be sampled (in absolute value). Defaults to 2 (shift sampled between -2 and 2 Hz).

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains

  • delta_freqfloat

    The amplitude of the frequency shift (in Hz).

  • sfreqfloat

    Sampling frequency of the signals to be transformed.

Return type:

dict

static operation(X, y, delta_freq, sfreq)[source]#

Adds a shift in the frequency domain to all channels.

Note that here, the shift is the same for all channels of a single example.

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • delta_freq (float) – The amplitude of the frequency shift (in Hz).

  • sfreq (float) – Sampling frequency of the signals to be transformed.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

class braindecode.augmentation.transforms.GaussianNoise(probability, std=0.1, random_state=None)[source]#

Bases: Transform

Randomly add white noise to all channels.

Suggested e.g. in [1], [2] and [3]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • std (float, optional) – Standard deviation to use for the additive noise. Defaults to 0.1.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Wang, F., Zhong, S. H., Peng, J., Jiang, J., & Liu, Y. (2018). Data augmentation for eeg-based emotion recognition with deep convolutional neural networks. In International Conference on Multimedia Modeling (pp. 82-93).

[2]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[3]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains

  • stdfloat

    Standard deviation to use for the additive noise.

  • random_statenumpy.random.Generator

    The generator to use.

Return type:

dict

static operation(X, y, std, random_state=None)[source]#

Randomly add white Gaussian noise to all channels.

Suggested e.g. in [1], [2] and [3]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • std (float) – Standard deviation to use for the additive noise.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Wang, F., Zhong, S. H., Peng, J., Jiang, J., & Liu, Y. (2018). Data augmentation for eeg-based emotion recognition with deep convolutional neural networks. In International Conference on Multimedia Modeling (pp. 82-93).

[2]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[3]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

class braindecode.augmentation.transforms.MaskEncoding(probability, max_mask_ratio=0.1, n_segments=1, random_state=None)[source]#

Bases: Transform

MaskEncoding from [1].

Replaces randomly chosen contiguous part (or parts) of all channels by zeros (if more than one segment, it may overlap).

Implementation based on [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • max_mask_ratio (float, optional) – Signal ratio to zero out. Defaults to 0.1.

  • n_segments (int, optional) – Number of segments to zero out in each example. Defaults to 1.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1] (1,2)

Ding, Wenlong, et al. “A Novel Data Augmentation Approach Using Mask Encoding for Deep Learning-Based Asynchronous SSVEP-BCI.” IEEE Transactions on Neural Systems and Rehabilitation Engineering 32 (2024): 875-886.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains …

Return type:

dict

static operation(X, y, time_start, segment_length, n_segments)[source]#

Mark encoding from Ding et al. (2024) from [ding2024].

Replaces a contiguous part (or parts) of all channels by zeros (if more than one segment, it may overlap).

Implementation based on [ding2024]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • time_start (torch.Tensor) – Tensor of integers containing the position (in last dimension) where to start masking the signal. Should have “n_segments” times the size of the first dimension of X (i.e. “n_segments” start positions per example in the batch).

  • segment_length (int) – Length of each segment to zero out.

  • n_segments (int) – Number of segments to zero out in each example.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[ding2024] (1,2)

Ding, Wenlong, et al. A Novel Data Augmentation Approach Using Mask Encoding for Deep Learning-Based Asynchronous SSVEP-BCI. IEEE Transactions on Neural Systems and Rehabilitation Engineering 32 (2024): 875-886.

class braindecode.augmentation.transforms.Mixup(alpha, beta_per_sample=False, random_state=None)[source]#

Bases: Transform

Implements Iterator for Mixup for EEG data. See [1]. Implementation based on [2].

Parameters:

  • alpha (float) – Mixup hyperparameter.

  • beta_per_sample (bool (default=False)) – By default, one mixing coefficient per batch is drawn from a beta distribution. If True, one mixing coefficient per sample is drawn.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Hongyi Zhang, Moustapha Cisse, Yann N. Dauphin, David Lopez-Paz (2018). mixup: Beyond Empirical Risk Minimization. In 2018 International Conference on Learning Representations (ICLR) Online: https://arxiv.org/abs/1710.09412

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains the values sampled uniformly between 0 and 1 setting the linear interpolation between examples (lam) and the shuffled indices of examples that are mixed into original examples (idx_perm).

Return type:

dict

static operation(X, y, lam, idx_perm)[source]#

Mixes two channels of EEG data.

See [1] for details. Implementation based on [2].

Parameters:

  • X (torch.Tensor) – EEG data in form batch_size, n_channels, n_times

  • y (torch.Tensor) – Target of length batch_size

  • lam (torch.Tensor) – Values between 0 and 1 setting the linear interpolation between examples.

  • idx_perm (torch.Tensor) – Permuted indices of example that are mixed into original examples.

Returns:

X, y. Where X is augmented and y is a tuple of length 3 containing the labels of the two mixed channels and the mixing coefficient.

Return type:

tuple

References

[1]

Hongyi Zhang, Moustapha Cisse, Yann N. Dauphin, David Lopez-Paz (2018). mixup: Beyond Empirical Risk Minimization. In 2018 International Conference on Learning Representations (ICLR) Online: https://arxiv.org/abs/1710.09412

class braindecode.augmentation.transforms.SegmentationReconstruction(probability, n_segments=None, random_state=None)[source]#

Bases: Transform

Segmentation Reconstruction from Lotte (2015) [Lotte2015].

Applies a segmentation-reconstruction transform to the input data, as proposed in [Lotte2015]. It segments each trial in the batch and randomly mix it to generate new synthetic trials by label, preserving the original order of the segments in time domain.

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether to transform given the probability argument and to sample the segments mixing. Defaults to None.

  • n_segments (int, optional) – Number of segments to use in the batch. If None, X will be automatically segmented, getting the last element in a list of factors of the number of samples’s square root. Defaults to None.

References

[Lotte2015] (1,2)

Lotte, F. (2015). Signal processing approaches to minimize or suppress calibration time in oscillatory activity-based brain–computer interfaces. Proceedings of the IEEE, 103(6), 871-890.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains the number of segments to split the signal into.

Return type:

dict

static operation(X, y, n_segments, data_classes, rand_indices, idx_shuffle)[source]#

Segment and reconstruct EEG data from [1].

See [1] for details.

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • n_segments (int) – Number of segments to use in the batch.

  • rand_indices (array-like) – Array of indices that indicates which trial to use in each segment.

  • idx_shuffle (array-like) – Array of indices to shuffle the new generated trials.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1] (1,2)

Lotte, F. (2015). Signal processing approaches to minimize or suppress calibration time in oscillatory activity-based brain–computer interfaces. Proceedings of the IEEE, 103(6), 871-890.

class braindecode.augmentation.transforms.SensorsRotation(probability, sensors_positions_matrix, axis='z', max_degrees=15, spherical_splines=True, random_state=None)[source]#

Bases: Transform

Interpolates EEG signals over sensors rotated around the desired axis with an angle sampled uniformly between -max_degree and max_degree.

Suggested in [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • sensors_positions_matrix (numpy.ndarray) –

    Matrix giving the positions of each sensor in a 3D cartesian coordinate system. Should have shape (3, n_channels), where n_channels is the number of channels. Standard 10-20 positions can be obtained from mne through:

    >>> ten_twenty_montage = mne.channels.make_standard_montage(
...    'standard_1020'
... ).get_positions()['ch_pos']

  • axis ('x' | 'y' | 'z', optional) – Axis around which to rotate. Defaults to ‘z’.

  • max_degree (float, optional) – Maximum rotation. Rotation angles will be sampled between -max_degree and max_degree. Defaults to 15 degrees.

  • spherical_splines (bool, optional) – Whether to use spherical splines for the interpolation or not. When False, standard scipy.interpolate.Rbf (with quadratic kernel) will be used (as in the original paper). Defaults to True.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Krell, M. M., & Kim, S. K. (2017). Rotational data augmentation for electroencephalographic data. In 2017 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 471-474).

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains four elements:

  • sensors_positions_matrixnumpy.ndarray

    Matrix giving the positions of each sensor in a 3D cartesian coordinate system. Should have shape (3, n_channels), where n_channels is the number of channels.

  • axis’x’ | ‘y’ | ‘z’

    Axis around which to rotate.

  • anglesarray-like

    Array of float of shape (batch_size,) containing the rotation angles (in degrees) for each element of the input batch, sampled uniformly between -max_degrees``and ``max_degrees.

  • spherical_splinesbool

    Whether to use spherical splines for the interpolation or not. When False, standard scipy.interpolate.Rbf (with quadratic kernel) will be used (as in the original paper).

Return type:

dict

static operation(X, y, sensors_positions_matrix, axis, angles, spherical_splines)[source]#

Interpolates EEG signals over sensors rotated around the desired axis with the desired angle.

Suggested in [1]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • sensors_positions_matrix (numpy.ndarray) –

    Matrix giving the positions of each sensor in a 3D cartesian coordinate system. Should have shape (3, n_channels), where n_channels is the number of channels. Standard 10-20 positions can be obtained from mne through:

    >>> ten_twenty_montage = mne.channels.make_standard_montage(
...    'standard_1020'
... ).get_positions()['ch_pos']

  • axis ('x' | 'y' | 'z') – Axis around which to rotate.

  • angles (array-like) – Array of float of shape (batch_size,) containing the rotation angles (in degrees) for each element of the input batch.

  • spherical_splines (bool) – Whether to use spherical splines for the interpolation or not. When False, standard scipy.interpolate.Rbf (with quadratic kernel) will be used (as in the original paper).

References

[1]

Krell, M. M., & Kim, S. K. (2017). Rotational data augmentation for electroencephalographic data. In 2017 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 471-474).

class braindecode.augmentation.transforms.SensorsXRotation(probability, ordered_ch_names, max_degrees=15, spherical_splines=True, random_state=None)[source]#

Bases: SensorsRotation

Interpolates EEG signals over sensors rotated around the X axis with an angle sampled uniformly between -max_degree and max_degree.

Suggested in [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • ordered_ch_names (list) – List of strings representing the channels of the montage considered. Has to be in standard 10-20 style. The order has to be consistent with the order of channels in the input matrices that will be fed to the transform. This channel will be used to compute approximate sensors positions from a standard 10-20 montage.

  • max_degree (float, optional) – Maximum rotation. Rotation angles will be sampled between -max_degree and max_degree. Defaults to 15 degrees.

  • spherical_splines (bool, optional) – Whether to use spherical splines for the interpolation or not. When False, standard scipy.interpolate.Rbf (with quadratic kernel) will be used (as in the original paper). Defaults to True.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Krell, M. M., & Kim, S. K. (2017). Rotational data augmentation for electroencephalographic data. In 2017 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 471-474).

class braindecode.augmentation.transforms.SensorsYRotation(probability, ordered_ch_names, max_degrees=15, spherical_splines=True, random_state=None)[source]#

Bases: SensorsRotation

Interpolates EEG signals over sensors rotated around the Y axis with an angle sampled uniformly between -max_degree and max_degree.

Suggested in [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • ordered_ch_names (list) – List of strings representing the channels of the montage considered. Has to be in standard 10-20 style. The order has to be consistent with the order of channels in the input matrices that will be fed to the transform. This channel will be used to compute approximate sensors positions from a standard 10-20 montage.

  • max_degree (float, optional) – Maximum rotation. Rotation angles will be sampled between -max_degree and max_degree. Defaults to 15 degrees.

  • spherical_splines (bool, optional) – Whether to use spherical splines for the interpolation or not. When False, standard scipy.interpolate.Rbf (with quadratic kernel) will be used (as in the original paper). Defaults to True.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Krell, M. M., & Kim, S. K. (2017). Rotational data augmentation for electroencephalographic data. In 2017 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 471-474).

class braindecode.augmentation.transforms.SensorsZRotation(probability, ordered_ch_names, max_degrees=15, spherical_splines=True, random_state=None)[source]#

Bases: SensorsRotation

Interpolates EEG signals over sensors rotated around the Z axis with an angle sampled uniformly between -max_degree and max_degree.

Suggested in [1]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • ordered_ch_names (list) – List of strings representing the channels of the montage considered. Has to be in standard 10-20 style. The order has to be consistent with the order of channels in the input matrices that will be fed to the transform. This channel will be used to compute approximate sensors positions from a standard 10-20 montage.

  • max_degree (float, optional) – Maximum rotation. Rotation angles will be sampled between -max_degree and max_degree. Defaults to 15 degrees.

  • spherical_splines (bool, optional) – Whether to use spherical splines for the interpolation or not. When False, standard scipy.interpolate.Rbf (with quadratic kernel) will be used (as in the original paper). Defaults to True.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Krell, M. M., & Kim, S. K. (2017). Rotational data augmentation for electroencephalographic data. In 2017 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 471-474).

class braindecode.augmentation.transforms.SignFlip(probability, random_state=None)[source]#

Bases: Transform

Flip the sign axis of each input with a given probability.

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether or not to transform given the probability argument. Defaults to None.

static operation(X, y)[source]#

Flip the sign axis of each input.

Parameters:
Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

class braindecode.augmentation.transforms.SmoothTimeMask(probability, mask_len_samples=100, random_state=None)[source]#

Bases: Transform

Smoothly replace a randomly chosen contiguous part of all channels by zeros.

Suggested e.g. in [1] and [2]

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • mask_len_samples (int | torch.Tensor, optional) – Number of consecutive samples to zero out. Will be ignored if magnitude is not set to None. Defaults to 100.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Defaults to None.

References

[1]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[2]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

get_augmentation_params(*batch)[source]#

Return transform parameters.

Parameters:

  • X (tensor.Tensor) – The data.

  • y (tensor.Tensor) – The labels.

Returns:

params – Contains two elements:

  • mask_start_per_sampletorch.tensor

    Tensor of integers containing the position (in last dimension) where to start masking the signal. Should have the same size as the first dimension of X (i.e. one start position per example in the batch).

  • mask_len_samplesint

    Number of consecutive samples to zero out.

Return type:

dict

static operation(X, y, mask_start_per_sample, mask_len_samples)[source]#

Smoothly replace a contiguous part of all channels by zeros.

Originally proposed in [1] and [2]

Parameters:

  • X (torch.Tensor) – EEG input example or batch.

  • y (torch.Tensor) – EEG labels for the example or batch.

  • mask_start_per_sample (torch.tensor) – Tensor of integers containing the position (in last dimension) where to start masking the signal. Should have the same size as the first dimension of X (i.e. one start position per example in the batch).

  • mask_len_samples (int) – Number of consecutive samples to zero out.

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

References

[1]

Cheng, J. Y., Goh, H., Dogrusoz, K., Tuzel, O., & Azemi, E. (2020). Subject-aware contrastive learning for biosignals. arXiv preprint arXiv:2007.04871.

[2]

Mohsenvand, M. N., Izadi, M. R., & Maes, P. (2020). Contrastive Representation Learning for Electroencephalogram Classification. In Machine Learning for Health (pp. 238-253). PMLR.

class braindecode.augmentation.transforms.TimeReverse(probability, random_state=None)[source]#

Bases: Transform

Flip the time axis of each input with a given probability.

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • random_state (int | numpy.random.Generator, optional) – Seed to be used to instantiate numpy random number generator instance. Used to decide whether or not to transform given the probability argument. Defaults to None.

static operation(X, y)[source]#

Flip the time axis of each input.

Parameters:
Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Transformed labels.

On this page