bidscoin tutorial

If you have set up a special python environment for bidscoin, activate it. For example with conda activate bidscoin.

Table of content

• DEMO 1: using bidscoin data
  • Get the data.
  • Reorganize the DICOM data
  • Read DICOM metadata and initialize the mapping
  • Fieldmaps
  • bidsmap.yml
  • Run the conversion
  • Post-processing
  • Validate the results
  • Inspect file types we have not seen before
• DEMO 2: using the dcm2bids test data
  • Get the data
    • Option 1
    • Option 2
    • Option 3
  • Dataset description
  • Sort DICOMS
  • Collect DICOM info
  • Create the bidsmap
  • Run the conversion

DEMO 1: using bidscoin data

This is a massively reduced version of the original bidscoin tutorial. Please refer back to the original tutorial for more information.

There is also a video tutorial about it

Get the data.

bidscoin --download .
cd bidscointutorial

This is a small phantom dataset.

Note that in this dataset the raw folder contains the DICOM files, and the bids_ref folder contains the BIDS dataset you are supposed to get after conversion.

Reorganize the DICOM data

bidscoin has strict requirements on how the source DICOM data should be organized.

If some DICOM data is not properly organized, this can be done with the dicomsort command:

dicomsort raw/sub-002/ses-01/

You can also extract some specific DICOM metadata with the rawmapper command:

rawmapper raw -f "AcquisitionDate" "EchoTime"

Read DICOM metadata and initialize the mapping

bidsmapper raw bids

Opens a GUI to create a mapping to say how each DICOM file should be renamed:

• T1 scan acquisition label mprage
• task label is reward for the acq-mb8 scans
• task label is stop for the acq-mb3me3 scans

Fieldmaps

Add a search pattern to the IntendedFor field such that:

• the first fieldmap will select your reward runs,
• and the second fieldmap your stop.

Make sure that the dcm2bids command is correct in the Options tab.

Save it in bids/code/bidscoin/bidsmap.yaml.

bidsmap.yml

Note that this YAML file (Yet Another Markup Language). You can read a quick intro about this file format on the Turing-way jupyter book or a longer one here. If you are working with VS code you can install the YAML extension.

If you need to re-edit the bidsmap, you can relaunch the GUI with:

bidseditor bids -b bids/code/bidscoin/bidsmap.yaml

You can also edit the default bidsmap or create a new one to adapt it to the needs of your lab or your MRI center.

Run the conversion

bidscoiner raw bids -p 001 002

Post-processing

This data set has functional multi-echo data and bidscoins offers a way to combine them.

echocombine bids "func/*task-reward*echo-1*" -p 001 002
echocombine bids "func/*task-stop*echo-1*" -p 001 002

You will also need to manually edit some files:

• README
• dataset_description.json
• participants.json that contains details about each column of the participants.tsv file.

Validate the results

Use the BIDS validator.

Inspect file types we have not seen before

• scans.tsv
• .bidsignore

DEMO 2: using the dcm2bids test data

This part was adapted from the dcm2bids converter tutorial to reuse their demo data.

Get the data

Option 1

Download and unzip the data:

https://github.com/neurolabusc/dcm_qa_nih/archive/refs/heads/master.zip

Option 2

From the terminal:

wget -O dcm_qa_nih-master.zip https://github.com/neurolabusc/dcm_qa_nih/archive/refs/heads/master.zip
unzip dcm_qa_nih-master.zip -d sourcedata/
mv sourcedata/dcm_qa_nih-master sourcedata/dcm_qa_nih

Option 3

Clone the repository:

git clone https://github.com/neurolabusc/dcm_qa_nih/ sourcedata/dcm_qa_nih

Dataset description

The data you want to focus on are in the In folder.

You have data coming from a Siemens scanner and data coming from a General Electrics scanner.

Sort DICOMS

dicomsort sourcedata/dcm_qa_nih/In/20180918GE
dicomsort sourcedata/dcm_qa_nih/In/20180918Si

Let’s also rename the folders and add the the prefix sub-.

• 20180918GE -> sub-GE
• 20180918Si -> sub-Si

Collect DICOM info

rawmapper sourcedata/dcm_qa_nih/In -f "SeriesDescription"

You are mostly interested in those sequences:

• 004_In_DCM2NIIX_regression_test_20180918114023 003_In_EPI_PE=AP_2018091812123

  • SeriesDescription: “Axial EPI-FMRI (Interleaved I to S)*”
  • will become a functional file with the task label rest

• 004_In_EPI_PE=PA_2018091812123

Create the bidsmap

bidsmapper sourcedata/dcm_qa_nih/In raw

Run the conversion

bidscoiner sourcedata/dcm_qa_nih/In raw -p GE Si

---