Custom Entities for fmaps

Software Support
1

Summary of what happened:

I am running the dcm2bids converter. The config.json file is set up to BIDSify anat, func and fmaps. So far it does it correctly, but I would like the fmaps filenaming convention follow that of the func > task-rest and func > task-sessionName bold files. We have two sessions: Reward and Threat. Is it possible to include the label “task-description” in the func file name similar to the func files I mentioned before?

Please see below for the config file:

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

{
  "extractors": {
    "SeriesDescription": [
      "(?P<echo>[0-9])"
    ]
  },
  "descriptions": [
    {
      "datatype": "anat",
      "suffix": "T1w",
      "criteria": {
        "SeriesDescription": "T1w_MPR",
        "EchoTime": 0.00222
      },
      "sidecar_changes": {
        "ProtocolName": "T1w_MPR"
      }
    },
    {
      "id": "task_rest",
      "datatype": "func",
      "suffix": "bold",
      "custom_entities": "task-rest",
      "criteria": {
        "ProtocolName": "bold_2mm_rest",
        "SeriesDescription": "bold_2mm_rest",
        "SeriesNumber": 8,
        "ImageType": ["ORIG*", "PRIMARY", "M", "ND", "NORM", "MOSAIC", "MAGNITUDE"]
      },
      "sidecar_changes": {
        "TaskName": "rest"
      }
    },
    {
      "datatype": "fmap",
      "suffix": "epi",
      "criteria": {
        "ProtocolName": "ep2d_bold_2mm_A>P",
        "SeriesNumber": 6,
        "PhaseEncodingDirection": "j-",
        "TotalReadoutTime": 0.0711195
      },
      "sidecar_changes": {
        "TaskName": "rest"
      }
    },
    {
      "datatype": "fmap",
      "suffix": "epi",
      "criteria": {
        "ProtocolName": "ep2d_bold_2mm_P>A",
        "SeriesNumber": 7,
        "PhaseEncodingDirection": "j",
        "TotalReadoutTime": 0.0711195
      },
      "sidecar_changes": {
        "TaskName": "rest"
      }
    },
    {
      "id": "task_reward",
      "datatype": "func",
      "suffix": "bold",
      "custom_entities": "task-reward",
      "criteria": {
        "ProtocolName": "bold_2mm_task",
        "SeriesDescription": "bold_2mm_task",
        "SeriesNumber": 11,
        "ImageType": ["ORIG*", "PRIMARY", "M", "ND", "NORM", "MOSAIC", "MAGNITUDE"]
      },
      "sidecar_changes": {
        "TaskName": "reward"
      }
    },
    {
      "datatype": "fmap",
      "suffix": "epi",
      "criteria": {
        "ProtocolName": "ep2d_bold_2mm_A>P",
        "SeriesNumber": 9,
        "PhaseEncodingDirection": "j-",
        "TotalReadoutTime": 0.0711195
      },
      "sidecar_changes": {
        "TaskName": "reward"
      }
    },
    {
      "datatype": "fmap",
      "suffix": "epi",
      "criteria": {
        "ProtocolName": "ep2d_bold_2mm_P>A",
        "SeriesNumber": 10,
        "PhaseEncodingDirection": "j",
        "TotalReadoutTime": 0.0711195
      },
      "sidecar_changes": {
        "TaskName": "reward"
      }
    }
  ]
}

Version:

dcm2bids version: 3.2.0
Based on BIDS version: v1.9.0

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

dcm2bids was installed through the Terminal and is being used in conjunction with a Python script.

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

PASTE VALIDATOR OUTPUT HERE

Relevant log outputs (up to 20 lines):

PASTE LOG OUTPUT HERE

Screenshots / relevant information:

Screenshot 2025-03-19 at 9.19.36 PM

2

Hi @caponte2 ,

Fmaps do not support the task-<> entity, but you can use acq-<> instead to make the association in the filename clearer.

Best,
Steven

3

Also I do not recommend using SeriesNumber as a criterion incase you have missing or repeated scans.

Additionally you will need to add the IntendedFor and/or B0FieldSource/Identifier method to link the fmaps to the BOLD.

4

That’s great!.
Thank you for all your help, @Steven.

Best,
Carlos

1 Like
5

Hi @Steven,

