Dcm2bids config fmap pairing problems

Priya_Kalra · June 17, 2025, 4:47pm

Summary of what happened:

Hello,

I am trying to BIDS-ify some DICOMs using dcm2bids. It works fine for the anat and func, but I am having some issues with the fmaps. Based on my reading of the helper .json files, I have magnitude1, magnitude2, and phase difference files. I have included my config file contents under “validator output” below.

Here are some of the strange things that happened as I was tinkering with the config file:
At first, it worked for magnitude1 and magnitude2, but failed to pair for phasediff. I have tried several criteria to uniquely identify the phasediff file (including the helper file .json filename, “ImageType”, and “EchoTime1” and “EchoTime2” together), but I either get the message that it pairs with both magnitude2 and phasediff or it seems like it is ignored.

Then, I tried deleting the entry for phasediff, but then it seemed to ignore magnitude 2 (the next-to-last entry in the config file)–not even saying that it did not pair. So that was also very strange.

Most recently, it has counted the phasediff file as a second run of magnitude2.

Also strange: I updated dcm2niix with pip, but I keep getting the message that there is a newer version.

Please help me–I think this should be fairly straightforward but I’m not sure what I’m missing.

Thank you.

Command used (and if a helper script was used, a link to the helper script or the command generated):

dcm2bids -d Downloads/DICOM -p P156 -c tmp_dcm2bids/code/dcm2bids_config.json

Version:

PUT VERSION HERE

Environment (Docker, Singularity / Apptainer, custom installation):

Installed on python using pip, linux environment.

Data formatted according to a validatable standard? Please provide the output of the validator:

{
  "descriptions": [
    {
      "datatype": "func",
      "suffix": "bold",
      "criteria": {
        "SeriesDescription": "ep_bold_mb4_task"
      }
    },
    
    {
      "datatype": "anat",
      "suffix": "T1w",
      "criteria": {
        "SeriesDescription": "MPRAGE SAG"
      }
    },
    {
      "datatype": "fmap",
      "suffix": "magnitude1",
      "criteria": {
        "SeriesDescription": "gre_field_mapping",
        "EchoTime": 0.00492
      },
            "sidecar_changes": {
        "intendedFor": "ep_bold_mb4_task"
        }
    },

  {
      "datatype": "fmap",
      "suffix": "magnitude2",
      "criteria": {
        "SeriesDescription": "gre_field_mapping",
        "EchoTime": "0.00738"
      },
       "sidecar_changes": {
        "intendedFor": "ep_bold_mb4_task"
        }
    },
                {
      "datatype": "fmap",
      "suffix": "phasediff",
      "criteria": {
	"SidecarFilename": "014_DICOM_gre_field_mapping_20241029134745_e2_ph.json"
      },
       "sidecar_changes": {
        "intendedFor": "ep_bold_mb4_task"        }
        }
  ]
}

Relevant log outputs (up to 20 lines):

