How to create a BIDS compliant channels.tsv and events.tsv files

As pointed out by Soichi during a datatype meeting (see Datatype meeting 22.04.2021), we don’t want an App that outputs a MEG file whose only difference from the input MEG file is the list of bad channels or the list of events.

This issue, regarding bad channels, was also discussed here Où stocker l'information "bad channels", and it was decided that the App that detects bad channels will only returns a BIDS-compliant channels.tsv and this file will be used in other Apps to populate the raw.info['bads'].

Channels.tsv

Steps to create a BIDS compliant channels.tsv

1. Create a BIDS path using mne_bids

2. Convert the MEG file into a BIDS structure using mne_bids.write_raw_bids()

3. Extract the channels.tsv from the BIDS path

4. Save it in the output directory

Update channels.tsv with bad channels detected by the App

1. Convert the channels.tsv into a pd.DataFrame

2. Update its column “status” of the dataframe with “bad” for the channels detected as bad

3. Save the updated dataframe in a .tsv file

Populate raw.info['bads'] with channels.tsv info

The output datatype of the App that detects bad channels is meg/fif-override (see https://brainlife.io/datatype/608195ce89df435fd26893c1), but as pointed out here Où stocker l'information "bad channels", MNE Python functions used the info stored in raw.info['bads']. So, we need to update raw.info['bads']with the info of channels.tsv. If raw.info['bads'] is not compliant with the info of channels.tsv, a warning is displayed to the user to tell him that, by default, only bad channels from channels.tsv are considered as bad: the info of his MEG file will be updated with those channels. The comparison between channels.tsv and raw.info['bads'] is performed at the beginning of each App.

Events.tsv

The events info is stored in raw.info['events'], but this info shouldn’t be manually changed, it is changed by the MNE Python function:

The only entries that should be manually changed by the user are info['bads'] and info['description']. All other entries should be considered read-only, though they can be modified by various MNE-Python functions or methods (which have safeguards to ensure all fields remain in sync).

So, we don’t populate raw.info['events'] with the info written in events.tsv.

Just like the channels.tsv file, events.tsv returned by app-get-events and app-resampling are BIDS compliant.

Steps to create a BIDS compliant events.tsv

1. Create a BIDS path using mne_bids

2. Get all the info needed to create the events file

   1. if we create fixed length events: we need to extract the event id

   2. if we extract existing events we use mne.read_events()

3. Convert the MEG file into a BIDS structure using mne_bids.write_raw_bids() and specify events_data and events_id

4. Extract the events.tsv from the BIDS path

5. Save it in the output directory

Extract the matrix of events from the events.tsv

To create epochs we use the MNE function mne.Epochs() that takes as parameters the raw file but also the matrix of events. So, we can’t give to this function the events.tsv directly, we need to extract the matrix of events from it.

The events.tsv contains the following info:

• onset of the epoch

• duration

• trial type

• value

• sample

(see https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/05-task-events.html)

The events matrix is a numpy.array of shape (n_events, 3):

• events time in sample

• value of trigger channel

• events id

Steps to create the events matrix:

# Compute the events matrix #
df_events = pd.read_csv(events_file, sep='\t')
            
# Extract relevant info from df_events
samples = df_events['sample'].values
event_id = df_events['value'].values

# Compute the values for events matrix 
events_time_in_sample = [raw.first_samp + sample for sample in samples]
values_of_trigger_channels = [0]*len(events_time_in_sample)

# Create a dataframe
df_events_matrix = pd.DataFrame([events_time_in_sample, values_of_trigger_channels, event_id])
df_events_matrix = df_events_matrix.transpose()

# Convert dataframe to numpy array
events_matrix = df_events_matrix.to_numpy()