Fieldmaps with multiple phase encoded directions (topup)

[Bertrand Thirion]

-- Sorry, maybe this is more a user-level discussion and should go to neurostars ? --

I am having trouble validating fieldmaps obtained in a multiple phase encoded directions procedure: "sub-01_dir-j_epi.nii.gz" is not accepted by the validator. I haven't found examples with such fieldmaps, hence I have no clue. Any advice on this ?

Best,

Bertrand

[Oscar Esteban]

Hi Bertrand,

If I understand correctly, your fieldmaps should follow the following pattern (sec 8.9.4 of the BIDS specification): 

sub-<participant_label>­/

    fmap/

        sub­-<label>[_acq-<label>­]_dir-<index>­_epi.nii[.gz]

therefore, that filename would not be valid. I guess the easiest way to encode this is to name it just "sub-01_dir-0_epi.nii.gz" and write the encoding direction "j" in the sidecar json:

{

  "PhaseEncodingDirection": "j­",

  "TotalReadoutTime": 0.000095

}

In which the two parameters are compulsory.

HTH.

Cheers,

Oscar

--
You received this message because you are subscribed to the Google Groups "The Brain Imaging Data Structure (BIDS) discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bids-discussi...@googlegroups.com.
To post to this group, send email to bids-di...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/bids-discussion/cbfe9e32-d12d-4489-ba10-247d9c79a9d3%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

___________________________

Oscar Esteban, Ph.D.
Postdoctoral Fellow, Poldrack Lab
Stanford University

+1 (650) 733 33 82

[Bertrand Thirion]

Great, that worked, thx.

[Robert Smith]

Can I suggest that the example in the specification document be changed in the next update?
0.000095 (~0.1ms) seems unrealistic for a total EPI readout duration.
I'm trying to have my software grab this relevant information during DICOM import, and this stumbled me a bit at one point.

Rob

[Chris Gorgolewski]

Thanks for the suggestion. What would be a more realistic number?

To unsubscribe from this group and stop receiving emails from it, send an email to bids-discussion+unsubscribe@googlegroups.com.
To post to this group, send email to bids-discussion@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/bids-discussion/3dc42325-69bb-43cf-b143-4b5cc884c885%40googlegroups.com.

[Satrajit Ghosh]

it's off by an order of magnitude 1ms echo spacing with 96 echoes would result in a total readout time (per FSL) as 0.095 = (n - 1) * echo spacing.

[Chris Gorgolewski]

Thanks!  Fixed.

You received this message because you are subscribed to the Google Groups "bids-discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bids-discussion+unsubscribe@googlegroups.com.
To post to this group, send email to bids-discussion@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/bids-discussion/bc9863c8-7d92-48b6-a504-cc478802c183%40googlegroups.com.

[Chris Gorgolewski]

BTW I worked today on clarifying the language describing phase encoding fieldmaps. Please have a look and let me know what do you think 

https://docs.google.com/document/d/1HFUkAEE-pB-angVcYe6pf_-fVf4sCpOHKesUvfb8Grc/edit#heading=h.6gef31kvsx0l

Template:

sub-<participant_label>/[ses-<session_label>/]

fmap/

sub-<label>[_ses-<session_label>][_acq-<label>]_dir-<index>[_run-<run_index>]_epi.nii[.gz]

sub-<participant_label>/[ses-<session_label>/]

fmap/

sub-<label>[_ses-<session_label>][_acq-<label>]_dir-<index>[_run-<run_index>]_epi.json

This technique combines two or more Spin Echo EPI scans with different phase encoding directions. In such a case, the phase encoding direction is specified in the corresponding JSON file as one of: “i”, “j”, “k”, “i-”, “j-, “k-”. For these differentially phase encoded sequences, one also needs to specify the Total Readout Time defined as the time (in seconds) from the center of the first echo to the center of the last echo (see here and here how to calculate it). For example

{

   "PhaseEncodingDirection": "j-",

   "TotalReadoutTime": 0.000095,

   "IntendedFor": "func/sub-01_task-motor_bold.nii.gz"

}

Each dir-<index> should correspond to a single unique direction. Each file should be a 3D volume.  If there are instances of the same phase encoding direction acquired multiple times with the same scanning parameters (for example for different tasks) the optional run-<run_index> should be used to distinguish them. To indicate which run is intended to be used with which functional or diffusion scan the IntendedFor field in the JSON file should be used.

[Tibor Auer]

+1

What would be the valid values for “dir” in the filename? I would not call it “index”, because they do not code a position in a list but rather the direction itself, if I understand correctly.

 

Vale,

