OK, here we go again... 😟

Related to #874, #1051, #1084.

An explicit option -align_seepi is added to the dwipreproc script, which instructs the script that the user wishes to enforce alignment between the inhomogeneity field as estimated by topup, and the estimations & corrections performed by eddy. It does this by ensuring that the first volume in the series input to topup is precisely the same volume as the first volume in the series input to eddy.

More specifics & addendums:

• If the volumes within the -se_epi input do not contain any phase-encoding contrast, previously the script would immediately abort, as it was impossible to estimate the inhomogeneity field. Now, if this occurs and the -align_seepi option is provided, the script will concatenate the DWI b=0 volumes with the -se_epi input, and re-check the requirement of phase-encoding contrast. This is to account for e.g. labs that acquire a single P>>A b=0 and then their A>>P DWIs; but also, if one is not going to acquire all DWIs with reversed phase-encoding, rather than e.g. acquiring one A>>P b=0, one P>>A b=0, then A>>P DWIs, for the same total acquisition time one could instead acquire ~ 5 P>>A b=0 images then A>>P DWIs, giving more data to topup. This is especially true for multi-band acquisitions due to the extra calibration time.

• If the first volume in the DWIs is not a b=0 (unlikely, but nevertheless possible), the DWI volumes are permuted such that the first b=0 volume becomes volume index 0, and then permuted back to their original order after eddy. This is necessary due to the topup / eddy silent mutual agreement regarding the reference space.

• If the -se_epi input image does not match the DWI voxel grid, it is immediately re-gridded to the DWI voxels. Even if the -align_seepi option is not used, it's still necessary for the topup estimated field and the DWIs input to eddy to be defined on the same grid: eddy appears to perform some internal concatenation step between these data, and so errors out if they don't match. Reports here and here.

• If -align_seepi is used, check header fields for information relating to TE, TR and flip angle, since these influence image contrast and may therefore invalidate the assumptions required for this option to work. Also capture these fields from DICOM import.

• topup cannot operate on images where one of the three spatial dimensions has an odd number of voxels; likely due to downsampling by a factor of 2 and experiencing a buffer overflow. Previously this was dealt with by cropping the image provided to topup by one voxel along relevant axes. However this removes image information, and stopped working when eddy started performing an internal concatenation step (since the DWIs were not also correspondingly cropped). This has been altered to not only manipulate both the DWI and SE-EPI images, but also to pad problematic axes with duplicate image information as opposed to cropping, and then crop the resulting series after eddy has completed. Therefore the image output by the script should always have the same size in the three spatial dimensions as the input image.

• warpinvert: New command, but not actually used (was going to be necessary for an alternative dwipreproc alignment approach).

There's a bit of gymnastics going on, and a lot of possible code paths, so I'm not expecting that anyone's going to be able to spot issues from the code alone; but you never know.

I've tested it on a reasonable range of possible input data configurations, including presence & absence of the above confounds, and different -rpe_* options. But ultimately it probably needs field testing...