This is a collaborative space. In order to contribute, send an email to maximilien.chaumon@icm-institute.org
On any page, type the letter L on your keyboard to add a "Label" to the page, which will make search easier.

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

Owned by Aurore Bussalb (Unlicensed)
Last updated: Jun 17, 2021
3 min read

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 brainlife), 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 thanks to helper.py (see Create a helper.py file).

Jun 17, 2021

Is it a good idea to display this warning message? It can confused the users (they don’t have to know that channels info can be stored in raw.info.

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

  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 MEG 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()

May 21, 2021 This code works well on fixed length events but was not tested on data with existing events!!!!

 

Delete the BIDS folder created

To get BIDS compliant events.tsv and channels.tsv, we created a BIDS folder. When the Apps creating these files run on Brainlife, the BIDS folder, which is useless, is in the outputs files. Besides, its presence may be confusing for the App users:

So in main , we add the line:

rm -r bids

after running the app.