Tibor

 

Auer, Tibor M.D. Ph.D.

MRC Cognition and Brain Sciences Unit
15 Chaucer Road
Cambridge
CB2 7EF

United Kingdom

Phone/Work: +44-(0)1223-273613

Mail: Tibor...@mrc-cbu.cam.ac.uk

Thanks!  Fixed.

 

To view this discussion on the web visit https://groups.google.com/d/msgid/bids-discussion/bc9863c8-7d92-48b6-a504-cc478802c183%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

 

 

--

You received this message because you are subscribed to the Google Groups "bids-discussion" group.

To unsubscribe from this group and stop receiving emails from it, send an email to bids-discussi...@googlegroups.com.
To post to this group, send email to bids-di...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/bids-discussion/CAAQzouP-YPpkse7oHKNiLdR_5nvO-isJTOeToHYJQU5HqKP8uA%40mail.gmail.com.

[Chris Gorgolewski]

Most recent question from Tibor and before frome Bertrand highlight lack of clarity in the current description of this type of field maps.

To begin let me back up a little bit. Originally we have opted for numbering each image with different phase encoding direction in the filename in the following manner:

sub-01_dir-1_epi.nii.gz

sub-01_dir-2_epi.nii.gz

sub-01_dir-3_epi.nii.gz

sub-01_dir-4_epi.nii.gz

Importantly the neither the actual direction and polarity value nor the intended the scan a fieldmap in question is intended to be applied to was encode in the filename. This was due to two main reasons:

1. A single fieldmap can be intended to be applied to multiple or no scans.

2. We should avoid encoding parameter values in filenames where we can (see recent email from Cameron). Therefore the _dir- is just an index and the true phase encoding direction is in the corresponding json file (which answer Tibors email).

I have recently (after the release of 1.0.0) proposed adding the ability to specify runs of the same direction using the _run keyword. For example:

sub-01_dir-1_run-1_epi.nii.gz

sub-01_dir-1_run-2_epi.nii.gz

sub-01_dir-2_run-1_epi.nii.gz

sub-01_dir-2_run-2_epi.nii.gz

The more I think about this the less I am convinced about this idea. The problem is that when we split things into runs of unique directions it is only a step from specifying the direction in the filename (which as discussed in other emails on this list is not desirable). Thus I am more leaning towards retracting the _run keyword in context of _epi fieldmaps and sticking to the original proposal in which each acquisition (of a unique or already repeated direction) would require a new _dir- value. In other words if in your study you acquired 4 tasks with two short AP/PA  acquisition for generating fieldmaps you would end up with 8 _epi files numbered from _dir-1 to _dir-8. The phase encoding directions of the files as well as which DWI or fMRI scans there should be applied to would be encoded in the json file (this part does not change).

I'll work on improving the description on the spec. Let me know what do you think.

Best,

Chris

Thanks!  Fixed.

 

To unsubscribe from this group and stop receiving emails from it, send an email to bids-discussion+unsubscribe@googlegroups.com.
To post to this group, send email to bids-discussion@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/bids-discussion/bc9863c8-7d92-48b6-a504-cc478802c183%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "bids-discussion" group.

To unsubscribe from this group and stop receiving emails from it, send an email to bids-discussion+unsubscribe@googlegroups.com.
To post to this group, send email to bids-discussion@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/bids-discussion/CAAQzouP-YPpkse7oHKNiLdR_5nvO-isJTOeToHYJQU5HqKP8uA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--

You received this message because you are subscribed to the Google Groups "bids-discussion" group.

To unsubscribe from this group and stop receiving emails from it, send an email to bids-discussion+unsubscribe@googlegroups.com.
To post to this group, send email to bids-discussion@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/bids-discussion/670F727F5995114F973CBFCD758B5C0212512C0C%40wsr-ex-101.mrc-cbsu.local.

[Satrajit Ghosh]

hi folks,

chris asked me to describe our current approach to topup like fieldmaps.

in our current structure we are using the following:

$ ls ../../data/sub-PANDA025/fmap/

sub-PANDA025_acq-dwidir98_dir-AP_run-01_epi.json    sub-PANDA025_acq-func_dir-AP_run-01_epi.json

sub-PANDA025_acq-dwidir98_dir-AP_run-01_epi.nii.gz  sub-PANDA025_acq-func_dir-AP_run-01_epi.nii.gz

sub-PANDA025_acq-dwidir98_dir-PA_run-02_epi.json    sub-PANDA025_acq-func_dir-AP_run-03_epi.json

sub-PANDA025_acq-dwidir98_dir-PA_run-02_epi.nii.gz  sub-PANDA025_acq-func_dir-AP_run-03_epi.nii.gz

