Phase encoding scheme handling
==============================

From version 3.0RC1 onwards, *MRtrix3* is capable of importing information from
DICOM relating to the phase encoding of the acquired images, and encoding this
information within key-value fields inside an image header. This information can
then later be used by the ``dwifslpreproc`` script, specifically using its
``-rpe_header`` command-line option, to automatically set up and execute FSL's
``topup`` and ``eddy`` commands without requiring explicit input from the user
regarding the phase encoding design of the imaging experiment. This page
explains how this information is encoded and manipulated by *MRtrix3*.


.. NOTE::

    Due to variations in sequences, acquisition protocols, DICOM encoding, and
    image manipulation operations, *MRtrix3* cannot be guaranteed to obtain or
    retain the phase encoding information correctly in all circumstances. Manual
    inspection of these data and/or the outcomes of image processing when making
    use of these data is advocated. If circumstances leading to incorrect import
    or encoding of this information in *MRtrix3* is reproducible, please report
    this to the *MRtrix3* developers so that the software can be updated to
    support such data.


Phase encoding information storage
----------------------------------

The phase encoding information for a particular image file can be stored in one
of two ways.

-  The most convenient of these is storage of (one or more) key-value field(s)
   encapsulated within the image header, just as can be used for
   the diffusion gradient scheme. This ensures that the information
   is retained through image processing, as each *MRtrix3* command passes the
   header entries of the input image through to the output image.

-  Alternatively, this information can be stored within a JSON file that
   accompanies the relevant image file(s). This information would then typically
   be imported / exported using the ``-json_import`` and ``-json_export`` options
   in ``mrconvert``.

Precisely *how* this phase encoding information is *encoded* however depends on
the nature of the phase encoding information for that image; specifically,
whether the phase encoding information is *identical* for all volumes within an
image file (or if it contains just one volume), or whether the phase encoding
information *varies* between volumes within the image series.


Fixed phase encoding
....................

In the case where both the phase encoding *direction* and the EPI *total readout
time* are equivalent for all volumes within an image, this information is encoded
within two fields: "``PhaseEncodingDirection``" and "``TotalReadoutTime``". These
fields are consistent with `BIDS
<http://bids.neuroimaging.io/>`_ (the Brain Imaging Data Structure).

``PhaseEncodingDirection`` can take one of six values: "``i``", "``i-``", "``j``",
"``j-``", "``k``", "``k-``". These correspond to the first, second and third axes of
the corresponding image. Exactly how these axes map to "real" / "scanner" space
axes (i.e. left-right, posterior-enterior, inferior-superior) depends on the
:ref:`transform` that is stored in the respective image header, which may
potentially have been modified internally by *MRtrix3* on image load (discussed
further in the :ref:`non_axial_acquisitions` section). Here, we begin with the most simple
use case:

Take an image that conforms to the RAS (Right-Anterior-Superior) convention common
to both NIfTI and *MRtrix3*. If the phase encoding is applied ``A>>P``
(anterior-posterior), this is the *second* spatial axis, or axis "``j``". However,
the phase encoding is also *reversed* along that axis ("RAS" indicates that voxel
positions along the second axis *increase* when moving toward the anterior of the
brain, whereas "``A>>P``" indicates the opposite). Hence, in this example,
``PhaseEncodingDirection`` would have the value "``j-``".

.. NOTE::

    The phase encoding direction is defined specifically with respect to *image
    axes*. It is therefore *not* affected by the image *strides*, which only affect
    how the data for these axes are arranged when they are stored as a
    one-dimensional list of values within a file.

.. NOTE::

    The phase encoding direction does *not* relate to "``x``", "``y``" and
    "``z``" axis directions in "real" / "scanner" space, as do other
    representations of orientation information in *MRtrix3*. This is because phase
    encoding specifically affects the appearance of the image *along the image axis
    in which phase encoding was applied*. The mapping from image axes to real-space
    axes is determined by the image header transform.

    To demonstrate this: Imagine if an EPI image were to undergo a rigid-body
    rotation. The EPI field inhomogeneity distortions would *still align* with the
    relevant image axis after this rotation; but the effective ``x-y-z`` direction
    of phase encoding in real-space would change.

``TotalReadoutTime`` provides the total time required for the EPI readout train.
Specifically, this is the time between the centre of the first echo, and the centre
of the last echo, in the train; this is consistent with BIDS, and is sometimes
referred to as the "FSL definition", since it is consistent with relevant
calculations performed within FSL tools. It should be defined in seconds.