Using the IntendedFor method worked! I am encountering one issue. We have two sessions called Reward and Threat. For some reason the acq-<> entity works for Threat but not for Reward. I compared both .json files after being converted to NifTi and they are identical except for ProcedureStepDescription: where one holds the value of 6047_6167^Threat_Learning and the other 6047_6167^Reward_Learning . I have the config.json file set up the following way, which successfully adds the acq-<> entity to any subjects in the Threat session:

{
  "extractors": {
    "SeriesDescription": [
      "(?P<echo>[0-9])"
    ]
  },
  "descriptions": [
    {
      "datatype": "anat",
      "suffix": "T1w",
      "criteria": {
        "SeriesDescription": "T1w_MPR",
        "EchoTime": 0.00222
      },
      "sidecar_changes": {
        "ProtocolName": "T1w_MPR"
      }
    },
    {
      "id": "task_rest",
      "datatype": "func",
      "suffix": "bold",
      "custom_entities": "task-rest",
      "criteria": {
        "ProtocolName": "bold_2mm_rest",
        "SeriesDescription": "bold_2mm_rest",
        "ImageType": ["ORIG*", "PRIMARY", "M", "ND", "NORM", "MOSAIC", "MAGNITUDE"]
      },
      "sidecar_changes": {
        "TaskName": "rest"
      }
    },
    {
      "datatype": "fmap",
      "suffix": "epi",
      "custom_entities": "acq-rest",
      "criteria": {
        "ProtocolName": "ep2d_bold_2mm_A>P",
        "ProcedureStepDescription": "6047_6167^Threat_Learning",
        "PhaseEncodingDirection": "j-",
        "TotalReadoutTime": 0.0711195
      },
      "sidecar_changes": {
        "TaskName": "rest",
        "IntendedFor": "task_rest"
      }
    },
    {
      "datatype": "fmap",
      "suffix": "epi",
      "custom_entities": "acq-rest",
      "criteria": {
        "ProtocolName": "ep2d_bold_2mm_P>A",
        "ProcedureStepDescription": "6047_6167^Threat_Learning",
        "PhaseEncodingDirection": "j",
        "TotalReadoutTime": 0.0711195
      },
      "sidecar_changes": {
        "TaskName": "rest",
        "IntendedFor": "task_rest"
      }
    }
  ]
}

What I should be looking out for?

Many thanks in advance!

Best,
Carlos

6

Hi @caponte2,

Without seeing your jsons or knowing more about your file organization and dcm2bids command I cannot prescribe an exact solution. I also don’t know what you mean when you say the “acq-<>” label doesn’t work. Do you mean the label isn’t added, or no file is converted, or something else? You can consider using wildcards in the criteria if somethings like numbers in the fields may be different. I also do not see any of your “reward” items in the config. Also TaskName should not be a json field for fmaps.

Best,
Steven

7

Thank you for your quick reply. I only added the config for the Threat session. I have been testing them separately. The only value that would change is the ProcedureStepDescription: where 6047_6167^Threat_Learning would be changed to 6047_6167^Reward_Learning.

The acq-<> isn’t added to any fmaps coming from Reward subjects. The dcm2bids converter does convert their files to JSON and NifTi, but they get dumped to the tmp folder and are not renamed.

As for file organization, please see attached. sub-02’s fmap JSONs are in the tmp_dcm2bids folder.

Screenshot 2025-03-21 at 3.07.59 PM
Screenshot 2025-03-21 at 3.07.59 PM500×681 67.1 KB

I am using the following command:

Running the following command: /Users/caponte2/miniconda3/envs/dcm2bids/bin/dcm2bids -d /Users/caponte2/Desktop/BIDS_MoonFlower_CarlosAponte_fmaps/bids_project/sourcedata/MoonReward/02 -p 02 -s moon -c /Users/caponte2/Desktop/BIDS_MoonFlower_CarlosAponte_fmaps/bids_project/code/config.json --auto_extract_entities

which then runs:

 Running: dcm2niix -b y -ba y -z y -f %3s_%f_%p_%t -o /Users/caponte2/Desktop/BIDS_MoonFlower_CarlosAponte_fmaps/bids_project/tmp_dcm2bids/sub-02_ses-moon /Users/caponte2/Desktop/BIDS_MoonFlower_CarlosAponte_fmaps/bids_project/sourcedata/MoonReward/02

I will try using the wildcards.

Thanks again!

Best,
Carlos

8

It seems that removing TaskName: did the trick.

Thank you for your help!

Best,
Carlos