Make sure the xform_code is correct when generating references

[oesteban]

Comes from nipreps/niworkflows#202 (comment).

We need to make sure that the xform_code is 2 when generating images aligned in anatomical space and 4 when generating results on MNI space.

EDIT:

This issue also includes generating the appropriate documentation about affines.

Use cases (from nipreps/niworkflows#202 (comment)):

1. When moving within the same space (SDC, head motion correction, SBRef-EPI), we keep the original xforms (even if they are wrong in the original files).

2. When moving to different space (anatomical or MNI), we are generating an image taken as reference space. So it is this point when we need to make sure that the xform code is the appropriate one. Since we pass on this reference image to the registration interface, the xform matrices should, indeed, be copied over the resulting images. Same for ApplyTransforms.

3. When several T1w images are present, the affine is set to the one chosen as reference or a new affine corresponding to the intermediate space to all will be generated (see anat affine appears off for ds000114 between data and fmriprep output #624).

Bottomline: no interface should change xforms unless we are certain we want to do that. Only GenerateSamplingReference should make these changes.

EDIT: this issue also covers #260:

@chrisfilo proposed:

To make sure data fed to FMRIPREP from different datasets is looking as similar as possible we are currently reorienting anatomical images to RAS. However, there is more that can be done:

• make sure that the information in the header concerning data type and affine transformation (sform, qform) are correct; fix if possible
• apply the same procedure to all input data (_bold, _sbref, fieldmaps etc.)

Problems:

• If we change the orientation of input files we need to adjust the phase encoding direction as well.
• Applying those fixes to big 4D _bold files will create an (almost) identical copy and waste a lot of disk space

And @effigies added #573 (comment):

To address further issues raised in #260:

• If we change the orientation of input files we need to adjust the phase encoding direction as well.

NIfTI does have a phase_dim header entry. We could update the header, and use that later.

• Applying those fixes to big 4D _bold files will create an (almost) identical copy and waste a lot of disk space

True, and adding the PE direction header entry will cause the same issue, if we don't already need to create a new file.

I haven't tried this out yet, but we could consider creating a filename.hdr.gz with a data offset matching the original header, and symlink to the original file with filename.img.gz. Assuming this works, we couldn't reorient, but we could update the headers without copying the data.

[effigies]

Just something to be careful on: The standard says that sform takes precedence over qform, which means the qform can be ignored and not updated when transformations are applied by standards-conforming software. So there's the possibility that setting the qform codes to 2 could be misleading.

Which is part of what makes ANTs' refusal to correctly handle sforms so frustrating.

[effigies]

Turns out the reason lta_convert was giving us bad translations (fixed in #743 by going LTA-FSL-ITK) was because of a qform/sform difference. LTAs contain sform-derived geometric information about the moving (source) and reference (destination) images, and lta_convert uses that information when converting from LTA to ITK (or to FSL, for that matter). c3d_affine_tool, when converting from FSL to ITK, reads the qforms of the moving and reference images to change spaces.

Related: https://www.mail-archive.com/freesurfer@nmr.mgh.harvard.edu/msg55547.html

I believe that syncing the qform to the sform in the BOLD series at the start should resolve the issue, as the reference image will be derived from that, and the transforms will all be calculated on the reference and applied to the series.

[effigies]

Incidentally, it's possible (though hacky) to turn a .nii.gz into a .hdr.gz/.img.gz, where the img.gz is just a symlink/hardlink to the original .nii.gz:

import os
import nibabel as nb
from gzip import GzipFile
img = nb.load('bold.nii.gz')
pair = nb.Nifti1Pair.from_image(img)
# This is the default offset, but real code would need to account for extensions
pair.header.set_data_offset(352)
with GzipFile('bold.hdr.gz', 'wb') as fobj:
    fobj.write(pair.header.binaryblock)
os.link('bold.nii.gz', 'bold.img.gz')

I'm just thinking in terms of strategies for fixing headers without making full copies of large BOLD series.

[oesteban]

I've written down the last two comments in two new issues that we may consider in a future, but right now they are not burning urgent.

This issue is also related to #726.

I guess this issue is completely covered now, so I'll close it.