Making dcm2bids output filenames more informative while staying BIDS-compliant

,
1

Hello everyone,

I am new to fMRI analyses and would appreciate some help with using dcm2bids to prepare my data for fMRIPrep.

As a background, our scanning protocol includes:

  • Three task-based fMRI scans (AST, MT, SST; all with PA phase encoding)
  • One resting-state fMRI scan (PA)
  • One topup scan (AP) per task and for resting-state
  • Four DWI scans:
    • b0 (7 directions, PA)
    • b1k (40 directions, AP)
    • b2k (53 directions, AP)
    • b3k (66 directions, AP)

I am following the official dcm2bids tutorial and can run dcm2bids successfully. However, the resulting NIfTI filenames are not very informative. At a glance, it is difficult to see which file corresponds to which task or DWI acquisition without inspecting the JSON sidecars.

Below are examples of the generated filenames for functional scans, topups, and DWI data, respectively:

Func:

sub-1001_dir-PA_run-01_bold.json 
sub-1001_dir-PA_run-03_bold.json 
sub-1001_dir-PA_run-01_bold.nii.gz 
sub-1001_dir-PA_run-03_bold.nii.gz 
sub-1001_dir-PA_run-02_bold.json 
sub-1001_dir-PA_run-04_bold.json 
sub-1001_dir-PA_run-02_bold.nii.gz 
sub-1001_dir-PA_run-04_bold.nii.gz

topup:

sub-1001_dir-AP_run-01_epi.json 
sub-1001_dir-AP_run-03_epi.json 
sub-1001_dir-AP_run-01_epi.nii.gz 
sub-1001_dir-AP_run-03_epi.nii.gz 
sub-1001_dir-AP_run-02_epi.json 
sub-1001_dir-AP_run-04_epi.json 
sub-1001_dir-AP_run-02_epi.nii.gz 
sub-1001_dir-AP_run-04_epi.nii.gz

DWI:

sub-1001_b0.bval 
sub-1001_run-02_dwi.bval 
sub-1001_b0.bvec 
sub-1001_run-02_dwi.bvec 
sub-1001_b0.json sub-1001_run-02_dwi.json 
sub-1001_b0.nii.gz 
sub-1001_run-02_dwi.nii.gz 
sub-1001_run-01_dwi.bval 
sub-1001_run-03_dwi.bval 
sub-1001_run-01_dwi.bvec 
sub-1001_run-03_dwi.bvec 
sub-1001_run-01_dwi.json 
sub-1001_run-03_dwi.json 
sub-1001_run-01_dwi.nii.gz 
sub-1001_run-03_dwi.nii.gz

As far as I understand, the naming convention is controlled by the dcm2bids_config.json. Below is an excerpt of my configuration file (functional tasks, fieldmaps, and DWI):

