01. Read BIDS datasets

When working with electrophysiological data in the BIDS format, we usually have varying data types, which can be loaded via the read_raw_bids function.

• MEG

• EEG (scalp electrodes)

• iEEG (ECoG and SEEG)

• the anatomical MRI scan of a study participant

In this tutorial, we show how read_raw_bids can be used to load and inspect BIDS-formatted data.

# Authors: Adam Li <adam2392@gmail.com>
#          Richard Höchenberger <richard.hoechenberger@gmail.com>
#
# License: BSD (3-clause)

Imports

We are importing everything we need for this example:

from mne.datasets import somato

from mne_bids import BIDSPath, read_raw_bids, print_dir_tree, make_report

We will be using the MNE somato data, which is already stored in BIDS format. For more information, you can check out the respective example.

Download the somato BIDS dataset

Download the data if it hasn’t been downloaded already, and return the path to the download directory. This directory is the so-called root of this BIDS dataset.

bids_root = somato.data_path()

Explore the dataset contents

We can use MNE-BIDS to print a tree of all included files and folders. We pass the max_depth parameter to mne_bids.print_dir_tree to the output to three levels of folders, for better readability in this example.

print_dir_tree(bids_root, max_depth=3)

Out:

|MNE-somato-data/
|--- CHANGES
|--- README
|--- dataset_description.json
|--- participants.json
|--- participants.tsv
|--- code/
|------ README
|------ convert_somato_data.py
|--- derivatives/
|------ freesurfer/
|--------- subjects/
|------ sub-01/
|--------- sub-01_task-somato-fwd.fif
|--- sub-01/
|------ sub-01_scans.tsv
|------ anat/
|--------- sub-01_T1w.json
|--------- sub-01_T1w.nii.gz
|------ meg/
|--------- sub-01_coordsystem.json
|--------- sub-01_task-somato_channels.tsv
|--------- sub-01_task-somato_events.tsv
|--------- sub-01_task-somato_meg.fif
|--------- sub-01_task-somato_meg.json

We can even ask MNE-BIDS to produce a human-readbale summary report on the dataset contents.

print(make_report(bids_root))

Out:

