permute_channels

selfeeg.augmentation.functional.permute_channels(x: ArrayLike, chan2shuf: int = -1, mode: str = 'random', channel_map: list = None, chan_net: list[str] = 'all', batch_equal: bool = True) → ArrayLike[source]

permutes the ArrayLike object along the EEG channel dimension.

Given an input x where the last two dimensions must be (EEG_channels x EEG_samples), permutation_channels shuffles all or a subset of the EEG’s channels. Shuffles can be done randomly or using specific networks (based on resting state functional connectivity networks).

Parameters:

  • x (ArrayLike) – The input Tensor or Array. The last two dimensions must refer to the EEG recording (Channels x Samples). Thus, permutation is applied on the second to last dimension.

  • chan2shuf (int, optional) –

    The number of channels to shuffle. It must be greater than 1. Only exception is -1, which can be given to permute all the channels.

    Default = -1

  • mode (str, optional) –

    How to permute the channels. Can be:

    • ’random’: shuffle channels at random

    • ’network’: shuffle channels which belongs to the same network. A network is a subset of channels whose activity is (with a minumum degree) correlated between each other. This mode support only a subset of 61 channels of the 10-10 system.

    Default = “random”

  • channel_map (list[str], optional) –

    The EEG channel map. Must be a list of strings or a numpy array of dtype=’<U4’ with channel names as elements. Channel name must be defined with capital letters (e.g. ‘P04’, ‘FC5’). If None is left the following 61 channel map is initialized:

    • [‘FP1’, ‘AF7’, ‘AF3’, ‘F1’, ‘F3’, ‘F5’, ‘F7’, ‘FT7’, ‘FC5’, ‘FC3’, ‘FC1’, ‘C1’, ‘C3’, ‘C5’, ‘T7’, ‘TP7’, ‘CP5’, ‘CP3’, ‘CP1’, ‘P1’, ‘P3’, ‘P5’, ‘P7’, ‘PO7’, ‘PO3’, ‘O1’, ‘OZ’, ‘POZ’, ‘PZ’, ‘CPZ’, ‘FPZ’, ‘FP2’, ‘AF8’, ‘AF4’, ‘AFZ’, ‘FZ’, ‘F2’, ‘F4’, ‘F6’, ‘F8’, ‘FT8’, ‘FC6’, ‘FC4’, ‘FC2’, ‘FCZ’, ‘CZ’, ‘C2’, ‘C4’, ‘C6’, ‘T8’, ‘TP8’, ‘CP6’, ‘CP4’, ‘CP2’, ‘P2’, ‘P4’, ‘P6’, ‘P8’, ‘PO8’, ‘PO4’, ‘O2’]

    Default = None

  • chan_net (str or list[str], optional) –

    The list of networks to use if network mode is selected. Must be a list of string or a single string. Supported networks are “DMN”, “DAN”, “VAN”, “SMN”, “VFN”, “FPN”. Use ‘all’ to select all networks. To get a list of the channel names per network call the get_eeg_network_channel_names function.

    Default = ‘all’

  • batch_equal (bool, optional) –

    whether to apply the same permutation to all EEG record or not. If True, permute_signal is called recursively in order to permute each EEG differently.

    Default = True

Returns:

x (ArrayLike) – The augmented version of the input Tensor or Array.

Warning

Using chan2shuf = -1 and mode = ‘network’ can result in a lower number of channels permuted compared to the whole list of channels included in the networks. This is due to the implementation of the permutation block in network mode, which iteratively applies the channel permutation at each single network, sequentially excluding channels already permuted in previous steps (networks are not mutually exclusive, there are overlapping channels). At some point a network may remain with only one channel to permute, which cannot be permuted since it is alone. This applies only in contexts where the number of channel is near the number of the selected ones.

See also

get_channel_map_and_networks

creates the channel map and networks arrays.

get_eeg_channel_network_names

prints the channel network arrays.

Example

>>> import torch
>>> import numpy as np
>>> import selfeeg.augmentation as aug
>>> x = torch.zeros(61,4) + torch.arange(61).reshape(61,1)
>>> xaug = aug.permute_channels(x,10)
>>> print( (x[:,0]!=xaug[:,0]).sum()) # should output 10
>>> # Try with network mode and check if channels not in the selected networks were permuted
>>> eeg1010, chan_net = aug.get_channel_map_and_networks(chan_net=["DMN","VFN"])
>>> chan2per = np.union1d(chan_net[0], chan_net[1])
>>> a=np.intersect1d(eeg1010, chan2per, return_indices=True)[1]
>>> b=torch.from_numpy( np.delete(np.arange(61),a))
>>> xaug2 = aug.permute_channels(x,50, mode='network', chan_net=["DMN","VFN"])
>>> print( ((x[:,0]!=xaug2[:,0]).sum())==50) # should output True
>>> print( ((x[b,0]==xaug2[b,0]).sum())==len(b) ) # should output True