Multiple discrete targets with the TUH EEG Corpus#

Welcome to this tutorial where we demonstrate how to work with multiple discrete targets for each recording in the TUH EEG Corpus. We’ll guide you through the process step by step.

# Author: Lukas Gemein <l.gemein@gmail.com>
#         Daria Agafonova
#
# License: BSD (3-clause)

import mne
import numpy as np
import torch
from torch.utils.data import DataLoader

from braindecode.datasets import TUH, BaseConcatDataset, RawDataset
from braindecode.preprocessing import create_fixed_length_windows
from braindecode.util import set_random_seeds

# Setting Logging Level
# ----------------------
#
# We'll set the logging level to 'ERROR' to avoid excessive messages when
# extracting windows:

mne.set_log_level("ERROR")  # avoid messages every time a window is extracted

cuda = torch.cuda.is_available()
seed = 20240205
set_random_seeds(seed=seed, cuda=cuda)

If you want to try this code with the actual data, please delete the next section. We are required to mock some dataset functionality, since the data is not available at creation time of this example. We use the mock’s four-recording v1.1.0 corpus so the subset example below includes recordings with different labels.

from braindecode.datasets.tuh import _TUHMock as TUH  # noqa F811

Creating Temple University Hospital (TUH) EEG Corpus Dataset#

We start by creating a TUH dataset. Instead of just a str, we give it multiple strings as target names. Each of the strings has to exist as a column in the description DataFrame.

TUH_PATH = "please insert actual path to data here"
tuh = TUH(
    path=TUH_PATH,
    version="v1.1.0",
    recording_ids=None,
    target_name=("age", "gender"),  # use both age and gender as decoding target
    preload=False,
    add_physician_reports=False,
)
print(tuh.description)
                                                path version  ...  age gender
0  tuh_eeg/v1.1.0/edf/02_tcp_le/000/00000058/s001...  v1.1.0  ...    0      M
1  tuh_eeg/v1.1.0/edf/01_tcp_ar/099/00009932/s004...  v1.1.0  ...   53      F
2  tuh_eeg/v1.1.0/edf/03_tcp_ar_a/123/00012331/s0...  v1.1.0  ...   39      M
3  tuh_eeg/v1.1.0/edf/01_tcp_ar/000/00000000/s001...  v1.1.0  ...   37      M

[4 rows x 10 columns]

Exploring Data#

Iterating through the dataset gives x as an ndarray with shape (n_channels x 1) and y as a list containing [age of the subject, gender of the subject]. Let’s look at the last example as it has more interesting age/gender labels (compare to the last row of the dataframe above).

x, y = tuh[-1]

print(f"{x=}\n{y=}")
x=array([[-0.08388354],
       [ 0.45734062],
       [ 0.17444011],
       [ 0.43492043],
       [-0.35701738],
       [ 0.12402036],
       [-0.51199567],
       [-1.8513022 ],
       [-2.36634669],
       [-0.90867609],
       [-1.47135629],
       [-0.08661267],
       [-0.15141935],
       [-0.79701399],
       [-1.12771743],
       [ 0.95583957],
       [-0.51916642],
       [ 1.30471802],
       [ 1.15364533],
       [ 0.6015342 ],
       [ 1.23045471]])
y=[37, 'M']

Creating Windows#

We will skip preprocessing steps for now, since it is not the aim of this example. Instead, we will directly create compute windows. We specify a mapping from genders ‘M’ and ‘F’ to integers, since this is required for decoding.

tuh_windows = create_fixed_length_windows(
    tuh,
    start_offset_samples=0,
    stop_offset_samples=None,
    window_size_samples=1000,
    window_stride_samples=1000,
    on_last_window="overlap",
    mapping={"M": 0, "F": 1},  # map non-digit targets
)
# store the number of windows required for loading later on
tuh_windows.set_description({"n_windows": [len(d) for d in tuh_windows.datasets]})

Exploring Windows#

Iterating through the dataset gives x as an ndarray with shape (n_channels x 1000), y as [age, gender], and ind. Let’s look at the last example again.

x, y, ind = tuh_windows[-1]
print(f"{x=}\n{y=}\n{ind=}")
x=array([[ 0.5625533 ,  0.1667017 ,  1.1376368 , ...,  0.80336064,
        -0.0759325 , -0.08388355],
       [ 0.1215528 ,  0.17057748,  0.6270015 , ..., -0.8585031 ,
         0.38844758,  0.45734063],
       [-1.9293324 , -0.0690375 , -1.185494  , ..., -0.15970044,
        -0.575385  ,  0.1744401 ],
       ...,
       [ 0.7467447 , -1.7557129 , -0.43545473, ...,  0.59196204,
        -0.87400156,  1.1536453 ],
       [ 1.293342  , -0.38169965,  1.6618726 , ..., -0.93147016,
        -1.5718849 ,  0.6015342 ],
       [ 1.5732402 ,  0.0705716 ,  1.3267263 , ..., -1.3382721 ,
         1.6085765 ,  1.2304547 ]], shape=(21, 1000), dtype=float32)
