Skip to content

BIDS conversion

Nipoppy docs are moving

Nipoppy is undergoing a major refactor to move from scripts to a command-line interface (CLI) and Python API. The new documentation website (work in progress) can be found at https://nipoppy.readthedocs.io/.

If you are using the (soon-to-be legacy) scripts from Nipoppy 0.1.0, this is still the correct place to be. But we encourage you to check out the new website!

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.