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
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
Create a BIDS path using
mne_bids
Convert the MEG file into a BIDS structure using
mne_bids.write_raw_bids()
Extract the
channels.tsv
from the BIDS pathSave it in the output directory
Update channels.tsv with bad channels detected by the App
Convert the
channels.tsv
into apd.DataFrame
Update its column “status” of the dataframe with “bad” for the channels detected as bad
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 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']
andinfo['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
Create a BIDS path using
mne_bids
Get all the info needed to create the events file
Convert the MEG file into a BIDS structure using
mne_bids.write_raw_bids()
and specify events_data and events_idExtract the
events.tsv
from the BIDS pathSave 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.