Variable phase encoding
.......................

If the phase encoding direction and/or the total readout time varies between
different volumes within a single image series, then the two key-value fields
described above are not sufficient to fully encode this information. In this
situation, *MRtrix3* will instead use a key-value entry "``pe_scheme``" (similar to
the "``dw_scheme``" entry used for the diffusion gradient scheme).

This information is stored as a *table*, where each row contains the phase encoding
direction and the readout time for the corresponding volume; the number of rows in
this table must therefore be equal to the number of volumes in the image. In each
row, the first three numbers encode the phase encoding direction, and the fourth
number is the total readout time. The direction is specified as a unit direction in
the image coordinate system; for instance, a phase encoding direction of A>>P would
be encoded as ``[ 0 -1 0 ]``.

Note that while this format closely resembles the interface by which the FSL
software is provided with phase encoding information, particularly the ``topup``
command, there is a subtle distinction relating to the way in which the FSL
software interprets image data. The contents of this field should therefore *not*
be interfaced with directly if the goal is to pass data to/from the FSL software;
the ``-import_pe_topup`` and ``-export_pe_topup`` options should instead be used
(see manipulation_of_phase_encoding_data_ below).

.. _non_axial_acquisitions:

Non-axial acquisitions
----------------------

When images are acquired in such a manner that the axes do not approximately
correspond to RAS convention (i.e. first axis increases from left to right, second
axis increases from posterior to anterior, third axis increases from inferior to
superior), *MRtrix3* will automatically alter the axis :ref:`strides` & transform
in order to make the image *appear* as close to an axial acquisition as possible.
This is briefly mentioned in :ref:`transform` section. The behaviour may
also be observed by running ``mrinfo`` with and without the
``-config RealignTransform false`` option, which temporarily disables this behaviour.

Because phase encoding is defined with respect to the image axes, any
transformation of image axes must correspondingly be applied to the phase encoding
data. When the phase encoding information is stored within the image data,
*MRtrix3* should automatically manipulate such phase encoding information in order
to maintain correspondence with the image data.

Where management of such information becomes more complex and prone to errors
is when it is included in the sidecar information of a JSON file, e.g. as is
commonly now utilised alongside NIfTI images such as in the BIDS format. This
becomes more complex at both read and write stages, each in their own complex way.

1. When *reading* a JSON file, *MRtrix3* will take the transformation that was
   applied to the corresponding input image, and apply that to the phase encoding
   information.

   This has two curious consequences:

   1. Running::

         mrconvert image.nii -json_import image.json - | mrinfo - | grep PhaseEncodingDirection

      and::

         cat image.json | grep PhaseEncodingDirection

      *may produce different results*. This is because once imported via the
      ``-json_import`` option, the phase encoding direction is altered to
      reflect *how MRtrix3 interprets the image data*, rather than how they
      are actually stored on file.

   2. Running::

         mrconvert image.nii - | mrconvert - -json_import image.json image.mif

      *may produce the incorrect result*. This is because information regarding
      the transformation that is applied to the NIfTI image in the *first*
      ``mrconvert`` call in order to approximate an axial acquisition is
      *no longer available* in the *second* ``mrconvert`` call. When the
      ``-json_import`` command-line option is used, it is interpreted with
      respect to the input image *for that command* - which, in the above case,
      is an MRtrix piped image to which the axial transformation has
      *already been applied* - and so must *always* be used immediately in
      conjunction with loading the image with which that JSON file is associated.

2. When *writing* a JSON file, *MRtrix3* will attempt to modify the phase
   encoding information in order to conform to the limitations of the output
   image format alongside which the JSON file is intended to reside.

   Unlike the :ref:`mrtrix_image_formats`, :ref:`nifti_format` do not support
   arbitrary image strides. When writing image data with non-trivial strides to
   a NIfTI image, *MRtrix3* will reorder the three spatial axes in order to
   approximate an axial alignment, performing the corresponding modifications
   to the image transform. Any exported JSON file must therefore also have the
   same transformation applied.

   This has the curious consequence that::

      mrconvert input.mif output.mif -json_export output.json
      cat output.json | grep PhaseEncodingDirection

   and::

      mrconvert input.mif output.nii -json_export output.json
      cat output.json | grep PhaseEncodingDirection

   *may produce different results*. A JSON file *must* only be interpreted in
   conjunction with the singular image file alongside which it was generated.
   In the case of the MRtrix image format, we suggest relying instead on the
   storage of sidecar information within the :ref:`header_keyvalue_pairs`
   rather than in such an external file, as it allows *MRtrix3* to apply any
   requisite modifications to such data to echo modifications to the image
   without user intervention.

