Dcm2bids: using epi as a field map

Software Support
1

Summary of what happened:

I have two epi field maps, one AP and one PA, that I’d like to use for distortion correction on functional images. When running dcm2bids, I get a “No Pairing” error for these sequences. The json file I’m using is pasted below (using only one functional run for brevity). I’ve tried a couple of different approaches from different threads on this site but keep running into the same issue.

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

         "id": "DMC-run-10",
         "datatype": "func",
         "suffix": "bold",
         "custom_entities": "task-DMC",
         "criteria": {
            "SidecarFilename": "017*"
         },
         "sidecar_changes": {
            "TaskName": "DMC"
         }
      },
      {
         "datatype": "fmap",
         "suffix": "epi",
         "criteria": {
            "SeriesDescription": "distortion_AP",
            "dir" : "AP",
            "PhaseEncodingDirection": "j-",
            "SidecarFilename": "006*"
         },
         "sidecar_changes": {
            "TaskName": "DMC",
            "IntendedFor": [
             "DMC-run-01",
             "DMC-run-02",
             "DMC-run-03",
             "DMC-run-04",
             "DMC-run-05",
             "DMC-run-06",
             "DMC-run-07",
             "DMC-run-08",
             "DMC-run-09",
             "DMC-run-10"
         ]
        }
      },
      {
         "datatype": "fmap",
         "suffix": "epi",
         "criteria": {
            "SeriesDescription": "distortion_PA",
            "dir" : "PA",
            "PhaseEncodingDirection": "j",
            "SidecarFilename": "007*"
         },
         "sidecar_changes": {
            "TaskName": "DMC",
            "IntendedFor": [
             "DMC-run-01",
             "DMC-run-02",
             "DMC-run-03",
             "DMC-run-04",
             "DMC-run-05",
             "DMC-run-06",
             "DMC-run-07",
             "DMC-run-08",
             "DMC-run-09",
             "DMC-run-10"
         ]
        }
      }

Version:

3.2.0

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

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:

Here’s a screenshot of the dcm2bids output:

image
image1773×663 204 KB

2

Hi @Edward_Ester and welcome to neurostars!

It will be hard to more precisely assist you without JSONs from your fmaps, may you provide those please?

Is dir a metadata in your fmap json? That’s not typical.

I also don’t recommend using any criteria that relies on acquisition number, in case you have scans that are misordered for any reason (e.g., a repeated scan).

Best,
Steven

3

Here’s the json file generated by ezbids. I was trying to do the conversion in one go using dcm2bids (rather than, e.g., heudiconv or dcm2niix), and the issue is that it doesn’t seem to recognize these acquisitions as field maps. Sorry if this is a silly question - it’s been ~15 years since I did this stuff and back then it was all BrainVoyager!

