Torcheeg

A new minor TorchEEG version release, bringing a new transform operation support to TorchEEG. It further includes some breaking changes.

Transform

* BaselineRemoval

python
eeg = np.random.randn(128, 9, 9)
baseline = np.ones((128, 9, 9))
transform = BaselineRemoval()
transformed_eeg = transform(eeg=eeg, baseline=baseline)['eeg']


TorchEEG now allows `BaselineRemoval` with preorder and followup operations. Usually, in order to ensure that baseline and eeg signal have the same shape and corresponding meaning, it is necessary to set `apply_to_baseline=True` to the transforms before BaselineRemoval.

python
eeg = np.random.randn(128, 9, 9)
baseline = np.ones((128, 9, 9))
transform = Compose([
ToTensor(apply_to_baseline=True), <-- preorder
Resize(size=(64, 64), apply_to_baseline=True), <-- preorder
RandomNoise(p=0.1), <-- preorder
BaselineRemoval(),
RandomMask(p=0.1) <-- followup
])
transformed_eeg = transform(eeg=eeg, baseline=baseline)['eeg']


If `baseline` is not passed in, no change is made to the input signal in the `BaselineRemoval` operation.

python
eeg = np.random.randn(128, 9, 9)
baseline = np.ones((128, 9, 9))
transform = BaselineRemoval()
transformed_eeg = transform(eeg=eeg)['eeg']


As other operations, `BaselineRemoval` can be performed in the `offline` phase or in the `online` phase. However, we strongly recommend using it in `online_transform` to save unnecessary computations.

python
dataset = DEAPDataset(io_path=f'./tmp_out/deap',
root_path='./tmp_in/data_preprocessed_python',
offline_transform=transforms.Compose(
[transforms.BandDifferentialEntropy(),
transforms.ToGrid(DEAP_CHANNEL_LOCATION_DICT)]),
online_transform=transforms.Compose([transforms.BaselineRemoval(),
transforms.ToTensor()]),
label_transform=transforms.Compose([
transforms.Select('valence'),
transforms.Binary(5.0),
]), num_worker=4)


Breaking Changes

The implementation of `transforms` follows the fashion of `albumentations` instead of `torchvision`.

* Named Input Named Output

The data passed into the transform operation must specify a name. For the transformation of EEG signals, the name of the input data is `eeg`, and the name of the output data is also `eeg`.

python
eeg = np.random.randn(32, 128)
transformed_eeg = ToTensor()(eeg=eeg)
transformed_eeg['eeg']


Multiple named inputs are allowed, and the corresponding outputs also have that name. A named input without a defined `apply` will be output directly (Usually used as a parameter).

python
eeg = np.random.randn(32, 128)
transformed_eeg = ToTensor()(eeg=eeg, somename=123)
transformed_eeg['eeg']
transformed_eeg['somename'] just 123


Synchronous Operation

* An operation can be applied to both the baseline signal and the experimental eeg signal by specifying `apply_to_baseline=True`.

python
eeg = np.random.randn(128, 9, 9)
baseline = np.ones((128, 9, 9))
transform = Compose([
ToTensor(apply_to_baseline=True), <-- for both input eeg and baseline signals
Resize(size=(64, 64), apply_to_baseline=True), <-- for both input eeg and baseline signals
RandomNoise(p=0.1),
BaselineRemoval(),
RandomMask(p=0.1)
])
transformed_eeg = transform(eeg=eeg, baseline=baseline)
transformed_eeg['eeg'] (after ToTensor, Resize, RandomNoise, BaselineRemoval, and RandomMask)
transformed_eeg['baseline'] (after ToTensor, Resize)


If you don't need to deeply customize the `BaseDataset`, just use `transforms` as usual:

python
dataset = DEAPDataset(io_path=f'./tmp_out/deap_{"".join(random.sample("zyxwvutsrqponmlkjihgfedcba", 20))}',
root_path='./tmp_in/data_preprocessed_python',
offline_transform=transforms.Compose(
[transforms.BandDifferentialEntropy(),
transforms.ToGrid(DEAP_CHANNEL_LOCATION_DICT)]),
online_transform=transforms.ToTensor()
label_transform=transforms.Compose([
transforms.Select('valence'),
transforms.Binary(5.0),
]), num_worker=4)

