BIDS introduction and BIDScoin demo
A good starting point to learn more about BIDS and BIDScoin is to watch this presentation from the OpenMR Benelux 2020 meeting (slides). The first 14 minutes Robert Oostenveld provides a general overview of the BIDS standard, after which Marcel Zwiers presents the design of BIDScoin and demonstrates hands-on how you can use it to convert a dataset to BIDS.
The tutorial below was written with the DCCN user in mind that wants to convert DICOM MRI data to BIDS. Nevertheless, the main principles also apply to other datasets, and you are encouraged to try out the assignments
1. Setting up the environment
Depending on how BIDScoin was installed, you may have to set your Python environment settings before you can run BIDScoin commands from your command-line interface / shell. In the DCCN compute cluster example below it is assumed that an environment module is used to load your Linux Anaconda Python installation and that BIDScoin is installed in a conda environment named “bidscoin”. Run or adjust these commands to your computer system if needed:
$ module add bidscoin # Load the DCCN bidscoin module with the PATH settings and Anaconda environment $ source activate /opt/bidscoin # Activate the Python virtual environment with the BIDScoin Python packages
Now you should be able to execute BIDScoin commands. Test this by running
bidscoin to get a general workflow overview. Can you generate a list of all BIDScoin tools? What about the plugins? Test the bidscoin installation and make sure everything is ok
2. Data preparation
Create a tutorial playground folder by executing these shell commands:
$ bidscoin --download . # Download the tutorial data (use a "." for the current folder or a pathname of choice to save it elsewhere) $ cd ./bidscointutorial # Go to the downloaded data (replace "." with the full pathname if your data was saved elsewhere)
bidscointutorial folder contains a
raw source-data folder and a
bids_ref reference BIDS folder, i.e. the intended end product of this tutorial. In the raw folder you will find these DICOM Series folders (aka “runs”):
bidscointutorial/raw/sub-001/ses-01/ ├─ 001-localizer_32ch-head A localizer scan that is not scientifically relevant and can be left out ├─ 002-AAHead_Scout_32ch-head A localizer scan that is not scientifically relevant and can be left out ├─ 007-t1_mprage_sag_ipat2_1p0iso An anatomical T1-weighted scan ├─ 047-cmrr_2p4iso_mb8_TR0700_SBRef A single-band reference scan of the subsequent multi-band fMRI scan ├─ 048-cmrr_2p4iso_mb8_TR0700 A multi-band fMRI scan ├─ 049-field_map_2p4iso The field-map "magnitude1" images (intended for the previous fMRI scan) ├─ 050-field_map_2p4iso The field-map phase difference image ├─ 059-cmrr_2p5iso_mb3me3_TR1500_SBRef A single-band reference scan of the subsequent multi-echo fMRI scan ├─ 060-cmrr_2p5iso_mb3me3_TR1500 A multi-band multi-echo fMRI scan ├─ 061-field_map_2p5iso Idem, the field-map "magnitude1" images (intended for the previous fMRI scan) └─ 062-field_map_2p5iso Idem, the field-map phase difference image
Let’s begin with inspecting this new raw data collection:
Are the DICOM files for all the
bids/sub-*folders organized in series-subfolders (e.g.
sub-001/ses-01/003-T1MPRAGE/0001.dcmetc)? Use dicomsort if this is not the case (hint: it’s not the case). A help text for all BIDScoin tools is available by running the tool with the
Use the rawmapper command to print out the values of the “EchoTime”, “PatientSex” and “AcquisitionDate” DICOM fields (hint: use
-f) of the fMRI series in the
rawfolder (hint: use
-w). You should find this result (NB: unfortunately in this tutorial sub-001 and sub-002 are identical phantoms):
subid sesid seriesname EchoTime PatientSex AcquisitionDate sub-001 ses-01 047-cmrr_2p4iso_mb8_TR0700_SBRef 39 O 20200428 sub-002 ses-01 047-cmrr_2p4iso_mb8_TR0700_SBRef 39 O 20200428
3. BIDS mapping
Now we can make a study bidsmap, i.e. the mapping from DICOM source-files to BIDS target-files. To that end, scan all folders in the raw data collection by running the bidsmapper command:
$ bidsmapper raw bids
We only have one session per subject, so in the main GUI that appears (when all raw data has been scanned), remove the session label (and note how the output names simplify, omitting the session subfolders and labels)
Edit the task and acquisition labels of the functional scans into something more readable, e.g.
mb3me3scans. Also make the name of the T1 scan more user friendly, e.g. by naming the acquisition label simply
Make the fieldmap scans more user friendly, e.g. by naming the acquisition label simply
acq-2p5iso, and add a search pattern to the
IntendedForfield such that the first field map will select your
Rewardruns and the second field map your
Stopruns (see the bidseditor field map notes for more details)
When all done, go to the
Optionstab and change the
dcm2niixsettings to get non-zipped NIfTI output data (i.e.
*.nii.gz). Test the tool to see if it can run and, as a final step, save your bidsmap. You can always go back later to change any of your edits by running the bidseditor command line tool directly. Try that.
4. BIDS coining
The next step, converting the source data into a BIDS collection, is very simple to do (and can be repeated whenever new data has come in). To do this run the bidscoiner command-line tool (note that the input is the same as for the bidsmapper):
$ bidscoiner raw bids
bids/code/bidscoin/bidscoiner.log(the complete terminal output) and
bids/code/bidscoin/bidscoiner.errors(the summary that is also printed at the end) files for any errors or warnings. You shouldn’t have any :-)
Compare the results in your
bids/sub-*subject folders with the in
bids_refreference result. Are the file and folder names the same (don’t worry about missing individual echo images, they are combined/generated as described below)? Also check the json sidecar files of the field maps. Do they have the right
What happens if you re-run the
bidscoinercommand? Are the same subjects processed again? Delete the
bids/sub-001folder and re-run the
bidscoinercommand to recreate
5. Finishing up
Now that you have converted the data to BIDS, you still need to do work to make it fully ready for data analysis and sharing. For instance:
Combine the echos using the echocombine tool (see
echocombine --helpexamples), such that the individual echo images are replaced by the echo-combined image
Deface the anatomical scans of
sub-001using the deface tool. This will take a while, but will obviously not work well for our phantom dataset. Therefore store the ‘defaced’ output in the
derivativesfolder (instead of e.g. overwriting the existing images)
Generate a QC report of the anatomical scans using the slicereport tool and open the
bids/derivatives/slicereport/index.htmlfile in your browser.
bids/participants.tsvfile and decide if it is ok.
READMEfiles in your
As a final step, run the bids-validator on your
bidscointutorial/bidsfolder. Are you completely ready now to share this dataset?