gradient echo fmap and dir-

[CPernet]

According to the definition https://bids-specification.readthedocs.io/en/stable/appendices/entities.html#dir dir- is arbitrary in terms of which files it comes with -- except some, e.g. pepolar field maps.

Problem -- I have fmaps for case 1 in which i put e.g. acq-gre_dir-LR and others as acq-gre_dir-RL ... oh it doesn't like that! (and bids-matlab doesn't see them somehow)

[effigies]

Could you provide the full listing of your fmap directory?

[CPernet]

https://github.com/CPernet/bids-matlab/tree/dev/demos/fmap_failexemple

[effigies]

It looks like it's being used as a label to distinguish acquisition parameters, not a way of distinguishing among related files. Is there a reason not to simply do acq-greLR and acq-greAP?

[CPernet]

because we also have spin echo but they are labelled _epi (don't ask why it's that complicated) -- in any cases why would dir-LP not be valid?

shouldn't dir- be allowed anywhere? there is nothing that says the opposite https://bids-specification.readthedocs.io/en/stable/appendices/entities.html#dir

tagging @Remi-Gau

[CPernet]

can you comment on 'not a way of distinguishing among related files' -- why would using the direction not be a good way?

sub-57507_ses-Baseline_acq-se_dir-AP_run-1_epi is valid
sub-57507_ses-Baseline_acq-gre_dir-AP_run-1 is not valid because dir doesn't apply to gre ?? doesn't make sense to me

[effigies]

can you comment on 'not a way of distinguishing among related files' -- why would using the direction not be a good way?

sub-57507_ses-Baseline_acq-se_dir-AP_run-1_epi is valid sub-57507_ses-Baseline_acq-gre_dir-AP_run-1 is not valid because dir doesn't apply to gre ?? doesn't make sense to me

This is about how files are grouped. With GRE fieldmaps, you have 2 magnitude images and a phase difference image. Because the phase difference image is of a different quantity than the magnitudes, they made sense as different suffixes, and the group is the collection of files with these suffixes. In this case, dir-AP would be additional metadata, but would not distinguish between these related files. The dir-LR files are an entirely different fieldmap.

For SE fieldmaps, the difference between dir-AP_epi and dir-PA_epi is only the PhaseEncodingDirection. The dir-<label> distinguishes between the two related files.

shouldn't dir- be allowed anywhere? there is nothing that says the opposite

There seem to be two views on entities; one focused on metadata richness while the other is focused on necessary distinctions, reducing filename lengths to exactly that needed to tell one file from another.

According to the rich metadata view, yes, any entity that is applicable to a file should be permissible. According to the necessary distinctions view, making available entities that are not needed to understand what a file is and how it's different from other files is just inviting users to add extraneous details into their filenames.

BIDS has generally (but not always) followed the necessary distinctions approach, which would be my estimation for why dir- is permitted for SE fieldmaps but not GRE fieldmaps (these decisions were made before I was a part of any discussions...).

---

Looking at your file listing:

├── sub-57460
│   ├── ses-1wkfollowup
│   │   └── fmap
│   │       ├── sub-57460_ses-1wkfollowup_acq-gre_dir-AP_run-1_magnitude1.json
│   │       ├── sub-57460_ses-1wkfollowup_acq-gre_dir-AP_run-1_magnitude1.nii.gz
│   │       ├── sub-57460_ses-1wkfollowup_acq-gre_dir-AP_run-1_magnitude2.json
│   │       ├── sub-57460_ses-1wkfollowup_acq-gre_dir-AP_run-1_magnitude2.nii.gz
│   │       ├── sub-57460_ses-1wkfollowup_acq-gre_dir-AP_run-1_phasediff.json
│   │       ├── sub-57460_ses-1wkfollowup_acq-gre_dir-AP_run-1_phasediff.nii.gz
│   │       ├── sub-57460_ses-1wkfollowup_acq-gre_dir-LR_run-1_magnitude1.json
│   │       ├── sub-57460_ses-1wkfollowup_acq-gre_dir-LR_run-1_magnitude1.nii.gz
│   │       ├── sub-57460_ses-1wkfollowup_acq-gre_dir-LR_run-1_magnitude2.json
│   │       ├── sub-57460_ses-1wkfollowup_acq-gre_dir-LR_run-1_magnitude2.nii.gz
│   │       ├── sub-57460_ses-1wkfollowup_acq-gre_dir-LR_run-1_phasediff.json
│   │       └── sub-57460_ses-1wkfollowup_acq-gre_dir-LR_run-1_phasediff.nii.gz
│   └── ses-Baseline
│       └── fmap
│           ├── sub-57460_ses-Baseline_acq-se_dir-AP_run-1_epi.json
│           ├── sub-57460_ses-Baseline_acq-se_dir-AP_run-1_epi.nii.gz
│           ├── sub-57460_ses-Baseline_acq-se_dir-AP_run-2_epi.json
│           ├── sub-57460_ses-Baseline_acq-se_dir-AP_run-2_epi.nii.gz
│           ├── sub-57460_ses-Baseline_acq-se_dir-PA_run-1_epi.json
│           ├── sub-57460_ses-Baseline_acq-se_dir-PA_run-1_epi.nii.gz
│           ├── sub-57460_ses-Baseline_acq-se_dir-PA_run-2_epi.json
│           └── sub-57460_ses-Baseline_acq-se_dir-PA_run-2_epi.nii.gz