A new minor TorchEEG version release, bringing new dataset support and visualization tools to TorchEEG. It further includes some new features.

Datasets

- MAHNOB dataset from Soleymani et al.: [A multimodal database for affect recognition and implicit tagging](https://ieeexplore.ieee.org/abstract/document/5975141).

python
dataset = MAHNOBDataset(io_path=f'./mahnob',
root_path='./Sessions',
offline_transform=transforms.Compose([
transforms.BandDifferentialEntropy(),
transforms.ToGrid(MAHNOB_CHANNEL_LOCATION_DICT)
]),
online_transform=transforms.ToTensor(),
label_transform=transforms.Compose([
transforms.Select('feltVlnc'),
transforms.Binary(5.0),
]))


- AMIGOS dataset from Miranda-Correa et al.: [AMIGOS: A dataset for affect, personality and mood research on individuals and groups](https://ieeexplore.ieee.org/abstract/document/8554112/).

python
dataset = AMIGOSDataset(io_path=f'./amigos',
root_path='./data_preprocessed',
offline_transform=transforms.Compose([
transforms.BandDifferentialEntropy(),
transforms.ToGrid(AMIGOS_CHANNEL_LOCATION_DICT)
]),
online_transform=transforms.ToTensor(),
label_transform=transforms.Compose([
transforms.Select('valence'),
transforms.Binary(5.0),
]))


Visualization Tools

* Show topographic map of raw EEG signals.


eeg = torch.randn(32, 128)
img = plot_raw_topomap(eeg,
channel_list=DEAP_CHANNEL_LIST,
sampling_rate=128)


* Show topographic map of EEG features.


eeg = torch.randn(32, 4)
img = plot_feature_topomap(eeg,
channel_list=DEAP_CHANNEL_LIST,
feature_list=["theta", "alpha", "beta", "gamma"])


* Show signal values of raw EEG.


eeg = torch.randn(32, 128)
img = plot_signal(eeg,
channel_list=DEAP_CHANNEL_LIST,
sampling_rate=128)


* Show 3-d matrices (often used to debug EEG features as the CNN input).

python
eeg = torch.randn(128, 9, 9)
img = plot_3d_tensor(eeg)


* Show 2-d matrices (used to debug in other cases).

python
eeg = torch.randn(9, 9)
img = plot_2d_tensor(eeg)


Other Features


* A transform for general operation: PickElectrode.

python
transform = PickElectrode(PickElectrode.to_index_list(
['FP1', 'AF3', 'F3', 'F7',
'FC5', 'FC1', 'C3', 'T7',
'CP5', 'CP1', 'P3', 'P7',
'PO3','O1', 'FP2', 'AF4',
'F4', 'F8', 'FC6', 'FC2',
'C4', 'T8', 'CP6', 'CP2',
'P4', 'P8', 'PO4', 'O2'], DEAP_CHANNEL_LIST))
transform(torch.randn(32, 128))

We open sourced our internal EEG analysis library, TorchEEG! Welcome to TorchEEG!

Highlights

* **torcheeg.datasets:** The packaged benchmark dataset implementation provides a multi-process preprocessing interface. All datasets rely on a set of efficient IO APIs, [torcheeg.io](https://torcheeg.readthedocs.io/en/latest/torcheeg.io.html), to store data preprocessing results on disk and read them quickly during training. Data preprocessing and storage support multiprocessing (speed up!).

- DREAMER dataset from Katsigiannis et al.: [DREAMER: A database for emotion recognition through EEG and ECG signals from wireless low-cost off-the-shelf devices](https://ieeexplore.ieee.org/abstract/document/7887697).

python
dataset = DREAMERDataset(io_path=f'./dreamer',
mat_path='./DREAMER.mat',
offline_transform=.Compose([
transforms.BandDifferentialEntropy(),
transforms.ToGrid(DREAMER_CHANNEL_LOCATION_DICT)
]),
online_transform=transforms.ToTensor(),
label_transform=transforms.Compose([
transforms.Select('valence'),
transforms.Binary(3.0),
]))


- SEED dataset from Zheng et al.: [Investigating critical frequency bands and channels for EEG-based emotion recognition with deep neural networks](https://ieeexplore.ieee.org/abstract/document/7104132).

python
dataset = SEEDDataset(io_path=f'./seed',
root_path='./Preprocessed_EEG',
offline_transform=transforms.Compose([
transforms.BandDifferentialEntropy(),
transforms.ToGrid(SEED_CHANNEL_LOCATION_DICT)
]),
online_transform=transforms.ToTensor(),
label_transform=transforms.Compose([
transforms.Select(['emotion']),
transforms.Lambda(x: x + 1)
]))


- DEAP dataset from Koelstra et al.: [DEAP: A database for emotion analysis; using physiological signals](https://ieeexplore.ieee.org/abstract/document/5871728).

python
dataset = DEAPDataset(io_path=f'./deap',
root_path='./data_preprocessed_python',
offline_transform=.Compose([
transforms.BandDifferentialEntropy(),
transforms.ToGrid(DEAP_CHANNEL_LOCATION_DICT)
]),
online_transform=transforms.ToTensor(),
label_transform=transforms.Compose([
transforms.Select('valence'),
transforms.Binary(5.0),
]))


* **torcheeg.transforms:** TorchEEG provides extensive data transformation tools to help users build EEG data representations suitable for a variety of task formulation and a variety of model structures.

* Feature Engineering: BandDifferentialEntropy, BandPowerSpectralDensity, BandMeanAbsoluteDeviation, BandKurtosis, BandSkewness, Concatenate.

python
transform = BandDifferentialEntropy()
transform(torch.randn(32, 128))

transform = BandDifferentialEntropy()
transform(torch.randn(32, 128))

transform = BandMeanAbsoluteDeviation()
transform(torch.randn(32, 128))

transform = BandKurtosis()
transform(torch.randn(32, 128))

transform = BandSkewness()
transform(torch.randn(32, 128))

transform = Concatenate([
BandDifferentialEntropy(),
BandMeanAbsoluteDeviation()
])
transform(torch.randn(32, 128))


* General Operation: MeanStdNormalize, MinMaxNormalize.

python
transform = MeanStdNormalize(axis=0)
transform(torch.randn(32, 128))

transform = MinMaxNormalize(axis=0)
transform(torch.randn(32, 128))


* For CNN: To2d, ToGrid, ToInterpolatedGrid.

python
transform = To2d()
transform(torch.randn(32, 128))

transform = ToGrid(DEAP_CHANNEL_LOCATION_DICT)
transform(torch.randn(32, 128))

transform = ToInterpolatedGrid(DEAP_CHANNEL_LOCATION_DICT)
transform(torch.randn(32, 128))


* For GNN: ToG.

python
transform = ToG(adj=DEAP_ADJACENCY_MATRIX)
transform(np.random.randn(32, 128))


* For Augmentation: ToTensor, Resize, RandomNoise, RandomMask.

python
transform = ToTensor()
transform(np.random.randn(32, 128))

transform = ToTensor(size=(64, 64))
transform(torch.randn(128, 9, 9))

transform = RandomNoise(p=0.5)
transform(torch.randn(32, 128))

transform = RandomMask()
transform(torch.randn(32, 128))


* For Label Construction: Select, Binary, BinariesToCategory.

python
transform = Select(key='valence')
transform({'valence': 4.5, 'arousal': 5.5, 'subject': 7})

transform = Binary(threshold=5.0)
transform(4.5)

transform = BinariesToCategory()
transform([0, 0])


* **torcheeg.model_selection:** Extensive dataset partitioning methods for users to experiment with different settings.

* Subject Dependent: KFoldTrialPerSubject, train_test_split_trial_per_subject.

python
cv = KFoldTrialPerSubject(n_splits=5, shuffle=True, split_path='./split')
cv.split(dataset)

train_test_split_trial_per_subject(dataset=dataset, split_path='./split')


* Subject Independent: LeaveOneSubjectOut.

python
cv = LeaveOneSubjectOut('./split')
cv.split(dataset)


* Conventional: KFoldDataset, train_test_split_dataset, KFoldTrial, train_test_split_trial.

python
cv = KFoldDataset(n_splits=5, shuffle=True, split_path='./split')
cv.split(dataset)

train_test_split_dataset(dataset=dataset, split_path='./split')

cv = KFoldTrial(n_splits=5, shuffle=False, split_path='./split')
cv.split(dataset)

train_test_split_trial(dataset=dataset, split_path='./split')