{
  "descriptions": [
    {
      "id": "id_task-Rest",
      "datatype": "func",
      "suffix": "bold",
      "custom_entities": {
        "task": "Rest",
        "acq": "epfid2m4",
        "dir": "PA",
        "run": "Run{item:02d}"
      },
      "criteria": {
        "SeriesDescription": "rs-fMRI_mbep2d_bold_2mm_MB4_PA_Run1"
      },
      "sidecar_changes": {
        "TaskName": "Rest"
      }
    },
    {
      "id": "id_task-SST",
      "datatype": "func",
      "suffix": "bold",
      "custom_entities": {
        "task": "SST",
        "acq": "epfid2m4",
        "dir": "PA",
        "run": "Run{item:02d}"
      },
      "criteria": {
        "SeriesDescription": "fMRI_SST_mbep2d_bold_2mm_MB4_PA_Run1"
      },
      "sidecar_changes": {
        "TaskName": "SST"
      }
    },
    {
      "id": "id_task-MT",
      "datatype": "func",
      "suffix": "bold",
      "custom_entities": {
        "task": "MT",
        "acq": "epfid2m4",
        "dir": "PA",
        "run": "Run{item:02d}"
      },
      "criteria": {
        "SeriesDescription": "fMRI_MT_mbep2d_bold_2mm_MB4_PA_Run1"
      },
      "sidecar_changes": {
        "TaskName": "MT"
      }
    },
    {
      "id": "id_task-AST",
      "datatype": "func",
      "suffix": "bold",
      "custom_entities": {
        "task": "AST",
        "acq": "epfid2m4",
        "dir": "PA",
        "run": "Run{item:02d}"
      },
      "criteria": {
        "SeriesDescription": "fMRI_AST_mbep2d_bold_2mm_MB4_PA_Run1"
      },
      "sidecar_changes": {
        "TaskName": "AST"
      }
    },
    {
      "datatype": "fmap",
      "suffix": "epi",
      "criteria": {
        "SeriesDescription": "mbep2d_bold_2mm_MB4_topup_AP"
      },
      "sidecar_changes": {
        "intendedFor": ["id_task-Rest"]
      }
    },
    {
      "datatype": "fmap",
      "suffix": "epi",
      "criteria": {
        "SeriesDescription": "mbep2d_bold_2mm_MB4_SST_topup_AP"
      },
      "sidecar_changes": {
        "intendedFor": ["id_task-SST"]
      }
    },
    {
      "datatype": "fmap",
      "suffix": "epi",
      "criteria": {
        "SeriesDescription": "mbep2d_bold_2mm_MB4_MT_topup_AP"
      },
      "sidecar_changes": {
        "intendedFor": ["id_task-MT"]
      }
    },
    {
      "datatype": "fmap",
      "suffix": "epi",
      "criteria": {
        "SeriesDescription": "mbep2d_bold_2mm_MB4_AST_topup_AP"
      },
      "sidecar_changes": {
        "intendedFor": ["id_task-AST"]
      }
    },
    {
      "datatype": "dwi",
      "suffix": "dwi",
      "criteria": {
        "SeriesDescription": "mb_diff_b1k_40dirs_2mm_AP_MB2G2"
      }
    },
    {
      "datatype": "dwi",
      "suffix": "dwi",
      "criteria": {
        "SeriesDescription": "mb_diff_b2k_53dirs_2mm_AP_MB2G2"
      }
    },
    {
      "datatype": "dwi",
      "suffix": "dwi",
      "criteria": {
        "SeriesDescription": "mb_diff_b3k_66dirs_2mm_AP_MB2G2"
      }
    },
    {
      "datatype": "dwi",
      "suffix": "b0",
      "criteria": {
        "SeriesDescription": "mb_diff_b0_7dirs_2mm_PA_MB2G2"
      }
    }
  ]
}

Is it possible to make the filenames more informative (e.g. explicitly indicating task names or DWI b-values) while remaining fully BIDS-compliant? If so, what would be the recommended way to do this in dcm2bids?

Many thanks in advance for your help!

2

Hi @tbn,

In the future, please format your code for readability using tickmarks (or by the </> button in the text editor). You can see I made the changes for you this time.

This is not done correctly. You can see an example here: Create a config file - dcm2bids documentation. For this particular example you could have "custom_entities": task-rest_acq-epfid2m4_dir-PA (the run-<> label will autopopulate if multiple matches for your criteria are found, or you could hard-code the run ID in, but that could cause issues if you had to repeat that sequence). Once this is corrected file names should be clearer. You would do the same for all items in your config file, including the fmaps and DWI. I do not see what command you used to run dcm2bids, but --auto_extract_entities might also be useful for you.

Best,
Steven

3

Hi @Steven ,

Thanks a lot for your help, I managed!!!

One follow-up I wanted to confirm: when running dcm2bids_helper, I consistently see two NIfTI/JSON pairs per acquisition (one very small, one much larger). Is it correct that these smaller files are reference/derived images (e.g. SBRef or single-volume reconstructions) produced by dcm2niix, and they don’t need to be included in the dcm2bids config file? Or do I need to include them?

Thanks again for pointing me in the right direction, much appreciated!

4

Hi @tbn,

fMRIPrep can use sbref images, and they are included in the BIDS specification. So you can add config entries to BIDS-ify them. Single-volume reconstructions (e.g., the scanner-derived trace or FAs from DWI) are not very useful and are fine not being in your raw BIDS directory.

Best,
Steven