I might initially go on a bit of a tangent on this one; I promise it’ll come around to answer the question, but I’m hoping it’ll give anyone curious a better understanding of how I made this all work.
dwipreproc has been basically re-written from scratch, largely due to the requirements of being able to handle any arbitrary input data without user interaction for the BIDS apps (now published). In such a use case, we can no longer rely on a user informing the script of the phase encoding design of the acquisition, therefore such information must be determined from the data.
3,0_RC1, in addition to a diffusion weighting table, it is also possible for image volumes to have stored in the header a phase encoding table. This captures the direction of phase encoding, and the total readout time, for each volume, just like the
topup “configuration file”. When importing from DICOM, MRtrix3 will now read the appropriate entries, generate this table, and store it in the image header.
(Note that while BIDS defines fields for storing phase encoding direction and readout time, it doesn’t have the capacity for storing a 4D image where the phase encoding direction / readout time varies between volumes)
Now, when you run
dwipreproc with the new
-rpe_header option, it examines the phase encoding table in the image header, and sets up e.g. the
eddy calls appropriately based on this information. This occurs quite differently to how the
dwipreproc script used to work, with the
-rpe_all options passing through substantially different code branches. But I couldn’t remove these old command-line options from the new version of the script, since it can’t be guaranteed that the phase-encoding table will be available in all cases (and also people have become accustomed to using them).
The way I resolved this in the newest version of the script is: When the user uses one of the
-rpe_all options in conjunction with the
-pe_dir option (and possibly also the
-readout_time option), the script uses this information to construct the phase-encoding table based on the user’s inputs and the number of image volumes. This then means that once the phase-encoding table is constructed, these three older
-rpe_* “operating modes” of the script in fact pass through the very same code path as the
However, this is only possible if the script has enough information to construct that phase-encoding table…
OK, promised I’d get there in the end. The reason
-rpe_pair requires an even number of volumes in the
-se_epi image is: If the number of volumes were odd, it would be impossible for the script to unambiguously determine the phase-encoding table for those volumes. E.g. for an image with 5 volumes, is it two A>>P and three P>>A images, or three A>>P and two P>>A images?
The alternative - assuming you have a Siemens scanner and don’t use any non-MRtrix3 commands between DICOM import and
dwipreproc invocation - is to use the
-rpe_header option (this will happily accept any
-se_epi image, as long as there is phase-encoding contrast with which to estimate the inhomogeneity field. Note that the output of
dwipreproc with the
-rpe_header option should always be visually checked, since I can’t guarantee that the phase-encoding import is bulletproof; but I’m hoping that over time more people will make use of this feature.