Preparing EEG data¶

The next step in the pipeline is to prepare the EEG data for TRF analysis. This step performs three main tasks:

1. Converts the EEG data into NDVar objects used by the eelbrain package.
2. Matches each EEG epoch to its corresponding stimulus file.
3. Determines how to handle duration differences between EEG epochs and stimulus audio files.

EEG data files¶

You will use ns.trf.prepare_eeg(). The usage is similar to ns.trf.make_gammatone_predictors(): you can just pass the relevant settings directly as keyword arguments:

Here are the main arguments you may want to change or check:

• eeg_data_path: Path to the '.fif' EEG data files mentioned in the Getting Started section.

• metadata_path: Path to the metadata file mentioned in the Getting Started section.

• output_path: Directory where the prepared EEG data will be saved.

• stim_path: Path to the folder containing the stimulus audio files.

• metadata_filename_col: Name of the column in the metadata spreadsheet that contains the EEG data filenames.

• metadata_stim_col: Name of the column in the metadata spreadsheet that lists the stimulus filenames corresponding to the EEG epochs.

• channels_to_drop: List of EEG channels to remove from the data. In this example, the two mastoid electrodes are still included in the EEG files, so we drop them here.

• duration_mode: EEG epochs may be longer than the corresponding stimuli or the stimulus files may differ in duration. This argument specifies how to handle duration differences. Three options are currently available:

  • 'min': Truncate all EEG epochs and stimulus predictors within each EEG data file to the shortest stimulus duration in that file. For example, if one EEG file contains five epochs corresponding to five audio tracks, and the shortest track is 50 s, then all epochs and predictors from that file will be truncated to 50 s before TRF analysis.

  • 'fixed': Use a fixed duration for all epochs across all EEG data files. If duration_mode = 'fixed', you must also provide fixed_duration, which specifies the duration in seconds, for example, fixed_duration = 45. The fixed duration cannot be longer than the shortest stimulus duration in the dataset.

  • 'concat': See below.

  The duration_mode setting will truncate the EEG accordingly in the output files but won't affect the stimulus predictors. However, it stores information about how duration was handled. The downstream TRF code will use this information to truncate the predictors when fitting the models.

Again, paths can be relative or absolute. Relative paths are interpreted relative to the trf module folder inside the neuraspeech package.

Please check the output carefully for any warnings. The function will try to catch issues such as mismatches between the number of EEG epochs and the number of stimuli listed in the metadata file. Files with these issues will be skipped and will not be saved to the output directory. Fix any warnings or skipped files before moving on to the next step.

If you load one of the prepared EEG output files, you should see something like this. The file contains the metadata associated with the EEG recording, plus the stimulus file for each epoch (stim) and duration_mode. It also contains the EEG data itself as an eelbrain.NDVar object.

Using the configuration file¶

Again, you can also run ns.trf.prepare_eeg() by using the configuration file instead of keyword arugments:

Pro tips¶

1. Concatenate EEG and stimulus predictors¶

In the example above, all EEG epochs within each data file were trimmed to the minimum stimulus length before building the dataset. This approach is usually OK when stimuli have similar durations. However, it can lead to substantial data loss when stimulus lengths vary considerably, as illustrated in the left panel of the diagram below.

To avoid this issue, ns.trf.prepare_eeg() allows users to set duration_mode to 'concat'. In this mode, each EEG epoch is truncated only to the actual duration of its corresponding stimulus. The resulting EEG segments, together with their matching stimulus predictors, are then concatenated to form a single continuous track, as shown below:

To use this mode, do the following:

Note that you will also need to provide the path to the predictor set, as the predictors must be concatenated in the same way as the EEG data. The function will create a new predictor folder using the original predictor set name plus a '_concat' suffix (e.gg., 'acou_pred_set_concat') under the 'predictors' folder.

The concatenated predictors are named using the corresponding EEG filename before the '~' separator (e.g., 'sub-3000_04_ses-1_task-alice~gammatone-1.pickle'. When you open the corresponding EEG output file, you will see that it has only one row with the 'stim' column containing the EEG data filename, which will be used by the TRF code to locate the matching concatenated predictors.

2. When an epoch contains mulitple stimuli¶

So far, we have assumed that each EEG epoch corresponds to a single stimulus audio track, with semicolons (;) used as epoch separators when listing stimuli in the metadata file. However, ns.trf.prepare_eeg() can also handle cases in which one EEG epoch contains multiple stimulus tracks, as long as this is specified correctly in the metadata.

Specifically, use plus signs (+) to indicate the sequence of stimulus tracks within the original EEG epoch. If there are pauses or silence intervals between stimuli, and you know their exact durations in seconds, you can include those durations in the sequence as well. In many cases, this is necessary for re-epoching the EEG data correctly.

See the example metadata and schematic figure below for an illustration of how this works.

However, it is generally recommended to avoid this kind of re-epoching when possible, because it can introduce potential misalignment issues. If you want each EEG epoch to correspond to a single audio track, it is better to set this up directly in the experiment script before data collection.