12. 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: Adam Li <adam2392@gmail.com>
#          mne-bids developers
#
# License: BSD-3-Clause

Imports#

We are importing everything we need for this example:

from mne.datasets import somato

from mne_bids import (
    read_raw_bids,
    find_matching_paths,
    print_dir_tree,
    make_report,
    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.

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 C:\Users\stefan\mne_data\MNE-somato-data\participants.tsv...
Summarizing scans.tsv files [WindowsPath('C:/Users/stefan/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: C:/Users/stefan/mne_data/MNE-somato-data
datatype: meg
basename: sub-01_task-somato_meg.fif)]
Writing 'C:\Users\stefan\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 C:\Users\stefan\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 C:\Users\stefan\mne_data\MNE-somato-data\sub-01\meg\sub-01_task-somato_events.tsv.
Reading channel info from C:\Users\stefan\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 C:\Users\stefan\mne_data\MNE-somato-data\participants.tsv...
Summarizing scans.tsv files [WindowsPath('C:/Users/stefan/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 'C:\Users\stefan\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 C:\Users\stefan\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 C:\Users\stefan\mne_data\MNE-somato-data\sub-01\meg\sub-01_task-somato_events.tsv.
Reading channel info from C:\Users\stefan\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 C:\Users\stefan\mne_data\MNE-somato-data\participants.tsv...
Summarizing scans.tsv files [WindowsPath('C:/Users/stefan/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).

Total running time of the script: (0 minutes 0.771 seconds)

Gallery generated by Sphinx-Gallery