bidscoiner ouputs files that haven't been specified in the editor

[JohannesWiesner]

Describe the bug

I used the bidseditor to create an edited bidsmap.yaml that should map all unique instances of my DICOMs to their corresponding BIDS-compliant NIfTI files. In the editor, everything looks correct — I’ve assigned unique labels to all distinct cases, and the mappings appear to cover all files properly. However, when I run bidscoiner, I get unexpected files that don’t appear in the editor.

In particular, for the T1w images: I know that for some subjects, there are two versions of the same T1w scan — one is non-uniformity–corrected by the scanner (identified by "NORM" in the "ImageType" field) and the other one is not (See this link). I currently differentiate between those two by using the desc-unnorm and desc-norm labels.

Despite this, bidscoiner generates additional files such as:

sub-YL4AS_ses-05_acq-unnorm_run-2_T1w.nii.gz
sub-6IECX_ses-03_acq-unnormEq1_T1w.nii.gz

These extra variants don’t correspond to anything I can see in the bidseditor, so I’m trying to understand why they’re being created.

My only clue right now is that bidscoin does not look at the ""ImageTypeText" field?

Expected behavior

Bidsmapper and/or Bidseditor should see all unique instances of my DICOMS so I can properly edit the bidsmap.yaml

Screenshots

Software version

• BIDScoin version: 4.6.2
• OS (e.g. Windows, Linux, MacOS): Linux

Additional context
Add any other context about the problem here.

[JohannesWiesner]

Might be related to:

#212 (comment)

[JohannesWiesner]

Addon: These are the two things that go wrong

1.) For some subjects and sessions, I get an additional file with the string "Eq1" in it (but no corresponding .json sidecar). Here I am clueless about what is going on:

I do get a corresponding warning though in the bidscoiner.errors file:

2025-10-20 14:34:17 - WARNING | Unexpected conversion result, could not find: /zi/flstorage/group_csp/in_house_datasets/bernn/mri/rawdata/sub-96WID/ses-01/anat/sub-96WID_ses-01_acq-unnormEq1_T1w.json
2025-10-20 14:34:19 - WARNING | Unexpected conversion result, could not find: /zi/flstorage/group_csp/in_house_datasets/bernn/mri/rawdata/sub-96WID/ses-01/anat/sub-96WID_ses-01_acq-normEq1_T1w.json

When I visually inspect the two files sub-6IECX_ses-03_acq-unnorm_T1w.nii.gz vs. sub-6IECX_ses-03_acq-unnormEq1_T1w.nii.gz they look identically but they don't have the same values:

2.) For some subjects and sessions, the bidscoiner creates two different run versions of my images. This only happens in session 5 and I know that the scanner settings have changed in that session.

When I inspect the corresponding sidecars of the .json files I can see that they are differing in the "ImageTypeText" section but not in the "ImageType" section. This is where I got the idea, that bidscoiner might not use this field to check file differences?

run-01:

    "ImageType": [
        "ORIGINAL",
        "PRIMARY",
        "M",
        "NONE",
        "MAGNITUDE"
    ],
    "ImageTypeText": [
        "ORIGINAL",
        "PRIMARY",
        "M",
        "DIS2D"
    ],

run-02:

    "ImageType": [
        "ORIGINAL",
        "PRIMARY",
        "M",
        "NONE",
        "MAGNITUDE"
    ],
    "ImageTypeText": [
        "ORIGINAL",
        "PRIMARY",
        "M",
        "NORM",
        "DIS2D"
    ],

[JohannesWiesner]

Okay, so I think:

• The first issue is described here and seems to be out of scope of bidscoin? Would still be nice if the log from dicom2niix would propagate to the bidscoiner log (so users know why these "Eq1" files are created. I can confirm that I get a warning, if I run dcm2niix directly on the subject's folder:

Warning: Interslice distance varies in this volume (incompatible with NIfTI format).
Warning: Missing images? Expected 191 images, but instance number (0020,0013) ranges from 1 to 192
Convert 191 DICOM as ./dcm2niix_out/t1_mprage_sag_p2_iso_6 (232x256x191x1)
Warning: Unable to rotate 3D volume: slices not equidistant: 1 != 2

But this warning is not propagated to the bidscoiner.error log (UPDATE: It is propagated to the bidscoiner.log file though)

• The second issue could be solved if bidscoin would also use the "ImageTypeText" field to discriminate images.

[marcelzwiers]

Thanks for your feedback and efforts to figure out what is going on. Indeed, the dcm2niix Eq1 suffix is a bit beyond bidscoin, as dcm2niix says:

_Eq is commonly seen in CT scans. For example, CT scans of the brain often have many slices closely packed near the brain stem and only a few slices spread far apart near the top of the head. Variable between-slice spacing is rarer in MRI, and if you see this from a MRI sequence you should ensure that all of the acquired slices have been provided to dcm2niix. NIfTI assumes all 2D slices that form a 3D stack are equidistant. Therefore, dcm2niix reslices the input data to generate an equidistant volume.

The problem is that it doesn't generate an error code, so that's why you don't see it in the error-log.

As for the ImageTypeText field, I can add it to the general template, but you can also easily do it yourself (see your ~/.bidscoin folder), e.g.:

  anat:       # ----------------------- All anatomical run-items --------------------
  - attributes: &anat_dicomattr   # An empty / non-matching reference dictionary that can be dereferenced in other run-items of this data type
      Modality:
      ProtocolName:
      SeriesDescription:
      ImageType:
      ImageTypeText:
      SequenceName:
      PulseSequenceName:
      SequenceVariant:
      ScanningSequence:
      EchoPulseSequence:          # Enhanced DICOM
      MRAcquisitionType:
      SliceThickness:
      FlipAngle:
      EchoNumbers:
      EchoTime:
      EffectiveEchoTime:
      RepetitionTime:
      InPlanePhaseEncodingDirection:

[marcelzwiers]

I also saw this post on neurostars:

neurolabusc
Jan '23

Please see dcm2niix issue 236 7. In brief, Siemens used to store private text in the public ImageType (0008,0008) tag, with XA30 Siemens is beginning to store these details in the private ImageTypeText (0021,1175) tag. Confusingly, the same XA30 device can store information in either the public or private tag depending on whether the user choses Enhanced or Classic DICOMs. The Siemens Research Collaboration Manager associated with your center can help you understand this transition.

The Siemens XA data has evolved dramatically from XA10 through XA30 thanks to community engagement. This means we get much richer datasets. However, due to this evolution it is crucial that you always use the latest stable release of dcm2niix. Here is a BIDS sidecar from a XA30 sequence that extracts the newly minted private ImageTypeText tag. The final line of the sidecar reveals that the recent stable version “ConversionSoftwareVersion”: “v1.0.20220717” 2 was used.

[marcelzwiers]

I'm not sure whether other manufacturers use ImageTypeText or not...

[JohannesWiesner]

Thanks for your feedback and efforts to figure out what is going on. Indeed, the dcm2niix Eq1 suffix is a bit beyond bidscoin, as dcm2niix says:

_Eq is commonly seen in CT scans. For example, CT scans of the brain often have many slices closely packed near the brain stem and only a few slices spread far apart near the top of the head. Variable between-slice spacing is rarer in MRI, and if you see this from a MRI sequence you should ensure that all of the acquired slices have been provided to dcm2niix. NIfTI assumes all 2D slices that form a 3D stack are equidistant. Therefore, dcm2niix reslices the input data to generate an equidistant volume.

Hm, I could ask the maintainer if all slices have been properly transferred over from the scanner. This might also be a network issue during copying?

[JohannesWiesner]

I'm not sure whether other manufacturers use ImageTypeText or not...

Ah okay, good to know. Maybe one could implement an if-else-statement? But of course, if this is super specific for my dataset/institution then it might not make sense to somehow add it to bidscoin.

[marcelzwiers]

You don't need if-else logic at all, just add the field, then bidscoin will use it to discriminate ("discover") datatypes. And if it's empty then it will simply be ignored

[JohannesWiesner]

You don't need if-else logic at all, just add the field, then bidscoin will use it to discriminate ("discover") datatypes. And if it's empty then it will simply be ignored

Ah sorry, I was talking about bidscoin itself. More in a sense of "Maybe bidscoin should be updated and also use this field for discovering files", but of course for my project specially, I know what to do now thanks! :)

[marcelzwiers]

I was also talking about bidscoin itself. Anyhow, I've added ImageTypeText to the template (for the next release)... Thanks again for your feedback. And please let me know if you found the cause of your Eq1 issue...

[JohannesWiesner]

I was also talking about bidscoin itself. Anyhow, I've added ImageTypeText to the template (for the next release)... Thanks again for your feedback. And please let me know if you found the cause of your Eq1 issue...

I see, sorry for the confusion! Yes, will update you on the Eq1 issue :)

[JohannesWiesner]

I could not find out what caused the Eq1 issue. Just from reading the threads it sounds like the most reasonable thing to do for these images is to use the Eq1-fixed ones created by dicom2niix. I trust @neurolabusc here but it would be nice if the Eq1 images would also get their own .json sidecars (?)

[neurolabusc]

@JohannesWiesner can you share the problematic DICOMs with my institutional email? It might also be useful to know what version of dcm2niix was used for this conversion.