```INFO    | --- dcm2bids start ---
INFO    | Running the following command: /home/UWO/pkalra7/venv/bin/dcm2bids -d Downloads/DICOM -p P156 -c tmp_dcm2bids/code/dcm2bids_config.json
INFO    | OS version: Linux-5.15.0-140-generic-x86_64-with-glibc2.35
INFO    | Python version: 3.10.12 (main, Feb  4 2025, 14:57:36) [GCC 11.4.0]
INFO    | dcm2bids version: 3.2.0
INFO    | dcm2niix version: v1.0.20250505
INFO    | Checking for software update
INFO    | Currently using the latest version of dcm2bids.
WARNING | A newer version exists for dcm2niix: v1.0.20250506
WARNING | You should update it -> https://github.com/rordenlab/dcm2niix.
INFO    | participant: sub-P156
INFO    | config: /home/UWO/pkalra7/tmp_dcm2bids/code/dcm2bids_config.json
INFO    | BIDS directory: /home/UWO/pkalra7
INFO    | Auto extract entities: False
INFO    | Reorder entities: True
INFO    | Validate BIDS: False

INFO    | Running: dcm2niix -b y -ba y -z y -f %3s_%f_%p_%t -o /home/UWO/pkalra7/tmp_dcm2bids/sub-P156 Downloads/DICOM
INFO    | Check log file for dcm2niix output

INFO    | SIDECAR PAIRING
INFO    | No Pairing  <-  001_DICOM_AAHScout_20241029134745
INFO    | No Pairing  <-  002_DICOM_AAHScout_20241029134745_i00001
INFO    | No Pairing  <-  002_DICOM_AAHScout_20241029134745_i00002
INFO    | No Pairing  <-  002_DICOM_AAHScout_20241029134745_i00003
INFO    | No Pairing  <-  002_DICOM_AAHScout_20241029134745_i00004
INFO    | No Pairing  <-  003_DICOM_AAHScout_20241029134745_i00001
INFO    | No Pairing  <-  003_DICOM_AAHScout_20241029134745_i00002
INFO    | No Pairing  <-  003_DICOM_AAHScout_20241029134745_i00003
INFO    | No Pairing  <-  004_DICOM_AAHScout_20241029134745_i00001
INFO    | No Pairing  <-  004_DICOM_AAHScout_20241029134745_i00002
INFO    | No Pairing  <-  004_DICOM_AAHScout_20241029134745_i00003
INFO    | sub-P156_bold  <-  005_DICOM_ep_bold_mb4_task_20241029134745
INFO    | sub-P156_bold  <-  006_DICOM_ep_bold_mb4_task_20241029134745
INFO    | sub-P156_bold  <-  007_DICOM_ep_bold_mb4_task_20241029134745
INFO    | sub-P156_T1w  <-  008_DICOM_MPRAGE_SAG_20241029134745
INFO    | sub-P156_bold  <-  009_DICOM_ep_bold_mb4_task_20241029134745
INFO    | sub-P156_bold  <-  010_DICOM_ep_bold_mb4_task_20241029134745
INFO    | sub-P156_bold  <-  011_DICOM_ep_bold_mb4_task_20241029134745
INFO    | sub-P156_magnitude1  <-  013_DICOM_gre_field_mapping_20241029134745_e1
INFO    | sub-P156_magnitude2  <-  013_DICOM_gre_field_mapping_20241029134745_e2
WARNING | Several Pairing  <-  014_DICOM_gre_field_mapping_20241029134745_e2_ph
WARNING |     ->  _magnitude2
WARNING |     ->  _phasediff
INFO    | No Pairing  <-  012_DICOM_ep_bold_mb4_PA_20241029134745
INFO    | sub-P156/func/sub-P156_bold has 6 runs
INFO    | Adding run information to the acquisition
INFO    | Moving acquisitions into BIDS folder "/home/UWO/pkalra7/sub-P156".

Screenshots / relevant information:

Steven · June 17, 2025, 5:03pm

Hi @Priya_Kalra and welcome to neurostars!

Priya_Kalra:

      "datatype": "fmap",
      "suffix": "phasediff",
      "criteria": {
	"SidecarFilename": "014_DICOM_gre_field_mapping_20241029134745_e2_ph.json"
      },
       "sidecar_changes": {
        "intendedFor": "ep_bold_mb4_task"        }
        }

This will only work if there is "SidecarFilename" metadata in your jsons, and even then it will only work for that one subject since that name seems too specific to generalize to other subjects.

Priya_Kalra:

      "datatype": "fmap",
      "suffix": "magnitude1",
      "criteria": {
        "SeriesDescription": "gre_field_mapping",
        "EchoTime": 0.00492
      },
            "sidecar_changes": {
        "intendedFor": "ep_bold_mb4_task"
        }
    },

  {
      "datatype": "fmap",
      "suffix": "magnitude2",
      "criteria": {
        "SeriesDescription": "gre_field_mapping",
        "EchoTime": "0.00738"
      },
       "sidecar_changes": {
        "intendedFor": "ep_bold_mb4_task"
        }
    },

The EchoNumber metadata if available would be better than EchoTime. Would also include ImageType to disambiguate between magnitude and phasediff.

Also, your IntendedFor are specified incorrectly. They must be in the form of

{
  "sidecar_changes": {
    "IntendedFor": "ID"
  }
}

where "ID" links to IDs you give to your BOLD files. You currently do not have any IDs for any files. I encourage you to read the dcm2bids documentation: Create a config file - dcm2bids documentation

Best,
Steven

Priya_Kalra · June 17, 2025, 8:39pm

Hi Steven,

Thanks very much for your help! I re-read the documentation you linked and followed your suggestions and now everything works as I had hoped.

I am posting my updated config file and output for anyone else who has the same problem.

Config file:

{
  "descriptions": [
    { "id": "task",
      "datatype": "func",
      "suffix": "bold",
      "criteria": {
        "SeriesDescription": "ep_bold_mb4_task"
      }
    },
    
    {
      "datatype": "anat",
      "suffix": "T1w",
      "criteria": {
        "SeriesDescription": "MPRAGE SAG"
      }
    },
    {
      "datatype": "fmap",
      "suffix": "magnitude1",
      "criteria": {
        "SeriesDescription": "gre_field_mapping",
        "EchoNumber": 1,
        "ImageType": ["ORIGINAL", "PRIMARY", "M", "ND", "MAGNITUDE"]
      },
            "sidecar_changes": {
        "intendedFor": "task"
        }
    },

  {
      "datatype": "fmap",
      "suffix": "magnitude2",
      "criteria": {
        "SeriesDescription": "gre_field_mapping",
        "EchoNumber": 2,
        "ImageType": ["ORIGINAL", "PRIMARY", "M", "ND", "MAGNITUDE"]
      },
       "sidecar_changes": {
        "intendedFor": "task"
        }
    },
                {
      "datatype": "fmap",
      "suffix": "phasediff",
      "criteria": {
	"ImageType": ["ORIGINAL", "PRIMARY", "P", "ND", "PHASE"]
      },
       "sidecar_changes": {
        "intendedFor": "task"        }
        },
                      {
      "datatype": "fmap",
      "suffix": "_acq-EPI_dir-PA_epi",
      "criteria": {
	"SeriesDescription": "ep_bold_mb4_PA"
      },
       "sidecar_changes": {
        "intendedFor": "task"        }
        }  
  ]
}

Output:

(venv) pkalra7@UWO-CBS-Heavy10:~$ dcm2bids -d Downloads/DICOM -p P156 -c tmp_dcm2bids/code/dcm2bids_config.json
INFO    | --- dcm2bids start ---
INFO    | Running the following command: /home/UWO/pkalra7/venv/bin/dcm2bids -d Downloads/DICOM -p P156 -c tmp_dcm2bids/code/dcm2bids_config.json
INFO    | OS version: Linux-5.15.0-140-generic-x86_64-with-glibc2.35
INFO    | Python version: 3.10.12 (main, Feb  4 2025, 14:57:36) [GCC 11.4.0]
INFO    | dcm2bids version: 3.2.0
INFO    | dcm2niix version: v1.0.20250505
INFO    | Checking for software update
INFO    | Currently using the latest version of dcm2bids.
WARNING | A newer version exists for dcm2niix: v1.0.20250506
WARNING | You should update it -> https://github.com/rordenlab/dcm2niix.
INFO    | participant: sub-P156
INFO    | config: /home/UWO/pkalra7/tmp_dcm2bids/code/dcm2bids_config.json
INFO    | BIDS directory: /home/UWO/pkalra7
INFO    | Auto extract entities: False
INFO    | Reorder entities: True
INFO    | Validate BIDS: False

INFO    | Running: dcm2niix -b y -ba y -z y -f %3s_%f_%p_%t -o /home/UWO/pkalra7/tmp_dcm2bids/sub-P156 Downloads/DICOM
INFO    | Check log file for dcm2niix output

INFO    | SIDECAR PAIRING
INFO    | No Pairing  <-  001_DICOM_AAHScout_20241029134745
INFO    | No Pairing  <-  002_DICOM_AAHScout_20241029134745_i00001
INFO    | No Pairing  <-  002_DICOM_AAHScout_20241029134745_i00002
INFO    | No Pairing  <-  002_DICOM_AAHScout_20241029134745_i00003
INFO    | No Pairing  <-  002_DICOM_AAHScout_20241029134745_i00004
INFO    | No Pairing  <-  003_DICOM_AAHScout_20241029134745_i00001
INFO    | No Pairing  <-  003_DICOM_AAHScout_20241029134745_i00002
INFO    | No Pairing  <-  003_DICOM_AAHScout_20241029134745_i00003
INFO    | No Pairing  <-  004_DICOM_AAHScout_20241029134745_i00001
INFO    | No Pairing  <-  004_DICOM_AAHScout_20241029134745_i00002
INFO    | No Pairing  <-  004_DICOM_AAHScout_20241029134745_i00003
INFO    | sub-P156_bold  <-  005_DICOM_ep_bold_mb4_task_20241029134745
INFO    | sub-P156_bold  <-  006_DICOM_ep_bold_mb4_task_20241029134745
INFO    | sub-P156_bold  <-  007_DICOM_ep_bold_mb4_task_20241029134745
INFO    | sub-P156_T1w  <-  008_DICOM_MPRAGE_SAG_20241029134745
INFO    | sub-P156_bold  <-  009_DICOM_ep_bold_mb4_task_20241029134745
INFO    | sub-P156_bold  <-  010_DICOM_ep_bold_mb4_task_20241029134745
INFO    | sub-P156_bold  <-  011_DICOM_ep_bold_mb4_task_20241029134745
INFO    | sub-P156_magnitude1  <-  013_DICOM_gre_field_mapping_20241029134745_e1
INFO    | sub-P156_magnitude2  <-  013_DICOM_gre_field_mapping_20241029134745_e2
INFO    | sub-P156_phasediff  <-  014_DICOM_gre_field_mapping_20241029134745_e2_ph
INFO    | sub-P156_acq-EPI_dir-PA_epi  <-  012_DICOM_ep_bold_mb4_PA_20241029134745
INFO    | sub-P156/func/sub-P156_bold has 6 runs
INFO    | Adding run information to the acquisition
INFO    | Moving acquisitions into BIDS folder "/home/UWO/pkalra7/sub-P156".

INFO    | Logs saved in /home/UWO/pkalra7/tmp_dcm2bids/log/sub-P156_20250617-163456.log
INFO    | --- dcm2bids end ---

Steven · June 17, 2025, 8:50pm

Hi @Priya_Kalra,

Great! But I think the “I” in IntendedFor has to be capitalized in your config. Confirm in your fmap jsons that it looks correct.

Best,
Steven