sub-PANDA025_acq-dwidir99_dir-AP_run-03_epi.json    sub-PANDA025_acq-func_dir-PA_run-02_epi.json

sub-PANDA025_acq-dwidir99_dir-AP_run-03_epi.nii.gz  sub-PANDA025_acq-func_dir-PA_run-02_epi.nii.gz

sub-PANDA025_acq-dwidir99_dir-PA_run-04_epi.json    sub-PANDA025_acq-func_dir-PA_run-04_epi.json

sub-PANDA025_acq-dwidir99_dir-PA_run-04_epi.nii.gz  sub-PANDA025_acq-func_dir-PA_run-04_epi.nii.gz

note that the acq and dir labels are used purely for semantic reasons, not to encode parameters. while the bids search tools are being built, this provides a quick mental route. however, the code is written to look at the json's and consider the intendedFor parameter to know which functional or diffusion runs these apply to.

since fieldmaps are sensitive to shimming and which dicom series have the same shims are hard to determine from the dicoms (if anyone knows, please let me know), we are currently manually noting this as a different dictionary and using it to fill the intendedFor parameter.

a search tool will eventually have to support grabbing files in both directions: given a run tell me where i can get fieldmap info from or given fieldmap files, what other things i can apply this to.

cheers,

satra

[Chris Gorgolewski]

I like the idea of allowing dir- to accept alphanumeric labels rather than just numbers. I just hope people will not use them instead of the "PhaseEncodingDirection" field in corresponding json files.

I am making gradual progress on pybids. I just added get_fieldmap() function which for a given file will return a corresponding fieldmap. Please have a look and let me know what do you think: https://github.com/INCF/pybids/pull/17

Best,

Chris

--

You received this message because you are subscribed to the Google Groups "bids-discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bids-discussion+unsubscribe@googlegroups.com.
To post to this group, send email to bids-discussion@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/bids-discussion/6dd0d79b-cc2c-4def-8b48-d4aa1190515c%40googlegroups.com.

[Chris Gorgolewski]

I was playing with some HCP data and I have to say the "sub-PANDA025_acq-dwidir99_dir-PA_run-04_epi.nii.gz" style formatting (instead of dir-1; JSON still will hold the PhaseEncodingDirection field) seems much more intuitive and readable. I would like to add it to the draft of the spec. Does anyone see any issues with this modification?

Best,

Chris

[Chris Gorgolewski]

On Mon, Sep 12, 2016 at 2:02 AM, Robert Smith <r.s...@brain.org.au> wrote:

Personally I'd be in favour of retaining the direction indices in the filename. On top of the concern that people may rely on the filename rather than the JSON entries:

• The phase encoding direction is constrained to lie upon an image axis; whereas LR / AP / IS are 'anatomical directions'. For a heavily off-axis acquisition, where the header transform is far from identity (even with axis permutations / flips), the appropriate anatomical designation for an image axis may become ambiguous. LR / AP / IS are also specific to human brain imaging: animal imaging (I think) more commonly uses dorsal/ventral.

Of course - but no one is claiming this label should be used to determine the phase encoding direction. 

