Note
Go to the end to download the full example code.
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.
Using default location ~/mne_data for somato...
0%| | 0.00/611M [00:00<?, ?B/s]
0%| | 179k/611M [00:00<05:53, 1.73MB/s]
0%|▏ | 2.28M/611M [00:00<00:47, 12.9MB/s]
2%|▌ | 10.0M/611M [00:00<00:14, 42.0MB/s]
3%|█ | 17.8M/611M [00:00<00:10, 56.0MB/s]
4%|█▌ | 25.8M/611M [00:00<00:09, 64.8MB/s]
6%|██ | 33.9M/611M [00:00<00:08, 70.2MB/s]
7%|██▌ | 42.0M/611M [00:00<00:07, 73.8MB/s]
8%|███ | 50.1M/611M [00:00<00:07, 76.1MB/s]
10%|███▌ | 58.1M/611M [00:00<00:07, 77.4MB/s]
11%|████ | 66.2M/611M [00:01<00:06, 78.5MB/s]
12%|████▋ | 74.3M/611M [00:01<00:06, 79.3MB/s]
13%|█████▏ | 82.4M/611M [00:01<00:06, 79.7MB/s]
15%|█████▋ | 90.5M/611M [00:01<00:06, 80.0MB/s]
16%|██████▏ | 98.5M/611M [00:01<00:06, 79.2MB/s]
17%|██████▊ | 106M/611M [00:01<00:06, 78.8MB/s]
19%|███████▎ | 114M/611M [00:01<00:06, 79.4MB/s]
20%|███████▊ | 123M/611M [00:01<00:06, 79.9MB/s]
21%|████████▎ | 131M/611M [00:01<00:05, 80.2MB/s]
23%|████████▊ | 139M/611M [00:01<00:05, 80.2MB/s]
24%|█████████▎ | 147M/611M [00:02<00:05, 80.0MB/s]
25%|█████████▉ | 155M/611M [00:02<00:05, 80.0MB/s]
27%|██████████▍ | 163M/611M [00:02<00:05, 80.1MB/s]
28%|██████████▉ | 171M/611M [00:02<00:05, 80.5MB/s]
29%|███████████▍ | 179M/611M [00:02<00:05, 80.3MB/s]
31%|███████████▉ | 187M/611M [00:02<00:05, 80.3MB/s]
32%|████████████▍ | 195M/611M [00:02<00:05, 80.5MB/s]
33%|████████████▉ | 203M/611M [00:02<00:05, 80.8MB/s]
35%|█████████████▍ | 211M/611M [00:02<00:04, 80.8MB/s]
36%|██████████████ | 219M/611M [00:02<00:04, 80.4MB/s]
37%|██████████████▌ | 227M/611M [00:03<00:04, 80.2MB/s]
39%|███████████████ | 235M/611M [00:03<00:04, 80.2MB/s]
40%|███████████████▌ | 244M/611M [00:03<00:04, 82.4MB/s]
41%|████████████████▏ | 253M/611M [00:03<00:04, 84.4MB/s]
43%|████████████████▋ | 262M/611M [00:03<00:04, 85.7MB/s]
44%|█████████████████▎ | 271M/611M [00:03<00:03, 86.5MB/s]
46%|█████████████████▊ | 280M/611M [00:03<00:03, 86.8MB/s]
47%|██████████████████▍ | 289M/611M [00:03<00:03, 87.5MB/s]
49%|██████████████████▉ | 297M/611M [00:03<00:03, 87.9MB/s]
50%|███████████████████▌ | 306M/611M [00:03<00:03, 88.0MB/s]
52%|████████████████████▏ | 315M/611M [00:04<00:03, 88.3MB/s]
53%|████████████████████▋ | 324M/611M [00:04<00:03, 88.4MB/s]
55%|█████████████████████▎ | 333M/611M [00:04<00:03, 88.4MB/s]
56%|█████████████████████▊ | 342M/611M [00:04<00:03, 88.4MB/s]
57%|██████████████████████▍ | 351M/611M [00:04<00:02, 88.3MB/s]
59%|██████████████████████▉ | 359M/611M [00:04<00:02, 88.3MB/s]
60%|███████████████████████▌ | 368M/611M [00:04<00:02, 88.4MB/s]
62%|████████████████████████ | 377M/611M [00:04<00:02, 88.6MB/s]
63%|████████████████████████▋ | 386M/611M [00:04<00:02, 88.6MB/s]
65%|█████████████████████████▏ | 395M/611M [00:04<00:02, 88.6MB/s]
66%|█████████████████████████▊ | 404M/611M [00:05<00:02, 88.6MB/s]
68%|██████████████████████████▎ | 413M/611M [00:05<00:02, 88.6MB/s]
69%|██████████████████████████▉ | 421M/611M [00:05<00:02, 85.8MB/s]
70%|███████████████████████████▍ | 430M/611M [00:05<00:02, 78.6MB/s]
72%|████████████████████████████ | 439M/611M [00:05<00:02, 80.4MB/s]
73%|████████████████████████████▌ | 447M/611M [00:05<00:01, 82.7MB/s]
75%|█████████████████████████████▏ | 456M/611M [00:05<00:01, 84.6MB/s]
76%|█████████████████████████████▋ | 465M/611M [00:05<00:01, 85.7MB/s]
78%|██████████████████████████████▎ | 474M/611M [00:05<00:01, 86.5MB/s]
79%|██████████████████████████████▊ | 483M/611M [00:05<00:01, 86.8MB/s]
81%|███████████████████████████████▍ | 492M/611M [00:06<00:01, 87.2MB/s]
82%|███████████████████████████████▉ | 500M/611M [00:06<00:01, 87.5MB/s]
83%|████████████████████████████████▌ | 509M/611M [00:06<00:01, 87.6MB/s]
85%|█████████████████████████████████ | 518M/611M [00:06<00:01, 87.7MB/s]
86%|█████████████████████████████████▋ | 527M/611M [00:06<00:00, 87.3MB/s]
88%|██████████████████████████████████▏ | 536M/611M [00:06<00:00, 86.9MB/s]
89%|██████████████████████████████████▊ | 544M/611M [00:06<00:00, 86.6MB/s]
91%|███████████████████████████████████▎ | 553M/611M [00:06<00:00, 86.6MB/s]
92%|███████████████████████████████████▊ | 562M/611M [00:06<00:00, 86.3MB/s]
93%|████████████████████████████████████▍ | 570M/611M [00:06<00:00, 86.1MB/s]
95%|████████████████████████████████████▉ | 579M/611M [00:07<00:00, 86.1MB/s]
96%|█████████████████████████████████████▌ | 587M/611M [00:07<00:00, 86.0MB/s]
98%|██████████████████████████████████████ | 596M/611M [00:07<00:00, 86.0MB/s]
99%|██████████████████████████████████████▌| 605M/611M [00:07<00:00, 85.7MB/s]
0%| | 0.00/611M [00:00<?, ?B/s]
100%|███████████████████████████████████████| 611M/611M [00:00<00:00, 3.86TB/s]
Download complete in 17s (582.2 MB)
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/runner/mne_data/MNE-somato-data/participants.tsv...
Summarizing scans.tsv files [PosixPath('/home/runner/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/runner/mne_data/MNE-somato-data
datatype: meg
basename: sub-01_task-somato_meg.fif)]
Writing '/home/runner/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/runner/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/runner/mne_data/MNE-somato-data/sub-01/meg/sub-01_task-somato_events.tsv.
Reading channel info from /home/runner/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/runner/mne_data/MNE-somato-data/participants.tsv...
Summarizing scans.tsv files [PosixPath('/home/runner/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/runner/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/runner/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/runner/mne_data/MNE-somato-data/sub-01/meg/sub-01_task-somato_events.tsv.
Reading channel info from /home/runner/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/runner/mne_data/MNE-somato-data/participants.tsv...
Summarizing scans.tsv files [PosixPath('/home/runner/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 17.661 seconds)