BIDS convention naming of topup+eddy corrected data

[tashrifbillah]

Hi all, I would like to know your opinion about BIDS convention naming of topup+eddy corrected data of the following two:

sub-2001_ses-1_acq-AP_dir-99_desc-XcUn_dwi.nii.gz
sub-2001_ses-1_acq-PA_dir-99_desc-XcUn_dwi.nii.gz

• when one set of volume is corrected, we name the output:

  sub-2001_ses-1_dir-99_desc-XcUnEdEp_dwi.nii.gz^1,2

  (_dir-99 is preserved)

• when both volumes are corrected, we name the output:

  sub-2001_ses-1_dir-198_desc-XcUnEdEp_dwi.nii.gz^1,2

  (_dir-99 is doubled hence _dir-198)

  The other candidate could be to drop _dir-* completely because the reader already knows about topup+eddy correction step from _desc-XcUnEdEp.

---

¹ The rationale for dropping _acq-* is that acquisition direction-specific distortion has been corrected by topup.
² Addition of EdEp string after _desc-XcUn signals that topup+eddy correction has been done.

@effigies @mgxd @sbouix @yrathi

[mgxd]

I haven't worked with DWI in BIDS much yet, but at first glance I think summing dir entities is grounds for confusion and should be avoided.

I think what would be most beneficial here is a sense of run. Looking at the diffusion specification, it could look like:

sub-2001_ses-1_acq-99_dir-AP_run-1_desc-XcUn_dwi.nii.gz
sub-2001_ses-1_acq-99_dir-PA_run-2_desc-XcUn_dwi.nii.gz

then, if you correct 1 volume, you can keep the run entity, and when you are merging volumes, drop it altogether. Besides naming, JSON sidecars would be most beneficial.

[tashrifbillah]

I think summing dir entities is grounds for confusion

Can you explain why?

[mgxd]

It is unclear whether the file is a processed derivative of sub-2001_ses-1_dir-198_dwi.nii.gz or 2 (or more) separate files.

Also, it seems you have the acq/dir entities switched:

The OPTIONAL acq- key/value pair corresponds to a custom label the user may use to distinguish different sets of parameters.

The OPTIONAL dir- key/value pair corresponds to a custom label the user may use to distinguish different sets of phase-encoding directions.

[effigies]

Edit: Removed bit because I didn't realize @mgxd had posted the original spec link, and also answered your question already.

Just as a note, the next relevant section is Derivatives - File naming conventions.

Each Derivatives filename MUST be of the form: <source_entities>[_keyword-<value>]_<suffix>.<ext> (where <value> could either be an <index> or a <label> depending on the keyword; see Definitions).

I'm trying to find the text¹, but there should be a rule that says you can drop source entities when they no longer apply to a file.

---

Re the original filenames, what does XcUn mean? Are these already derivatives?

sub-2001_ses-1_acq-AP_dir-99_desc-XcUn_dwi.nii.gz
sub-2001_ses-1_acq-PA_dir-99_desc-XcUn_dwi.nii.gz

---

¹ Here is the text:

One exception to this rule is filename entities that are no longer relevant.

[tashrifbillah]

Re the original filenames, what does XcUn mean?

Xc: axis alignment
Un: Gibbs unringing

Are these already derivatives?

Yes. After each process, we have appended a string to _desc-* to indicate the process that was done.

The above is consistent with the following of the linked source:

When necessary to distinguish two files that do not otherwise have a distinguishing entity, the _desc- keyword-value SHOULD be used.

[effigies]

Got it. I think I agree with @mgxd's assessment, overall. Use dir- for PE direction. I'm not sure if acq- is buying you much unless you have different acq-s. Editing acq- downstream breaks the visual connection with the source images.

As I'm also not very familiar with diffusion techniques, if there are remaining questions, it might be a good idea to ping the BIDS-DWI community (I'd probably ask on https://neurostars.org) who may have seen similar sequences and have good suggestions.

Also:

[tashrifbillah]

Just for our mental peace--is the acq and dir specification new? We have been naming as above for more than a year and I am not sure how we switched them!

[effigies]

The acq- text has been there since 1.2.0 at least, but dir was added in 1.5.0 to match the text in functional and fieldmap data. This was intended as a clarification, not a change in meaning, and I guess we're finding out that it was indeed unclear.