{
    "Modality": "MR",
    "MagneticFieldStrength": 3,
    "ImagingFrequency": 123.250147,
    "Manufacturer": "Siemens",
    "ManufacturersModelName": "MAGNETOM Skyra",
    "InstitutionName": "Double R Siemens 3T Renown",
    "InstitutionAddress": "Double R Blvd. 10085,RENO,District,US,89521",
    "DeviceSerialNumber": "145728",
    "StationName": "AWP145728",
    "SeriesInstanceUID": "1.3.12.2.1107.5.2.19.145728.2025110909112767987542607.0.0.0",
    "StudyInstanceUID": "1.3.12.2.1107.5.2.19.145728.30000025110906450063900000003",
    "StudyID": "8c505419-ad7c-40",
    "PatientName": "CB",
    "PatientID": "2025.11.09-07:58:47-STD-1.3.12.2.1107.5.99.3",
    "PatientBirthDate": "1999-03-03",
    "PatientSex": "F",
    "PatientWeight": 72.5747,
    "PatientAge": 26,
    "BodyPartExamined": "HEAD",
    "PatientPosition": "HFS",
    "SoftwareVersions": "syngo MR XA60",
    "MRAcquisitionType": "2D",
    "SeriesDescription": "distortion_AP",
    "ProtocolName": "distortion_AP",
    "ScanningSequence": "EP",
    "SequenceVariant": "SK",
    "ScanOptions": "FS",
    "PulseSequenceName": "*epfid2d1_80",
    "ImageType": [
        "ORIGINAL",
        "PRIMARY",
        "FMRI",
        "NONE"
    ],
    "ImageTypeText": [
        "ORIGINAL",
        "PRIMARY",
        "M",
        "ND"
    ],
    "NonlinearGradientCorrection": false,
    "SeriesNumber": 13,
    "AcquisitionTime": "09:11:37.185000",
    "AcquisitionDateTime": "2025-11-09T09:11:37.185000",
    "AcquisitionNumber": 1,
    "SliceThickness": 2.5,
    "SpacingBetweenSlices": 2.5,
    "EchoTime": 0.046,
    "RepetitionTime": 3.54,
    "MTState": false,
    "FlipAngle": 90,
    "PartialFourier": 1,
    "BaseResolution": 80,
    "ShimSetting": [
        9498,
        -11389,
        2269,
        692,
        -322,
        1326,
        -466,
        79
    ],
    "TxRefAmp": 319.318,
    "PhaseResolution": 1,
    "ReceiveCoilName": "Head_32",
    "ReceiveCoilActiveElements": "HEA;HEP",
    "CoilString": "Head_32",
    "PulseSequenceDetails": "%SiemensSeq%\\ep2d_bold",
    "RefLinesPE": 14,
    "CoilCombinationMethod": "Sum of Squares",
    "MultibandAccelerationFactor": 3,
    "PercentPhaseFOV": 100,
    "PercentSampling": 100,
    "EchoTrainLength": 80,
    "PhaseEncodingSteps": 80,
    "FrequencyEncodingSteps": 80,
    "AcquisitionMatrixPE": 80,
    "ReconMatrixPE": 80,
    "BandwidthPerPixelPhaseEncode": 21.93,
    "ParallelAcquisitionTechnique": "SMS",
    "EffectiveEchoSpacing": 0.000569995,
    "DerivedVendorReportedEchoSpacing": 0.000569995,
    "AcquisitionDuration": 22.285,
    "TotalReadoutTime": 0.0450296,
    "PixelBandwidth": 2155,
    "DwellTime": 0.0000029,
    "PhaseEncodingDirection": "j-",
    "SliceTiming": [
        0,
        1.8775,
        0.235,
        2.1125,
        0.47,
        2.3475,
        0.705,
        2.5825,
        0.94,
        2.8175,
        1.175,
        3.0525,
        1.41,
        3.2875,
        1.6425,
        0,
        1.8775,
        0.235,
        2.1125,
        0.47,
        2.3475,
        0.705,
        2.5825,
        0.94,
        2.8175,
        1.175,
        3.0525,
        1.41,
        3.2875,
        1.6425,
        0,
        1.8775,
        0.235,
        2.1125,
        0.47,
        2.3475,
        0.705,
        2.5825,
        0.94,
        2.8175,
        1.175,
        3.0525,
        1.41,
        3.2875,
        1.6425
    ],
    "ImageOrientationPatientDICOM": [
        0.999605,
        0.0279297,
        -0.00311355,
        -0.0279215,
        0.999607,
        0.00263798
    ],
    "InPlanePhaseEncodingDirectionDICOM": "COL",
    "BidsGuess": [
        "func",
        "_acq-epfid2m3_dir-AP_run-13_bold"
    ],
    "ConversionSoftware": "dcm2niix",
    "ConversionSoftwareVersion": "v1.0.20240202"
}
4

Hi @Edward_Ester,

dcm2bids has dcm2niix under the hood and can do everything in one step (as opposed to having something else produce the json/nifti pairs before using dcm2bids).

dir is not in your fmap json metadata, which is why your pairings fail. In general you want your criteria to be minimally sufficient. Trying to over-specify it can lead to unintentional missed pairings (e.g., if you had a fmap that had 009 instead of 007). It seems like in your case I doubt any other file will have a SeriesDescription of distortion_AP/PA, can probably just stick to that.

Best,
Steven