BIDS and autobids - Getting Started

Tutorials
,
#1

BIDS & autobids

What is BIDS and why should I use it?

BIDS is a simple and intuitive way to organize and describe your neuroimaging and behavioral data.

By using this standard you will benefit in the following ways:

  • It will be easy for another researcher to work on your data. By using BIDS you will save time trying to understand and reuse data acquired by a graduate student or postdoc that has already left the lab.
  • There is a growing number of data analysis software packages that can understand data organized according to BIDS.
  • Databases such as OpenNeuro.org and others will accept and export datasets organized according to BIDS. If you ever plan to share your data publicly (nowadays some journals require this) you can speed up the curation process by using BIDS.
  • There are validation tools (also available online) that can check your dataset integrity and let you easily spot missing values.

How do I get my data in BIDS?

The BIDS starter kit is a good introduction on how to BIDS-ify your data:

At the CFMM you also have the option to get automated BIDS conversion of your data.

Autobids is a platform for automated download, standardization, and post-processing of neuroimaging data using the BIDS standard. Autobids uses heudiconv for its back-end conversion process.

How can I use CFMM autobids?

Researchers currently or planning on collecting data using the Centre for Functional and Metabolic Mapping (CFMM) 3T or 7T scanners can request CFMM autobids automated BIDS conversion of their data. Under this option, dicom data from every scan for autobids-registered studies will be automatically converted to BIDS format every night, using Compute Canada resources. Following BIDS conversion, users will receive an email including a link to their data which can be downloaded to any computer or server using the Globus file transfer service.

Data acquired on the 7T scanner will also have CFMM standard 7T corrections applied. Please contact Suzanne (switt4 -AT- uwo.ca) or Ali (alik - AT - robarts.ca) if you want to add any of your own additional post-processing scripts to your BIDS data.

Steps for requesting CFMM autobids conversion

  1. Complete the ‘New study request’ form.

  2. Have the PI (or lab manager) add ‘bidsdump’ as an authorized user for the study’s data on the CFMM DICOM server. A step-by-step guide can be found here.

  3. Sign up for a Globus account and download Globus Connect Personal.

Can I also have autobids deface my data?

Yes! We now can enable automated defacing of your structural T1w scans. Please ask Suzanne to enable this option.

Guide to autobids output

The output directory for autobids will always be called ‘bids’ and always have the same format in line with the BIDS standard. Do not change anything about the structure of the bids directory.

Each subject’s data is contained with a single directory (with sessions included as sub-directories of the subject directory). Structural scans are saved in the ‘anat’ directory, functional scans in ‘func’, diffusion scans in ‘dwi’, and fieldmaps in ‘fmap’.

Each image file (.nii.gz) has a corresponding .json file, which includes relevant details about the scanning parameters (e.g., information taken from the DICOM header file). Functional runs with more than one volume will also have an events.tsv file, where information about each stimulus (e.g., onsets, durations, parametric factors, etc.) can be entered. Please see the BIDS specification for task event files to read about how to fill in the necessary details.

Each study also is associated with at least two additional .json files: [dataset_description.json][13] and a task-TASKNAME-bold.json for each individual task collected during the study. The task-TASKNAME-bold.json files contain the scanning parameters for that specific task as read in from the DICOM header. Each study also has one [participants.tsv][14] file associated with it, which is where relevant details (e.g., participant_id, age, sex, experiment group, etc.) about each subject are included.

Additionally, a tarball file containing all of the DICOM data for a given subject/session is saved in the ‘sourcedata’ directory.

Tips for successful autobids conversion the first time

Autobids conversion relies heavily on having a consistent naming scheme for both the patient/subject IDs and MR sequence/series IDs as input into the CFMM DICOM server. Every subject collected in a single study must use the exact same naming scheme.

Before having the data uploaded to the CFMM DICOM server:

  • Adopt a consistent naming convention for both the MRI sequence/series names and the patient/subject IDs.

    • Capitalization matters! (‘This’ is not the same as ‘THIS’ is not the same as ‘this’.)

    • Punctuation matters! (‘sub_001’ is not the same as ‘sub.001’ is not the same as ‘sub001’.)

  • If the study involves subjects returning for multiple visits, make sure that the patient/subject ID has some session number identifier.

    • Subject ID with one session: 20190306_SubjectName

    • Subject ID with multiple sessions: 20190306_SubjectName_SessionNumber

  • If the study involves the collection of different tasks (or task and rest), make sure that the series/sequence name contains some information about what task was run. (It is not necessary to include a run number if the same task is run multiple times in a single scanning session.)

Troubleshooting

Most problems that occur when using autobids are due to inconsistent naming of either the patient/subject IDs or MR sequence/series names. The best way to avoid mistakes is to make sure that everything is named consistently the first time around.

  1. I scanned a subject yesterday, but I still have not received an email with the Globus link to download my data 24 hours later.

    • Check the Globus link from a previous BIDS conversion to see if the data are in your study’s bids folder. It is possible that the email just did not get sent.

    • Check that the scans are on the CFMM DICOM server.

    • Check that the patient/subject ID matches that of the other subjects in the study (e.g., is there an extra ‘_’ where there shouldn’t be?). Please note that due to recent software upgrades, it is no longer possible for the MR-techs to correct mistakes in the CFMM DICOM server. Contact Suzanne Witt (switt4 -at- uwo -dot- ca) to discuss options.

    • If the scans are on the CFMM DICOM server and the patient/subject ID is correct, please contact Suzanne Witt (switt4 -at- uwo -dot- ca) to let her know that you are missing a subject (again, provide scan date and PI^StudyName). Occasionally, autobids can fail to pick up a new scan.

  2. I noticed that some of the scans I ran are missing from the subject’s BIDS folder

    • Check that the sequence/series IDs of the missing scans matches those of the same scans run for another subject in your study (e.g., is the task identified as ‘tap’ instead of ‘Tap’?). Mistakes in the sequence/series name will need to be corrected by you after autobids conversion. As with subject/patient ID errors, it is no longer possible for the MR-techs to correct mistakes in the CFMM DICOM server.

Additional information

For additional information, please contact either Suzanne T. Witt (switt4 -at- uwo -dot- ca) or Ali Khan (alik -at- robarts -dot- ca).