• There was an example somewhere (don't recall whether it was in a publication or in the FSL documentation somewhere) where two EPI images with the same phase encoding direction but different bandwidths were used to estimate the inhomogeneity field. Even if it's not a likely scenario, this contrast would not be sufficiently encoded in the filename: You'd have to label them as different 'runs' of the same direction, which would therefore erroneously appear to a user as 'repeats of the same phase encoding acquisition'.

Sorry I don't quite follow. Again - the idea isn't to encode any parameters in the filename. 

• The biggest delay in getting my BIDS app working has been EPI susceptibility distortion correction. Because a priori the script doesn't know what type of DWI acquisition / EPI field-mapping acquisition has taken place, this needs to be determined based on the images (& associated JSONs) present; which means importing all available field-mapping image data and then figuring out what the phase encoding contrast is. In this case, it makes more sense to be looping through images that have different 'direction' indices and then figuring out what to do with them based on the data, rather than having to e.g. glob your way through the directory contents.

I'm afraid you will have to loop over all fieldmaps for a given participant independently if the dir is constrained to numbers or extended to alphanumeric labels. I implemented this in pybids: https://github.com/INCF/pybids/blob/master/bids/grabbids/bids_layout.py#L62

This is the text I put in the spec:

"dir_label value can be set to arbitrary alphanumeric label ([a-zA-Z0-9]+ for example “LR” or “AP”) that can help users to distinguish between different files, but should not be used to infer any scanning parameters (such as phase encoding directions) of the corresponding sequence. Please rely only on the JSON file to obtain scanning parameters. _epi files can be a 3D or 4D - in the latter case all timepoints share the same scanning parameters.  To indicate which run is intended to be used with which functional or diffusion scan the IntendedFor field in the JSON file should be used."

Please also mind that the validator still checks for presence of the PhaseEncodingDirection in the JSON file and raises an error if this is not present.

Best,

Chris

 

Rob

To unsubscribe from this group and stop receiving emails from it, send an email to bids-discussi...@googlegroups.com.
To post to this group, send email to bids-di...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/bids-discussion/6dd0d79b-cc2c-4def-8b48-d4aa1190515c%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "bids-discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bids-discussion+unsubscribe@googlegroups.com.
To post to this group, send email to bids-discussion@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/bids-discussion/d5c2140f-2452-4178-95ec-bcb0fa8e611c%40googlegroups.com.

[Chris Gorgolewski]

On Tue, Sep 13, 2016 at 12:34 AM, Robert Smith <r.s...@brain.org.au> wrote:

> Of course - but no one is claiming this label should be used to determine the phase encoding direction.

Sure; but for the sake of another example: the phase encoding direction indicated in the filename could be outright wrong, and the validator would have no choice but to label the dataset as BIDS-conforming, since that field only needs to be unique, not correct. So by trying to make the file names more user-readable, it may just introduce a potential source of error if a user manipulates that data manually (which may not be possible in your BIDS-Apps interface, but BIDS-Apps is not the only use case of BIDS).

True, but this is a rather edge case where the filename suggests a phase encoding that is incorrect while the one stored in the JSON file is correct. It's much more likely that the phase encoding direction in the JSON file would be incorrect - in which case even if we index directions with plain numbers we would have a problem.

  

> Sorry I don't quite follow. Again - the idea isn't to encode any parameters in the filename.

An example EPI field-mapping experiment would be one volume with A>>P phase encode direction and 0.1s readout time, and one volume with P>>A phase encode direction and 0.1s readout time. So in this case, your file naming might be "sub-01_dir-AP_epi.nii.gz" and "sub-01_dir-AP_epi.nii.gz", where the old naming would have been "sub-01_dir-1_epi.nii.gz" and "sub-01_dir-2_epi.nii.gz". But now consider if your acquisition protocol consists of one volume with A>>P phase encode direction and 0.1s readout time, and one volume also with A>>P phase encode direction but 0.2s readout time. These data are perfectly valid for estimating the inhomogeneity field; but how would you name them, given the phase encoding direction is the same? You'd likely have to resort to "sub-01_dir-AP_run-1_epi.nii.gz" and "sub-01_dir-AP_run-2_epi.nii.gz". But now those two images look like two 'runs' of the same 'protocol', when in fact the protocol differs between the two due to the varying readout time. Again, it's not a likely realistic use case, and in all cases they're just file names and the JSON data would need to be used; I'm just using it to highlight how permitting anything other than unique integer identifiers may only introduce potential for errors.

This could be done with:

sub-01_dir-AP1_epi.nii.gz

sub-01_dir-AP2_epi.nii.gz

but the labels really do not matter as long as the JSON files are correct.

 

As an aside: When using a web interface (or any equivalent script) to store raw data as BIDS, I would imagine that keeping an integer counter and naming uploaded fmap images based on that counter would be easier and more robust than attempting to assign a unique name to each image based on phase encoding direction. So permitting deviations from that 'standard' is effectively inviting users to manually edit their BIDS file names for their own readability, which may be a bad precedent to set: Just because you can, doesn't mean you should.

Remember that within this scheme the dir label can still be a number - so if you want to use number you still can. Added flexibility of human readable labels will make the files easier to identify during manual inspection. Try this on one of your datasets (I did this recently with HCP example): index the directions with numbers vs indexing them with human readable labels and see which feels better. At the end it's not that much of a choice, since everything is in the JSON files.

I'd be content with the change; just raising the counter argument since I think it's what I'd personally opt for if it were my choice alone.

Glad to hear that - I don't think this is something worth splitting hairs about!

Best,

Chris 

Rob

To view this discussion on the web visit https://groups.google.com/d/msgid/bids-discussion/d5c2140f-2452-4178-95ec-bcb0fa8e611c%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "bids-discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bids-discussion+unsubscribe@googlegroups.com.
To post to this group, send email to bids-discussion@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/bids-discussion/11f3776c-8d09-4e8d-aef3-6a794b55cbe4%40googlegroups.com.