Skip to content

BIDS conversion

Objective

Convert DICOMs to BIDS using Heudiconv (tutorial).

Key directories and files

  • <DATASET_ROOT>/dicom
  • <DATASET_ROOT>/bids
  • <DATASET_ROOT>/scratch/raw_dicom/doughnut.csv
  • heuristic.py

Procedure

  1. Ensure you have the appropriate HeuDiConv container listed in your global_configs.json
  2. Use nipoppy/workflow/bids_conv/run_bids_conv.py to run HeuDiConv stage_1 and stage_2.
  3. Run stage_1 to generate a list of available protocols from the DICOM header. These protocols are listed in <DATASET_ROOT>/bids/.heudiconv/<participant_id>/info/dicominfo_ses-<session_id>.tsv

Sample cmd: 

python nipoppy/workflow/bids_conv/run_bids_conv.py \
   --global_config <global_config_file> \
   --session_id <session_id> \
   --stage 1

Note

If participants have multiple sessions (or visits), these need to be converted separately and combined post-hoc to avoid Heudiconv errors.

  1. Copy+Rename sample_heuristic.py to heuristic.py in the code repo itself. Then edit ./heuristic.py to create a name-mapping (i.e. dictionary) for BIDS organization based on the list of available protocols.

Note

This file automatically gets copied into <DATASET_ROOT>/proc/heuristic.py to be seen by the Singularity container.

  1. Run stage_2 to convert the dicoms into BIDS format based on the mapping from heuristic.py. This updates <DATASET_ROOT>/scratch/raw_dicom/doughnut.csv (sets converted column to True).

Sample cmd: 

python nipoppy/workflow/bids_conv/run_bids_conv.py \
   --global_config <global_config_file> \
   --session_id <session_id> \
   --stage 2

Note

Once heuristic.py is finalized, only stage_2 needs to be run periodically unless new scan protocol is added.