Summarizing participants.tsv /Users/hoechenberger/mne_data/MNE-somato-data/participants.tsv...
Summarizing scans.tsv files [PosixPath('/Users/hoechenberger/mne_data/MNE-somato-data/sub-01/sub-01_scans.tsv')]...
The participant template found: comprised of 1 men and 0 women;
handedness were all unknown; ages all unknown
The MNE-somato-data-bids dataset was created with BIDS version 1.2.0 by Lauri
Parkkonen. This report was generated with MNE-BIDS
(https://doi.org/10.21105/joss.01896). The dataset consists of 1 participants
(comprised of 1 men and 0 women; handedness were all unknown; ages all unknown).
Data was recorded using a MEG system (Elekta manufacturer) sampled at 300.31 Hz
with line noise at 50 Hz. There was 1 scan in total. Recording durations ranged
from 897.08 to 897.08 seconds (mean = 897.08, std = 0.0), for a total of 897.08
seconds of data recorded over all scans. For each dataset, there were on average
316.0 (std = 0.0) recording channels per scan, out of which 316.0 (std = 0.0)
were used in analysis (0.0 +/- 0.0 were removed from analysis).

Now it’s time to get ready for reading some of the data! First, we need to create a mne_bids.BIDSPath, which is the working horse object of MNE-BIDS when it comes to file and folder operations.

For now, we’re interested only in the MEG data in the BIDS root directory of the somato dataset.

datatype = 'meg'
bids_path = BIDSPath(root=bids_root, datatype=datatype)

We can now retrieve a list of all MEG-related files in the dataset:

print(bids_path.match())

Out:

[BIDSPath(
root: /Users/hoechenberger/mne_data/MNE-somato-data
datatype: meg
basename: sub-01_task-somato_channels.tsv), BIDSPath(
root: /Users/hoechenberger/mne_data/MNE-somato-data
datatype: meg
basename: sub-01_task-somato_events.tsv), BIDSPath(
root: /Users/hoechenberger/mne_data/MNE-somato-data
datatype: meg
basename: sub-01_task-somato_meg.fif)]

The returned list contains BIDSpaths of 3 files: sub-01_task-somato_channels.tsv, sub-01_task-somato_events.tsv, and sub-01_task-somato_meg.fif. The first two are so-called sidecar files that contain information on the recording channels and experimental events, and the third one is the actual MEG data file.

Prepare reading the data

There is obviously only one subject (01) and one experimental task (somato). Let’s use this knowledge to create a new BIDSPath with all the information required to actually read the MEG data. We also need to pass a suffix, which is the last part of the filename just before the extension – 'channels' and 'events' for the two TSV files in our example, and 'meg' for MEG raw data. For MEG and EEG raw data, the suffix is identical to the datatype, so don’t let yourselve be confused here!

bids_root = somato.data_path()
datatype = 'meg'
subject = '01'
task = 'somato'
suffix = 'meg'

bids_path = BIDSPath(subject=subject, task=task, suffix=suffix,
                     datatype=datatype, root=bids_root)

Now let’s print the contents of bids_path.

print(bids_path)

Out:

/Users/hoechenberger/mne_data/MNE-somato-data/sub-01/meg/sub-01_task-somato_meg.fif

You probably noticed two things: Firstly, this looks like an ordinary string now, not like the more-or-less neatly formatted output we saw before. And secondly, that there’s suddenly a filename extension which we never specified anywhere!

The reason is that when you call print(bids_path), BIDSPath returns a string representation of BIDSPath.fpath, which looks different. If, instead, you simply typed bids_path (or print(repr(bids_path)), which is the same) into your Python console, you would get the nicely formatted output:

bids_path

Out:

BIDSPath(
root: /Users/hoechenberger/mne_data/MNE-somato-data
datatype: meg
basename: sub-01_task-somato_meg)

The root here is – you guessed it – the directory we passed via the root parameter: the “home” of our BIDS dataset. The datatype, again, is self-explanatory. The basename, on the other hand, is created automatically based on the suffix and BIDS entities we passed to BIDSPath: in our case, subject and task.

Note

There are many more supported entities, the most-commonly used among them probably being session. Please see our introduction to BIDSPath to learn more about entities, basename, and BIDSPath in general.

But what about that filename extension, now? BIDSPath.fpath, which – as you hopefully remember – is invoked when you run print(bids_path) – employs some heuristics to auto-detect some missing filename components. Omitting the filename extension in your script can make your code more portable. Note that, however, you can explicitly specify an extension too, by passing e.g. extension='.fif' to BIDSPath.

Read the data

Let’s read the data! It’s just a single line of code.

raw = read_raw_bids(bids_path=bids_path, verbose=False)

Out:

Opening raw data file /Users/hoechenberger/mne_data/MNE-somato-data/sub-01/meg/sub-01_task-somato_meg.fif...
    Range : 237600 ... 506999 =    791.189 ...  1688.266 secs
Ready.
Reading events from /Users/hoechenberger/mne_data/MNE-somato-data/sub-01/meg/sub-01_task-somato_events.tsv.
Reading channel info from /Users/hoechenberger/mne_data/MNE-somato-data/sub-01/meg/sub-01_task-somato_channels.tsv.
/Users/hoechenberger/Development/mne-bids/mne_bids/read.py:339: RuntimeWarning: The unit for channel(s) STI 001, STI 002, STI 003, STI 004, STI 005, STI 006, STI 014, STI 015, STI 016 has changed from V to NA.
  raw.set_channel_types(channel_type_dict)

Now we can inspect the raw object to check that it contains to correct metadata.

Basic subject metadata is here.

print(raw.info['subject_info'])

Out:

{'id': 175, 'sex': 1, 'participant_id': 'sub-01', 'age': 'n/a'}

Power line frequency is here.

print(raw.info['line_freq'])

Out:

50

Sampling frequency is here.

print(raw.info['sfreq'])

Out:

300.3074951171875

Events are now Annotations

print(raw.annotations)

Out:

<Annotations | 111 segments: somato_event1 (111)>

Plot the raw data.

raw.plot()

Out:

<MNEBrowseFigure size 977x1080 with 4 Axes>