Torcheeg

An emergency fix for TorchEEG v1.0.8 to avoid crashes with `pywt`.


ERROR: Could not find a version that satisfies the requirement pywt (from versions: none)
ERROR: No matching distribution found for pywt


For the new features brought by TorchEEG v1.0.8, please refer to https://github.com/tczhangzhi/torcheeg/releases/tag/v1.0.8 (as follows).

Datasets

TorchEEG is actively supporting BCI events ongoing this year, including the [BCI Controlled Robot Contest - 2022 World Robot Conference](https://oneuro.cn/n/competitiondetail/2022_emotion_bci/), and the [EEG-based Biometric Competition - 2022 Brain-Computer Interface Algorithm Challenge](https://aistudio.baidu.com/aistudio/competition/detail/315/0/introduction).

- BCI2022Dataset for BCI Controlled Robot Contest - 2022 World Robot Conference

python
dataset = BCI2022Dataset(
io_path='./tmp_out/bci2022',
root_path='./tmp_in/TrainSet',
offline_transform=transforms.BandDifferentialEntropy(),
label_transform=transforms.Select('emotion'),
channel_num=30,
num_worker=9
)




- M3CVDataset for EEG-based Biometric Competition - 2022 Brain-Computer Interface Algorithm Challenge

python
en_dataset = M3CVDataset(io_path='./tmp_out/m3cv_en',
root_path='./tmp_in/aistudio',
subset='Enrollment',
num_worker=9)
te_dataset = M3CVDataset(io_path='./tmp_out/m3cv_te',
root_path='./tmp_in/aistudio',
subset='Testing',
num_worker=9)
ca_dataset = M3CVDataset(io_path='./tmp_out/m3cv_ca',
root_path='./tmp_in/aistudio',
subset='Calibration',
num_worker=9)


Transforms

- CWTSpectrum

python
transform = CWTSpectrum()
transform(eeg=np.random.randn(32, 1000))['eeg']


- ARRCoefficient

python
transform = ARRCoefficient(order=4)
transform(eeg=np.random.randn(32, 128))['eeg']


- ChunkConcatenate

python
transform = ChunkConcatenate(
[BandDifferentialEntropy(),
BandMeanAbsoluteDeviation()],
chunk_size=250,
overlap=0)
transform(eeg=np.random.randn(64, 1000))['eeg']


Bug Fixes

- Fix a data type error in documentation
- Fix a bug where data partitioning could not be fixed with random seeds when running the program multiple times

To help users use TorchEEG more easily, new examples have been added to illustrate how to train and test models in BCI competitions.

- [Examples of the baseline submission for BCI Controlled Robot Contest - 2022 World Robot Conference](https://github.com/tczhangzhi/torcheeg/blob/main/examples/examples_bci2022_competition.py)
- [Examples of the baseline submission for EEG-based Biometric Competition - 2022 Brain-Computer Interface Algorithm Challenge](https://github.com/tczhangzhi/torcheeg/blob/main/examples/examples_m3cv_competition.py)

A new minor TorchEEG release brings new datasets and transformation supports to TorchEEG. It further includes some bug fixes. More feedback was taken to improve TorchEEG usability.

Datasets

TorchEEG is actively supporting BCI events ongoing this year, including the [BCI Controlled Robot Contest - 2022 World Robot Conference](https://oneuro.cn/n/competitiondetail/2022_emotion_bci/), and the [EEG-based Biometric Competition - 2022 Brain-Computer Interface Algorithm Challenge](https://aistudio.baidu.com/aistudio/competition/detail/315/0/introduction).

- BCI2022Dataset for BCI Controlled Robot Contest - 2022 World Robot Conference

python
dataset = BCI2022Dataset(
io_path='./tmp_out/bci2022',
root_path='./tmp_in/TrainSet',
offline_transform=transforms.BandDifferentialEntropy(),
label_transform=transforms.Select('emotion'),
channel_num=30,
num_worker=9
)


- M3CVDataset for EEG-based Biometric Competition - 2022 Brain-Computer Interface Algorithm Challenge

python
en_dataset = M3CVDataset(io_path='./tmp_out/m3cv_en',
root_path='./tmp_in/aistudio',
subset='Enrollment',
num_worker=9)
te_dataset = M3CVDataset(io_path='./tmp_out/m3cv_te',
root_path='./tmp_in/aistudio',
subset='Testing',
num_worker=9)
ca_dataset = M3CVDataset(io_path='./tmp_out/m3cv_ca',
root_path='./tmp_in/aistudio',
subset='Calibration',
num_worker=9)


Transforms

* CWTSpectrum

python
transform = CWTSpectrum()
transform(eeg=np.random.randn(32, 1000))['eeg']


* ARRCoefficient

python
transform = ARRCoefficient(order=4)
transform(eeg=np.random.randn(32, 128))['eeg']


* ChunkConcatenate

python
transform = ChunkConcatenate(
[BandDifferentialEntropy(),
BandMeanAbsoluteDeviation()],
chunk_size=250,
overlap=0)
transform(eeg=np.random.randn(64, 1000))['eeg']


Bug Fixes

* Fix a data type error in documentation
* Fix a bug where data partitioning could not be fixed with random seeds when running the program multiple times

To help users use TorchEEG more easily, new examples have been added to illustrate how to train and test models in BCI competitions.

- [Examples of the baseline submission for BCI Controlled Robot Contest - 2022 World Robot Conference](https://github.com/tczhangzhi/torcheeg/blob/main/examples/examples_bci2022_competition.py)
- [Examples of the baseline submission for EEG-based Biometric Competition - 2022 Brain-Computer Interface Algorithm Challenge](https://github.com/tczhangzhi/torcheeg/blob/main/examples/examples_m3cv_competition.py)

A new minor TorchEEG version release, bringing new `model_selection` supports to TorchEEG. It further includes some new features. More feedback was taken to improve TorchEEG usability.

model_selection

TorchEEG has reorganized the API related to data partitioning, new data partitioning methods have been added, and old data partitioning methods have been renamed more intuitively.

- KFold

python
cv = KFold(n_splits=5, shuffle=True, split_path='./split')
for train_dataset, test_dataset in cv.split(dataset):
train_loader = DataLoader(train_dataset)
test_loader = DataLoader(test_dataset)
...


* KFoldPerSubject

python
cv = KFoldPerSubject(n_splits=5, shuffle=True, split_path='./split')
for train_dataset, test_dataset in cv.split(dataset):
train_loader = DataLoader(train_dataset)
test_loader = DataLoader(test_dataset)
...


* KFoldGroupbyTrial

python
cv = KFoldGroupbyTrial(n_splits=5, shuffle=False, split_path='./split')
for train_dataset, test_dataset in cv.split(dataset):
train_loader = DataLoader(train_dataset)
test_loader = DataLoader(test_dataset)
...


* KFoldPerSubjectGroupbyTrial

python
cv = KFoldPerSubjectGroupbyTrial(n_splits=5, shuffle=True, split_path='./split')
for train_dataset, test_dataset in cv.split(dataset):
train_loader = DataLoader(train_dataset)
test_loader = DataLoader(test_dataset)
...


* KFoldCrossTrial

python
cv = KFoldCrossTrial(n_splits=5, shuffle=True, split_path='./split')
for train_dataset, test_dataset in cv.split(dataset):
train_loader = DataLoader(train_dataset)
test_loader = DataLoader(test_dataset)
...


* KFoldPerSubjectCrossTrial

python
cv = KFoldPerSubjectCrossTrial(n_splits=5, shuffle=True, split_path='./split')
for train_dataset, test_dataset in cv.split(dataset):
train_loader = DataLoader(train_dataset)
test_loader = DataLoader(test_dataset)
...


* LeaveOneSubjectOut

python
cv = LeaveOneSubjectOut('./split')
for train_dataset, test_dataset in cv.split(dataset):
train_loader = DataLoader(train_dataset)
test_loader = DataLoader(test_dataset)
...


* train_test_split

python
train_dataset, test_dataset = train_test_split(dataset=dataset, split_path='./split')


* train_test_split_groupby_trial

python
train_dataset, test_dataset = train_test_split_groupby_trial(dataset=dataset, split_path='./split')


* train_test_split_per_subject_groupby_trial

python
train_dataset, test_dataset = train_test_split_per_subject_groupby_trial(dataset=dataset, split_path='./split')


* train_test_split_cross_trial

python
train_dataset, test_dataset = train_test_split_cross_trial(dataset=dataset, split_path='./split')


* train_test_split_per_subject_cross_trial

python
train_dataset, test_dataset = train_test_split_per_subject_cross_trial(dataset=dataset, split_path='./split')


Examples

To help users use TorchEEG more easily, new examples have been added to illustrate how to train and test models.

* [Examples of the CCNN model on the DEAP dataset](https://github.com/tczhangzhi/torcheeg/blob/main/examples/examples_ccnn.py)

* [Examples of the DGCNN model on the SEED dataset](https://github.com/tczhangzhi/torcheeg/blob/main/examples/examples_dgcnn.py)

* [Examples of the STNet model on the DEAP dataset](https://github.com/tczhangzhi/torcheeg/blob/main/examples/examples_stnet.py)

* [Examples of the TSCeption model on the DEAP dataset](https://github.com/tczhangzhi/torcheeg/blob/main/examples/examples_tsception.py)

* [Examples of accelerated preprocessing using multiprocessing for the DEAP and SEED datasets](https://github.com/tczhangzhi/torcheeg/blob/main/examples/examples_dataset_runtime.py)

This is a minor release, bringing some emergency fixes to TorchEEG v1.0.5.

Bugfixes

Fixed a bug in dataset initialization, where multiprocess data IO failed on Windows.

shell
pandas.errors.EmptyDataError: No columns to parse from file


Fixed bug in installation, where PyG reported core dump.

shell
Aborted (core dumped)


Fixed a bug in dataset initialization, where the space requested by lmdb is larger than the remaining disk space on Windows.

shell
lmdb.Error

A new minor TorchEEG version release, bringing new transform operation supports to TorchEEG. It further includes some new features. More feedback was taken to improve TorchEEG usability.

Transforms

TorchEEG further supports a large number of practical torch-based data augmentation methods.

- RandomWindowSlice

python
transform = RandomWindowSlice()
transform(eeg=torch.randn(32, 128))['eeg'].shape
>>> (32, 128)

transform = RandomWindowSlice(window_size=100)
transform(eeg=torch.randn(1, 32, 128))['eeg'].shape
>>> (1, 32, 128)

transform = RandomWindowSlice(p=1.0, series_dim=0)
transform(eeg=torch.randn(128, 9, 9))['eeg'].shape
>>> (128, 9, 9)


* RandomWindowWarp

python
transform = RandomWindowWarp()
transform(eeg=torch.randn(32, 128))['eeg'].shape
>>> (32, 128)

transform = RandomWindowWarp(window_size=24, warp_size=48)
transform(eeg=torch.randn(1, 32, 128))['eeg'].shape
>>> (1, 32, 128)

transform = RandomWindowWarp(p=1.0, series_dim=0)
transform(eeg=torch.randn(128, 9, 9))['eeg'].shape
>>> (128, 9, 9)


* RandomPCANoise

python
transform = RandomPCANoise()
transform(eeg=torch.randn(32, 128))['eeg'].shape
>>> (32, 128)

transform = RandomPCANoise(mean=0.5, std=2.0, n_components=4)
transform(eeg=torch.randn(1, 32, 128))['eeg'].shape
>>> (1, 32, 128)

transform = RandomPCANoise(p=1.0, series_dim=0)
transform(eeg=torch.randn(128, 9, 9))['eeg'].shape
>>> (128, 9, 9)


* RandomFlip

python
transform = RandomFlip(dim=-1)
transform(eeg=torch.randn(32, 128))['eeg'].shape
>>> (32, 128)

transform = RandomFlip(dim=1)
transform(eeg=torch.randn(128, 9, 9))['eeg'].shape
>>> (128, 9, 9)


* RandomSignFlip

python
transform = RandomSignFlip()
transform(eeg=torch.randn(32, 128))['eeg'].shape
>>> (32, 128)


* RandomShift

python
transform = RandomShift(dim=-1, shift_min=8, shift_max=24)
transform(eeg=torch.randn(32, 128))['eeg'].shape
>>> (32, 128)


* RandomChannelShuffle

python
transform = RandomChannelShuffle()
transform(eeg=torch.randn(32, 128))['eeg'].shape
>>> (32, 128)


* RandomFrequencyShift

python
transform = RandomFrequencyShift()
transform(eeg=torch.randn(32, 128))['eeg'].shape
>>> (32, 128)

transform = RandomFrequencyShift(frequency=128, shift_min=4.0)
transform(eeg=torch.randn(1, 32, 128))['eeg'].shape
>>> (1, 32, 128)

transform = RandomFrequencyShift(p=1.0, series_dim=0)
transform(eeg=torch.randn(128, 9, 9))['eeg'].shape
>>> (128, 9, 9)


On the transformation of constructing graphs, TorchEEG provides a dynamic graph constructing strategy, which makes some GNN algorithms based on computational functional connections more easily implemented.

* ToDynamicG

python
transform = ToDynamicG(edge_func='gaussian_distance', sigma=1.0, top_k=10, complete_graph=False)
transform(eeg=np.random.randn(32, 128))['eeg']
>>> Data(edge_index=[2, 320], x=[32, 128], edge_weight=[320])

transform = ToDynamicG(edge_func='absolute_pearson_correlation_coefficient', threshold=0.1, binary=True)
transform(eeg=np.random.randn(32, 128))['eeg']
>>> Data(edge_index=[2, 310], x=[32, 128], edge_weight=[310])

transform = ToDynamicG(edge_func='phase_locking_value')
transform(eeg=np.random.randn(32, 128))['eeg']
>>> Data(edge_index=[2, 992], x=[32, 128], edge_weight=[992])

transform = ToDynamicG(edge_func=lambda x, y: (x * y).mean())
transform(eeg=np.random.randn(32, 128))['eeg']
>>> Data(edge_index=[2, 1024], x=[32, 128], edge_weight=[1024])


Utils

In terms of visualization, TorchEEG further supports the visualization of graph data structures to help users debug graph structures.

- plot_graph

python
eeg = np.random.randn(32, 128)
g = ToG(DEAP_ADJACENCY_MATRIX)(eeg=eeg)['eeg']
plot_graph(g)

A new minor TorchEEG version release, fixing bugs in TorchEEG v1.0.3. After v1.0.4, the TorchEEG architecture will remain stable in the v1.0 phase.

IO

- EEGSignalIO

Allows storage of different different types of data.

python
io_cache_path = f'./tmp_out/io'
io = EEGSignalIO(cache_path=io_cache_path)

eeg = torch.randn(32, 128)
io_eeg_idx = io.write_eeg(eeg)

eeg = np.random.randn(32, 128)
io_eeg_idx = io.write_eeg(eeg)

io_eeg = io.read_eeg(io_eeg_idx)
self.assertTrue(np.array_equal(eeg, io_eeg))


Allows storage of different different shapes of data.

python
io_cache_path = f'./tmp_out/io'
io = EEGSignalIO(cache_path=io_cache_path)

eeg = np.random.randn(32, 128)
io_eeg_idx = io.write_eeg(eeg)

eeg = np.random.randn(128, 9, 9)
io_eeg_idx = io.write_eeg(eeg)

io_eeg = io.read_eeg(io_eeg_idx)
self.assertTrue(np.array_equal(eeg, io_eeg))


Dataset

* AMIGOSDataset, DEAPDataset, DREAMERDataset, MAHNOBDataset

Unify the behavior of `offline_transform` and `online_transform`. By default, baseline is not preprocessed unless `apply_to_baseline=True` is set.

python
dataset = DEAPDataset(io_path=io_path,
root_path=root_path,
need to set apply_to_baseline=True before BaselineRemoval
offline_transform=transforms.BandDifferentialEntropy(
apply_to_baseline=True),
online_transform=transforms.Compose([transforms.BaselineRemoval(),
transforms.ToTensor()]),
label_transform=transforms.Compose([
transforms.Select('valence'),
transforms.Binary(5.0),
]),
num_worker=4)