Updating BIDS datasets

When working with electrophysiological data in the BIDS format, we usually do not have all the metadata stored in the Raw mne-python object. We can update the BIDS sidecar files via the update_sidecar_json function.

In this tutorial, we show how update_sidecar_json can be used to update and modify BIDS-formatted data.

# Authors: The MNE-BIDS developers
# SPDX-License-Identifier: BSD-3-Clause

Imports

We are importing everything we need for this example:

from mne.datasets import somato

from mne_bids import (
    find_matching_paths,
    make_report,
    print_dir_tree,
    read_raw_bids,
    update_sidecar_json,
)

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

Using default location ~/mne_data for somato...

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)

# We can generate a report of the existing dataset
print(make_report(bids_root))

|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
Summarizing participants.tsv /home/circleci/mne_data/MNE-somato-data/participants.tsv...
Summarizing scans.tsv files [PosixPath('/home/circleci/mne_data/MNE-somato-data/sub-01/sub-01_scans.tsv')]...
The participant template found: comprised of 1 male and 0 female participants;
handedness were all unknown;
ages all unknown
 The MNE-somato-data-bids dataset was created by Lauri Parkkonen and conforms to
BIDS version 1.2.0. This report was generated with MNE-BIDS
(https://doi.org/10.21105/joss.01896). The dataset consists of 1 participants
(comprised of 1 male and 0 female participants; handedness were all unknown;
ages all unknown) . Data was recorded using an MEG system (Elekta) 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).

Update the sidecar JSON dataset contents

We can use MNE-BIDS to update all sidecar files for a matching BIDSPath object. We then pass in a dictionary (or JSON file) to update all matching metadata fields within the BIDS dataset.

# Search for all matching BIDSPaths in the root directory
bids_root = somato.data_path()
suffix = "meg"
extension = ".fif"

bids_paths = find_matching_paths(bids_root, suffixes=suffix, extensions=extension)
# We can now retrieve a list of all MEG-related files in the dataset:
print(bids_paths)

# Define a sidecar update as a dictionary
entries = {
    "PowerLineFrequency": 60,
    "Manufacturer": "MEGIN",
    "InstitutionName": "Martinos Center",
}

# Note: ``update_sidecar_json`` will perform essentially a
# dictionary update to your sidecar json file, so be absolutely sure
# that the ``entries`` are defined with the proper fields specified
# by BIDS. For example, if you are updating the ``coordsystem.json``
# file, then you don't want to include ``PowerLineFrequency`` in
# ``entries``.
#
# Now update all sidecar fields according to our updating dictionary
bids_path = bids_paths[0]
sidecar_path = bids_path.copy().update(extension=".json")
update_sidecar_json(bids_path=sidecar_path, entries=entries)

[BIDSPath(
root: /home/circleci/mne_data/MNE-somato-data
datatype: meg
basename: sub-01_task-somato_meg.fif)]
Writing '/home/circleci/mne_data/MNE-somato-data/sub-01/meg/sub-01_task-somato_meg.json'...

Read the updated dataset

# new line frequency is now 60 Hz
raw = read_raw_bids(bids_path=bids_path)
print(raw.info["line_freq"])

Opening raw data file /home/circleci/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 /home/circleci/mne_data/MNE-somato-data/sub-01/meg/sub-01_task-somato_events.tsv.
Reading channel info from /home/circleci/mne_data/MNE-somato-data/sub-01/meg/sub-01_task-somato_channels.tsv.
Not fully anonymizing info - keeping his_id, sex, and hand info
60.0

Generate a new report based on the updated metadata.

# The manufacturer was changed to ``MEGIN``
print(make_report(bids_root))

Summarizing participants.tsv /home/circleci/mne_data/MNE-somato-data/participants.tsv...
Summarizing scans.tsv files [PosixPath('/home/circleci/mne_data/MNE-somato-data/sub-01/sub-01_scans.tsv')]...
The participant template found: comprised of 1 male and 0 female participants;
handedness were all unknown;
ages all unknown
 The MNE-somato-data-bids dataset was created by Lauri Parkkonen and conforms to
BIDS version 1.2.0. This report was generated with MNE-BIDS
(https://doi.org/10.21105/joss.01896). The dataset consists of 1 participants
(comprised of 1 male and 0 female participants; handedness were all unknown;
ages all unknown) . Data was recorded using an MEG system (MEGIN) sampled at
300.31 Hz with line noise at 60 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).

We can revert the changes by updating the sidecar again.

# update the sidecar data to have a new PowerLineFrequency
entries["Manufacturer"] = "Elekta"
entries["PowerLineFrequency"] = 50
update_sidecar_json(bids_path=sidecar_path, entries=entries)

Writing '/home/circleci/mne_data/MNE-somato-data/sub-01/meg/sub-01_task-somato_meg.json'...

Now let us inspect the dataset again by generating the report again. Now that update_sidecar_json was called, the metadata will be updated.

# The power line frequency should now change back to 50 Hz
raw = read_raw_bids(bids_path=bids_path)
print(raw.info["line_freq"])

# Generate the report with updated fields
print(make_report(bids_root))

Opening raw data file /home/circleci/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 /home/circleci/mne_data/MNE-somato-data/sub-01/meg/sub-01_task-somato_events.tsv.
Reading channel info from /home/circleci/mne_data/MNE-somato-data/sub-01/meg/sub-01_task-somato_channels.tsv.
Not fully anonymizing info - keeping his_id, sex, and hand info
50.0
Summarizing participants.tsv /home/circleci/mne_data/MNE-somato-data/participants.tsv...
Summarizing scans.tsv files [PosixPath('/home/circleci/mne_data/MNE-somato-data/sub-01/sub-01_scans.tsv')]...
The participant template found: comprised of 1 male and 0 female participants;
handedness were all unknown;
ages all unknown
 The MNE-somato-data-bids dataset was created by Lauri Parkkonen and conforms to
BIDS version 1.2.0. This report was generated with MNE-BIDS
(https://doi.org/10.21105/joss.01896). The dataset consists of 1 participants
(comprised of 1 male and 0 female participants; handedness were all unknown;
ages all unknown) . Data was recorded using an MEG system (Elekta) 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).