.. NOTE::

   This concept also has consequences for the ``dwifslpreproc`` script when manually
   providing the phase encoding direction. The axis and sign of phase encoding
   provided to the script must reflect the direction of phase encoding *after*
   *MRtrix3* has performed this transformation, i.e. as it is read by any
   *MRtrix3* command or as it appears in ``mrview``, *not* the actual encoding
   of axes within the file.


.. _manipulation_of_phase_encoding_data:

Manipulation of phase encoding data
-----------------------------------

The primary purpose of storing this phase encoding information is to automate the
correction of EPI susceptibility distortions. However this can only occur if the
information stored is not invalidated through the manipulation of the corresponding
image data. Therefore, any *MRtrix3* command that is capable of manipulating the
image data in such a way as to invalidate the phase encoding information will
*automatically* modify this phase encoding information appropriately. This includes
modifying the representation of this information between the fixed and variable
phase encoding cases.

Consider, for instance, a pair of b=0 images, where the first was acquired with
phase encoding direction ``A>>P``, and the second was acquired using phase encoding
direction ``P>>A``::

    $ mrinfo AP.mif
    ******************************
    Image:            AP.mif
    ******************************
      ...
      PhaseEncodingDirection: j-
      TotalReadoutTime:  0.0575
      ...

    $ mrinfo PA.mif
    ******************************
    Image:            PA.mif
    ******************************
      ...
      PhaseEncodingDirection: j
      TotalReadoutTime:  0.0575
      ...

Now watch what happens when we concatenate these two images together::

    $ mrcat AP.mif PA.mif AP_PA_pair.mif -axis 3
    mrcat: [100%] concatenating "AP.mif"
    mrcat: [100%] concatenating "PA.mif"
    # mrinfo AP_PA_pair.mif
    ******************************
    Image:            AP_PA_pair.mif
    ******************************
      ...
      pe_scheme:     0,-1,0,0.0575
                     0,1,0,0.0575
      ...

When the two input images are concatenated, *MRtrix3* additionally concatenates the
phase encoding information of the input volumes; since it detects that these are not
consistent between volumes, it stores this information using the ``pe_scheme`` header
entry, rather than ``PhaseEncodingDirection`` and ``TotalReadoutTime``.

The ``mrconvert`` command has a number of additional functionalities that can be used
to manipulate this information:

-  The ``-import_pe_table`` and ``-export_pe_table`` options can be used to
   import/export the phase encoding information from / to file as a table, i.e. in
   the format used for the ``pe_scheme`` header entry described above. Note that even
   if all volumes in the image have the same phase encoding direction and total
   readout time, these options will still import / export these data in table format.

-  The ``-import_pe_topup`` and ``-export_pe_topup`` options can be used to
   import/export the phase encoding information in the format required by FSL's
   ``topup`` tool. While this may look identical to the phase encoding table as stored
   in the ``pe_scheme`` header entry and passed using the ``-import_pe_table`` and
   ``-export_pe_table``, the two are not always equivalent;
   see reference_axes_for_phase_encoding_directions_ below.

-  The ``-import_pe_eddy`` and ``-export_pe_eddy`` options can be used to
   import/export the phase encoding information in the format required by FSL's
   ``eddy`` tool. The `FSL documentation page <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A--acqp>`_
   describes this format in more detail. This format takes into account the possible
   flipping of the first image axis in the same way as do the ``-import_pe_topup`` and
   ``-export_pe_topup`` options as described in
   reference_axes_for_phase_encoding_directions_ below.

-  The ``-json_import`` and ``-json_export`` options can be used to import/export
   *all* header key-value entries from/to an external JSON file. This may be useful
   in particular for operating within the BIDS specification. There is a caveat here:
   If you use the ``-json_export`` option on an image with *fixed* phase encoding,
   the ``PhaseEncodingDirection`` and ``TotalReadoutTime`` fields will be written as
   expected by BIDS; however if the image contains *variable* phase encoding, then
   the ``pe_scheme`` header entry will be written to the JSON file, and this will not
   be appropriately interpreted by other BIDS tools.

