Non-standard fMRI Orientation Must Be Fixed or an Error

[glasserm]

#139 Implemented fslreorient2std in fMRI data but limited it to those datasets where no distortion correction was going to be applied. Recently I was working with a collaborator on an HCP-Style GE acquired dataset where the NIFTI files were upside down in FSL (I believe in RAS convention). This led to multiple fMRI runs not being aligned correctly (trapped in a local minimum upside down). It was stated in #139 that fslreorient2std would break distortion correction; however, I am not sure that is the case (assuming the labels actually match the data). Can someone explain why this is wrong? If it does break distortion correction, the pipeline cannot accept data that is upside down--we cannot expect it to reliably fix the data in these settings and so it should error.

[mharms]

The point that I was making in #139 is that you can't just throw in an fslreorient2std at the front end and assume all else is fine. As regards the distortion correction, you need to assess whether the orientation was actually changed, and if so, then UnwarpDir inside fMRIVolume needs to be adjusted appropriately as well. And to be robust, would need to check/confirm that the SEFMs need reorienting as well. And changes might be necessary in the case of gradient echo field maps as well.

And if STC is being used then the change of orientation needs to be accounted for there as well.

In principle, this could all be done internally to fMRIVolume, but it would take some careful thought.

[glasserm]

What kind of changes do you think would occur to unwarpdir? This is not the kind of reorientation that changes the labels vs the anatomical axes of the image. For the GE data case, there was no adjustment to UnwarpDir needed.

[mharms]

UnwarpDir is specified relative to the voxel axes (ijk) -- i.e., the order in which the planes are stored in the NIFTI, and the polarity matters as well. Any fslreorient2std operation that changes either the axis corresponding to the phase encoding axis, or its polarity, will need a corresponding change in UnwarpDir. What is the GE example for which this wasn't necessary?

[glasserm]

Not sure about polarity, but I doubt fixing the orientation would otherwise break things. In any case, with these sort of complicated situations, one will have to use trial and error anyway to figure out the polarity. As the pipelines currently stand they will produce broken results for data that need fslreorient2std run on them, whereas at least some of the time the results would be correct if it were run. I don't have the data, but it was acquired within the last month on a GE scanner with an HCP-Style protocol.

[mharms]

If UnwarpDir is properly specified against the orientation of the input volume in ijk axes (as the pipelines currently call for; not the reoriented orientation), then applying fslreorient2std indeed breaks the distortion correction. If you want to redefine UnwarpDir to reflect the unwarping direction relative to anatomical labels, that is technically a big change in behavior.

I seems reasonable to me to have fMRIVolume check the orientation and generate an error, with an appropriately informative message, if the input isn't already LAS or RAS oriented, thereby putting the burden on the user to provide appropriately oriented inputs.

[glasserm]

I still don't understand an example situation where this would create a problem. As far as I know, UnwarpDir has always referred to the anatomical labels. It is specified as xyz and it would take quite some creative thinking to make those not refer to medial-lateral, anterior-posterior, and superior-inferior.

We work in LPI and RPI not LAS or RAS.

[mharms]

The FSL tools are technically based on the image axes, not the anatomical labels. To the extent that xyz are allowed as valid entries in any of those tools, or the HCPpipelines, that is technically inaccurate, and the likely source of the confusion on this very issue.

FWIW, I consider the space we work in to be LAS/RAS, since I believe the more typical usage historically has been to label the orientation based on the increasing index direction. e.g., the following all adopt that "convention":

https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Orientation%20Explained
http://www.grahamwideman.com/gw/brain/orientation/orientterms.htm
https://nipy.org/nibabel/image_orientation.html

Unfortunately, I think FreeSurfer adopted the convention of describing the orientation via the decreasing index direction.

[glasserm]

One would have to mentally translate what they set on the scanner into a strange coordinate system if one does not use fslreorient2std. I would expect setup errors to be more likely attempting to use the HCP Pipelines without fslreorient2std than with it, and any images that need this step are unlikely to be robustly processed in any case. I'm still not seeing the case where the current behavior is a good idea.

FreeSurfer's convention is the opposite of ours.

[mharms]

Here are example of the confusion that unfortunately exists in FSL around this issue:
From https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FUGUE/Guide:

--unwarpdir=dir

specifies the direction of the unwarping/warping - i.e. phase-encode direction - with dir being one of x,y,z,x-,y-,z- (default is y).
Note: the conventions for x, y and z are voxel axes (in the input image), but with the x-axis being swapped if the qform or sform determinant is positive (to match the internal FSL voxel coordinate axes), though due to other possible changes in the pipeline for reconstructing/analysing both the EPI and fieldmap images, it is usually necessary to determine the sign of the direction by trial-and-error once for each scanning/reconstruction/analysis protocol (each dataset using the same protocol will need the same unwarpdir). 

https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FEAT/UserGuide#Pre-Stats:

You also need to specify the Unwarp direction, which is the phase-encoding direction of your FMRI EPI data (using voxel axes).

Note that both descriptions mention that the specification is in terms of the voxel axes. The use of xyz by FSL in this context is historically unfortunate.

[mharms]

Regarding your earlier comment, at this point the ecosystem is designed around the technical specification of UnwarpDir reflecting the ijk voxel axis. e.g., QuNex obtains the UnwarpDir value from the PhaseEncodingDirection field in the dcm2niix sidecar json if it isn't otherwise specified, which is an ijk voxel axis specification.

That's why I think the safest path forward at this point is to just generate an error if the orientation of the inputs aren't LAS/RAS :)

[coalsont]

If the SE fieldmaps and the BOLD have the same orientation before the reorient2std, then the same axis flips/swaps apply to both. If they are only flips, then something like "j-" should result in the same distortion warpfield before and after the flips (though technically it confounds both increased versus decreased field strength and direction (which we don't attempt to disambiguate in the pipelines anyway), but with both things reversed, you get the same displacement in real mm).

Yes, we could tell the user they need to manually run fslreorient2std and think about the phase direction again, but that isn't much different than automatically running fslreorient2std and the current "try it and see if it works" approach for the phase direction argument. In fact, WITH fslreorient2std, "x, y, z" in the FSL distortion correction tools actually will match the anatomical directions (with a possible sign flip), whereas without it, they might not, so that confusion is currently increased by not running fslreorient2std.

There isn't an ideal solution, but other than STC (which we don't do in our data, and the reorient usually doesn't need to swap the third dimension anyway), the end result is generally that running fslreorient2std is better than not, and the question is whether we should yell at the user to do it themselves, or do it for them.

wb_command -file-information can report orientation (even on oblique or skew volumes), though it is a bit verbose (note: I ran it on a strange orientation I previously generated for testing purposes):

...
Orientation[0]:           Superior to Inferior
Orientation[1]:           Right to Left
Orientation[2]:           Posterior to Anterior
...

[glasserm]

We discussed and Grega's current plan is to implement something that makes it an error to run the HCP Pipelines on incorrectly oriented data. Mike's point is that fully automated tools might not work with coronal or sagittal EPI (where unwarpdir is set based on a dcm2niix output and not by the user); however, these are fairly rare.

[mharms]

@coalsont : We can treat STC as a separate issue, but the data that Matt saw that prompted this whole thing was flipped on the S/I axis. fslreorient2std on that wouldn't need to swap axes, but it would change the "increasing index" direction on the 3rd dimension, and that would need to be accounted for as part of STC or otherwise the STC would be completely wrong.