There's redundant information. acq-gre/acq-se duplicate information in the file suffixes. run-1 in the GRE fieldmaps is redundant because there's no run-2. Consider:

├── sub-57460
│   ├── ses-1wkfollowup
│   │   └── fmap
│   │       ├── sub-57460_ses-1wkfollowup_acq-AP_magnitude1.json
│   │       ├── sub-57460_ses-1wkfollowup_acq-AP_magnitude1.nii.gz
│   │       ├── sub-57460_ses-1wkfollowup_acq-AP_magnitude2.json
│   │       ├── sub-57460_ses-1wkfollowup_acq-AP_magnitude2.nii.gz
│   │       ├── sub-57460_ses-1wkfollowup_acq-AP_phasediff.json
│   │       ├── sub-57460_ses-1wkfollowup_acq-AP_phasediff.nii.gz
│   │       ├── sub-57460_ses-1wkfollowup_acq-LR_magnitude1.json
│   │       ├── sub-57460_ses-1wkfollowup_acq-LR_magnitude1.nii.gz
│   │       ├── sub-57460_ses-1wkfollowup_acq-LR_magnitude2.json
│   │       ├── sub-57460_ses-1wkfollowup_acq-LR_magnitude2.nii.gz
│   │       ├── sub-57460_ses-1wkfollowup_acq-LR_phasediff.json
│   │       └── sub-57460_ses-1wkfollowup_acq-LR_phasediff.nii.gz
│   └── ses-Baseline
│       └── fmap
│           ├── sub-57460_ses-Baseline_dir-AP_run-1_epi.json
│           ├── sub-57460_ses-Baseline_dir-AP_run-1_epi.nii.gz
│           ├── sub-57460_ses-Baseline_dir-AP_run-2_epi.json
│           ├── sub-57460_ses-Baseline_dir-AP_run-2_epi.nii.gz
│           ├── sub-57460_ses-Baseline_dir-PA_run-1_epi.json
│           ├── sub-57460_ses-Baseline_dir-PA_run-1_epi.nii.gz
│           ├── sub-57460_ses-Baseline_dir-PA_run-2_epi.json
│           └── sub-57460_ses-Baseline_dir-PA_run-2_epi.nii.gz

Every piece of information in the filename is needed to distinguish it from a different file (apart from the required duplication of sub and ses in the filename and directory structure).

If you had dir-AP_phasediff and dir-PA_phasediff and they were intended to be analyzed together that would be a clear use case for increasing the applicability of dir-<label>.

---

Either way, the validator follows the spec and the spec says what are valid entities for each suffix. I'm going to move this issue to the spec for people to weigh in, if they want to change the scope of the entity.

[CPernet]

hey Chris, this is really informative on the philosophy of file naming - I don't think this appears transparently in the spec, I shall PR this -- and discuss it at the next steering meeting, thx for enlightening me :-)

note on my data, I do have run 2 and other stuffs, here we were checking with the code was not indexing files ...
note on entities, I maintain that there is nothing in the entity table that says it is specific to some file type but I agree it's a discrepancy to be resolved on the basis on the file naming philosophy you presented above 👍🏻