-  The ``-set_property`` option may be useful to *override* these header entries if
   they are deemed incorrect by some other source of information.

.. _reference_axes_for_phase_encoding_directions:

Reference axes for phase encoding directions
--------------------------------------------

Whether a phase encoding direction is encoded via BIDS field ``PhaseEncodingDirection``
or using the *MRtrix3*-specific metadata key ``pe_scheme``,
these directions are defined with respect to the image axes as-is.
This is however *not* the case for the FSL software:
similarly to the ``bvecs`` / ``bvals`` format for diffusion gradient tables,
FSL uses as the basis for interpretation of phase encoding directions
its own internal coordinate system.
This system is *sometimes*, but *not always*,
equivalent to the image axes as encoded by the image header transform.
This equivalence depends on the "*handedness*" of that transform:

-  A "*left-handed*" coordinate system
   is one where if the positive direction of the first image axis
   is indicated with one's left thumb,
   and the positive direction of the second image axis
   is indicated with one's left index finger,
   then the direction of the left middle finger
   when placed at right angles to the first two
   indicates the positive direction of the third image axis.
   Mathemtically, it is stated that the *determinant* of the transform is *negative*.
   In this circumstance,
   the phase encoding directions encoded by the file formats
   here attributed to the "`topup`" and "`eddy`" commands
   *do* correspond to the image axes as stored on disk.

-  The converse situation is an image with a "*right-handed*" coordinate system /
   a positive determinant.
   Notably, the "RAS" (right-anterior-superior) coordinate system
   used both by the NIfTI image format and the *MRtrix3* software
   is intrinsically right-handed.
   When FSL reads such an image,
   it performs an internal re-interpretation
   that is equivalent to having flipped the image along the first axis.

.. note:: It is the handedness of the image transform that is *stored on disk*
   that matters here,
   *not* *MRtrix3*s *interpretation* of those data:
   in the absence of use of "RealignTransform: false" in an MRtrix config file
   or the use of command-line option "``-config RealignTransform false``",
   *MRtrix3* will interpret *every* image as right-handed,
   as it *explicitly* alters its interpretation of the image data
   in order for this to be the case.

This is consequential in the definition of phase encoding directions
within external metadata files.
If an image has a *left*-handed transform,
then the image axes as stored and the FSL interepretation of those image axes
are equivalent,
and therefore the BIDS / *MRtrix3* and FSL interpretation of phase encoding directions
are also equivalent.
For an image with a *right*-handed transform this is however not the case.
FSL's re-interpretation of such images,
in a manner equivalent to having flipped the first image axis,
is *not* reflected in its interpretation of phase encoding metadata.
As such, phase encoding directions
defined in metadata text files intended for interfacing with FSL
need to be defined with respect to *how FSL will interpret the image*
rather than the image itself.

This distinction is the reason why,
from version 3.0.8 of the *MRtrix3* software,
there are separate command-line options ``-import_pe_topup`` and ``-export_pe_topup``
in contrast to ``-import_pe_table`` and ``-export_pe_table``.
The appropriate command-line option needs to be chosen
based on which of these interpretations should be applied.
This in turn may in turn depend on where those data have come from
or the reason for which the data are being exported to text file.

Unfortunately, it is *not* possible to determine
which of these two conventions a given metadata file conforms to
based exclusively on the context of the text file.
In both scenarios,
the corresponding text file contains four columns,
with the first three columns providing a one-hot encoding of phase encoding direction
and the fourth column providing the total readout time.
It is only the *interpretation* of the stored phase encoding direction
that differs between the two conventions.
Ensuring that such metadata are appropriately *generated* and *interpreted*,
both by *MRtrix3* and other neuroimaging softwares,
is up to the diligence of the user.

(While it is true that *MRtrix3* will write a comment at the head of the text file
providing the string of the command used to generate that file
*only* for the ``-export_pe_table`` option and *not* for the ``-export_pe_topup`` option,
the presence of such content should *not* be interpreted on its own as a robust marker
of which set of references axes should be used
in interpretation of the contained phase encoding data)

Options ``-import_pe_eddy` and ``-export_pe_eddy``
involve storing the phase encoding information in a slightly different format,
but the interpretation of the phase encoding directions contained within
have the same confound with respect to image transform handedness
as does the format interfaced by the ``-import_pe_topup`` and ``-export_pe_topup`` options.