y=[37, 0]
ind=[3, 2600, 3600]

DataLoader for Model Training#

We give the dataset to a pytorch DataLoader, such that it can be used for model training.

dl = DataLoader(
    dataset=tuh_windows,
    batch_size=4,
)

Exploring DataLoader#

When iterating through the DataLoader, we get batch_X as a tensor with shape (4 x n_channels x 1000), batch_y as [tensor([4 x age of subject]), tensor([4 x gender of subject])], and batch_ind. To view the last example, simply iterate through the DataLoader:

for batch_X, batch_y, batch_ind in dl:
    pass

print(f"{batch_X=}\n{batch_y=}\n{batch_ind=}")
batch_X=tensor([[[ 3.4255e-01,  3.9813e-01,  4.3842e-01,  ...,  6.8848e-01,
          -6.8627e-01, -1.6076e-01],
         [-1.4676e-01, -2.7259e+00,  5.8164e-01,  ..., -8.7323e-02,
          -3.8489e-01,  1.4714e+00],
         [-6.7458e-01, -1.7280e-01, -8.8024e-01,  ...,  4.2146e-01,
           3.9975e-01, -1.9645e-01],
         ...,
         [-7.9086e-01,  5.1349e-01, -1.0982e+00,  ...,  3.1622e-01,
          -1.3991e+00,  4.4434e-01],
         [ 7.3869e-01, -2.7542e-01, -1.2387e+00,  ..., -9.4483e-01,
           1.2540e+00,  1.0914e+00],
         [ 1.6510e-01,  3.4803e-01,  6.9684e-02,  ..., -2.4324e-01,
           1.1410e+00, -1.2149e+00]],

        [[-3.0154e-01, -9.2984e-01,  6.4848e-01,  ..., -4.6284e-01,
          -6.6643e-02,  1.1902e+00],
         [-4.1180e-01, -6.9959e-01,  1.6393e-01,  ..., -4.3973e-01,
          -1.7124e-01, -6.5156e-01],
         [-2.0676e+00,  1.4021e+00, -8.8960e-02,  ..., -1.2859e-03,
           6.0182e-01,  2.0245e+00],
         ...,
         [-1.0774e+00,  4.3456e-01, -1.6407e-01,  ...,  9.0579e-01,
           6.4514e-01, -9.6780e-01],
         [-1.0332e+00, -6.9702e-01, -1.1782e+00,  ...,  1.8425e-01,
           1.4251e-03,  4.6951e-01],
         [ 2.5924e-01,  2.1697e-01, -1.1398e+00,  ...,  4.8916e-02,
          -1.3878e+00, -5.0575e-01]],

        [[ 1.4122e+00,  5.2889e-01,  9.3042e-01,  ...,  1.0026e+00,
          -8.4910e-02,  6.3180e-01],
         [ 7.4972e-01,  5.0729e-01, -9.0348e-01,  ...,  9.4041e-03,
          -9.9262e-01, -2.5424e+00],
         [-1.1751e-01,  5.6003e-02,  1.1174e-01,  ..., -1.0769e+00,
          -1.1123e+00,  3.4882e-01],
         ...,
         [-6.1406e-01, -1.2389e+00,  2.2630e+00,  ...,  2.1672e-01,
           1.6545e+00, -3.1211e-01],
         [-1.4842e-01, -3.6253e-01, -1.8248e-01,  ...,  5.6481e-01,
          -7.1054e-01,  4.7081e-01],
         [-8.8762e-01, -6.0361e-01, -4.0231e-01,  ..., -1.0109e-01,
           1.3751e+00, -1.6027e-01]],

        [[ 5.6255e-01,  1.6670e-01,  1.1376e+00,  ...,  8.0336e-01,
          -7.5933e-02, -8.3884e-02],
         [ 1.2155e-01,  1.7058e-01,  6.2700e-01,  ..., -8.5850e-01,
           3.8845e-01,  4.5734e-01],
         [-1.9293e+00, -6.9038e-02, -1.1855e+00,  ..., -1.5970e-01,
          -5.7538e-01,  1.7444e-01],
         ...,
         [ 7.4674e-01, -1.7557e+00, -4.3545e-01,  ...,  5.9196e-01,
          -8.7400e-01,  1.1536e+00],
         [ 1.2933e+00, -3.8170e-01,  1.6619e+00,  ..., -9.3147e-01,
          -1.5719e+00,  6.0153e-01],
         [ 1.5732e+00,  7.0572e-02,  1.3267e+00,  ..., -1.3383e+00,
           1.6086e+00,  1.2305e+00]]])
