False `MULTIPLE_INHERITABLE_FILES` error for distinct `_dwi` files with different entities

[rcruces]

I'm encountering a MULTIPLE_INHERITABLE_FILES error in a dataset that I believe complies with the BIDS Inheritance Principle.

Example error

[ERROR] MULTIPLE_INHERITABLE_FILES Multiple files in a directory were found to be valid candidates for inheritance.
/sub-MPN0000018/ses-MPN1Scan1/dwi/sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_dwi.bval - Candidate files:
/sub-MPN0000018/ses-MPN1Scan1/dwi/sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_dwi.bval,
/sub-MPN0000018/ses-MPN1Scan1/dwi/sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_part-phase_dwi.bval

Description

The validator treats both .bval files as valid metadata for the same _dwi.nii.gz image, but they differ by the part- entity, and the target _dwi.nii.gz does not include part-phase.

According to the BIDS Inheritance Principle (Rule 2.c):

"The metadata filename must not include any entity absent from the data filename."

So in this case:

• sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_dwi.nii.gz
  should only match →
  sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_dwi.bval

…and should not match
sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_part-phase_dwi.bval.

Observations

• This error only occurs for subjects that include files with a run- entity (e.g., SBRefs with run-1, run-2).
• The DWI filenames themselves do not include run-, so run- shouldn't be influencing which .bval gets matched.
• It seems like the validator is mistakenly treating both .bval files as valid candidates, despite the extra part- entity, which should disqualify one of them per Rule 2.c.

Affected directory (simplified)

sub-MPN0000018/ses-MPN1Scan1/dwi/
├── sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_dwi.nii.gz
├── sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_dwi.bval
├── sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_part-phase_dwi.nii.gz
├── sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_part-phase_dwi.bval
├── sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_run-1_sbref.nii.gz
├── sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_run-2_sbref.nii.gz
├── sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_run-1_part-phase_sbref.nii.gz
├── sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_run-2_part-phase_sbref.nii.gz

Non-affected (most common structure)

sub-MPN0000022/ses-MPN1Scan1/dwi/
├── sub-MPN0000022_ses-MPN1Scan1_acq-multib38_dir-AP_dwi.bval
├── sub-MPN0000022_ses-MPN1Scan1_acq-multib38_dir-AP_dwi.nii.gz
├── sub-MPN0000022_ses-MPN1Scan1_acq-multib38_dir-AP_part-phase_dwi.bval
├── sub-MPN0000022_ses-MPN1Scan1_acq-multib38_dir-AP_part-phase_dwi.nii.gz
├── sub-MPN0000022_ses-MPN1Scan1_acq-multib38_dir-AP_part-phase_sbref.nii.gz
├── sub-MPN0000022_ses-MPN1Scan1_acq-multib38_dir-AP_sbref.nii.gz

Validator version

• BIDS Validator 2.0.3 (deno 2.2.3)

Suggestion

This looks like a validator bug in how it handles metadata inheritance and filename disambiguation when multiple metadata files exist in the same directory and differ by additional entities. Rule 2.c should cause *_part-phase_dwi.bval to be excluded as a candidate for *_dwi.nii.gz, but it seems not to be.

---

Note: This issue might be related to the ongoing discussion in #2224 #2155 regarding limitations and edge cases in the current implementation of the Inheritance Principle.

[effigies]

I would guess that the error is when looking at sub-MPN0000018_ses-MPN1Scan1_acq-multib38_dir-AP_part-phase_dwi.nii.gz, and there are then two .bval files that each match a subset of entities.

Please confirm that this is still an issue with the latest release, 2.0.7.

Also, why do your .bvals differ for the phase and magnitude images, and why do you omit the part-mag from the magnitude images? If the bvals don't differ, I would delete the duplicate with part-phase. I would also recommend using part-mag when there is a part-phase to contrast with it.

[rcruces]

Thanks for the insight!

I'll re-run the validation using version 2.0.7 and confirm whether the issue persists.

it's a good point about using part-mag for consistency. We'll likely update the filenames to include part-mag where appropriate.

Appreciate the guidance!