batch_y=[tensor([37, 37, 37, 37]), tensor([0, 0, 0, 0])]
batch_ind=[tensor([0, 1, 2, 3]), tensor([   0, 1000, 2000, 2600]), tensor([1000, 2000, 3000, 3600])]

Numeric targets without a mapping#

A mapping is unnecessary when the description already contains numeric targets. Here we encode the corpus’s gender labels in a new description column, and reuse the same recordings with age and gender_code as targets. This leaves the original dataset and its description unchanged. The target order follows target_name, not the description column order.

numeric_description = tuh.description.assign(
    gender_code=tuh.description["gender"].map({"M": 0, "F": 1})
)
numeric_tuh: BaseConcatDataset[RawDataset] = BaseConcatDataset(
    [
        RawDataset(ds.raw, description, target_name=("age", "gender_code"))
        for ds, (_, description) in zip(tuh.datasets, numeric_description.iterrows())
    ]
)
numeric_windows = create_fixed_length_windows(
    numeric_tuh,
    window_size_samples=1000,
    window_stride_samples=1000,
    on_last_window="overlap",
)
print(f"Target without a mapping: {numeric_windows[0][1]}")
Target without a mapping: [0, 0]

Choosing the batch target layout#

Numeric list targets still collate into one tensor per target, as above. For a model expecting a single (batch_size, n_targets) tensor, convert each target list to a NumPy array before collation. This is useful, for example, with multiple continuous regression targets; choose the target dtype and loss to match the task. Encoding gender as a number does not make it a continuous regression target.

numeric_windows.target_transform = np.asarray
_, matrix_y, _ = next(iter(DataLoader(numeric_windows, batch_size=4)))
print(f"Matrix target shape: {tuple(matrix_y.shape)}")
print(matrix_y)
assert matrix_y.shape == (4, 2)
Matrix target shape: (4, 2)
tensor([[0, 0],
        [0, 0],
        [0, 0],
        [0, 0]])

Changing the prediction target#

Use set_target() to switch to a different target without loading the recordings or creating the windows again. For example, select the numeric class label we added to the description. Clear the array transform from the multi-target example so indexing returns a scalar target again.

numeric_windows.target_transform = None
numeric_windows.set_target("gender_code")
print(f"Classification target: {numeric_windows[-1][1]}")
Classification target: 0

The same windows can instead return age as a regression target. Selecting a column does not choose a model, loss, or dtype: here float converts the returned target to a floating-point value. This transform does not change the stored metadata.

numeric_windows.set_target("age")
numeric_windows.target_transform = float
print(f"Regression target: {numeric_windows[-1][1]}")
Regression target: 37.0

Recording descriptions and window metadata#

description has one row per recording; get_metadata() has one row per window, with recording descriptions repeated alongside the window information. set_target first looks for the column in each window dataset’s metadata, then in its description. A description value such as age is broadcast to all windows of that recording. Editing the DataFrame returned by get_metadata() alone does not update the targets returned by dataset indexing.

description = numeric_windows.description
print(description[["age", "gender_code"]])
metadata = numeric_windows.get_metadata()
print(metadata[["age", "gender_code", "target", "i_window_in_trial"]])
   age  gender_code
0    0            0
1   53            1
2   39            0
3   37            0
   age  gender_code  target  i_window_in_trial
0    0            0       0                  0
1    0            0       0                  1
2    0            0       0                  2
3    0            0       0                  3
0   53            1      53                  0
1   53            1      53                  1
2   53            1      53                  2
3   53            1      53                  3
0   39            0      39                  0
1   39            0      39                  1
2   39            0      39                  2
3   39            0      39                  3
0   37            0      37                  0
1   37            0      37                  1
2   37            0      37                  2
3   37            0      37                  3

Selecting a subset of recordings#

Keep only recordings with gender_code == 1, independently of the current prediction target. To keep several values, use isin instead of eq. The row positions passed to split refer to recordings, not individual windows. This selection keeps all windows from each selected recording; it does not filter event classes that vary within a recording. See Split Dataset Example for other recording-level splits.

selected_ids = description.index[description["gender_code"].eq(1)].tolist()
selected_windows = numeric_windows.split({"selected": selected_ids})["selected"]
print(selected_windows.description[["age", "gender_code"]])
print(f"Selected {len(selected_windows)} of {len(numeric_windows)} windows")
   age  gender_code
0   53            1
Selected 4 of 16 windows

split reuses the underlying datasets rather than copying the signals. Later calls to set_target also affect splits sharing those datasets. Here we finish changing targets before constructing the subset.

Total running time of the script: (0 minutes 0.057 seconds)

Gallery generated by Sphinx-Gallery