Add option to us 2mm voxels size for the MNI transformation

[chrisgorgo]

We currently keep the same voxel size of the MNI outputs as the original inputs. This avoids upsampling and saves disk space.

However, images in MNI space that do not have the canonical MNI template resolution and dimensions can cause problems with some legacy software (for example FSLView). It would be good for compatibility reasons to provide an option to disable resolution preserving feature and use cannonical 2mm resolution.

Suggested by @poldrack.

[feilong]

Does FSL in the Docker/Singularity image contains standard brains? I didn't find the data directory of FSL.

[chrisgorgo]

Indeed the atlases are not included to save space.

However, to add an option of forcing 2mm voxel size (instead of the voxel size of the inputs as it is done right now) you can modify this Interface https://github.com/poldracklab/fmriprep/blob/cecf99dd25a25a840673c900b3f905616bd35666/fmriprep/interfaces/images.py#L42

Most importantly it would be interesting to learn why are you interested in this feature. Using 2mm voxel size when your original data has lower resolution will waste disk space without much of an advantage.

[feilong]

One data set that I'm working on was collected from different sites and has different voxel sizes. It would be helpful to resample data to the same resolution (not necessarily upsampling to 2mm).

[chrisgorgo]

Ah I see - let me know if you need help implementing this. Opening a pull request with "[WIP]" (as in Work in Progress) could be a good starting point.

[feilong]

I just sent a pull request that allows to use an external image as the resampling reference.

Alternatively we could specify a resolution for resampling and create the reference using the interface mentioned above, but the created 2-mm reference would be slightly different from the one provided by FSL in terms of shape and affine matrix.

[chrisgorgo]

I think there are two issues we need to disentangle here:

• Selection of the normalization target template. We are currently using MNI152NLin2009cAsym while SPM and FSL are using an older MNI152NLin6Asym (more details here). Those templates are very similar, but not the same and will produce different results. If you want your results to be in the exactly same space as FSL we need to add support for MNI152NLin6Asym space.

• Resolution and grid size of the output images. Currently we are using the same resolution as the source data (and a grid that is scaled down accordingly). This ok if all input images have the same resolution, but causes problems when there is an odd image with different resolution or data comes from multiple sites. We could however add a heuristic that that would crawl the input dataset and figure out what is the highest (or most common) resolution across all scans and use that for reslicing.

What do you think @feilong?

[feilong]

I'm happy with only using MNI152NLin2009cAsym at this moment. The two template brains (6th and 2009c) are very similar, but 2009c has better details, and in most cases we can use transform data (e.g., atlases) between the two spaces with linear or nonlinear warping. It's still good to have an MNI152NLin6Asym option so that preprocessed data will be directly compatible with SPM, FSL, and HCP data.

For the resolution and grid size issue, I still want to have the option to explicitly specify the resolution to use. It's because different data sets can have different BIDS folders, and I'm afraid inference from each dataset is not enough in this case.

[feilong]

Does it make sense to have two parameters separately for normalization template and grid template?

[chrisgorgo]

Ideally I think we should have the following:

• --output-spaces should include MNI152NLin6Asym (but keep MNI152NLin2009cAsym as default)
• --output-resolution=3x3x3 prescribed resolution in mm (default value auto)
• --output-dimensions=182x218x182 prescribed grid size in voxels (default value auto)

In argument help (--help) we can explain what values of those options are used by SPM and FSL.

This way the user will not need to find and provide reference files. It has an additional advantage of being able to store provenance (prescribed input options) without having to save any additional input files provided by the user.

What do you think?

[feilong]

Shall we have another parameter to complement --output-resolution and determine the affine matrix? It could be the offsets from the last column of the affine matrix (e.g., 90,-126,-72).

Another minor detail is the output orientation, where RAS is probably a nice default.

[chrisgorgo]

Wouldn't the 'offsets from the last column' define the location of the origin (0,0,0) which should be the already defined by the --output-space? What is the use case for changing this?

RAS seems like a good default.

[feilong]

Still to achieve compatibility with FSL etc.
For example, this is part of the output of mri_info MNI152_T1_2mm.nii.gz, using the 2mm template of FSL:

dimensions: 91 x 109 x 91
voxel to ras transform:
               -2.0000   0.0000   0.0000    90.0000
                0.0000   2.0000   0.0000  -126.0000
                0.0000   0.0000   2.0000   -72.0000
                0.0000   0.0000   0.0000     1.0000

Whereas a 2-mm template created by transforming the 1-mm template with fmriprep.interfaces.images._gen_reference to 2-mm would be like:

dimensions: 92 x 110 x 92
voxel to ras transform:
                2.0000   0.0000   0.0000   -91.0000
                0.0000   2.0000   0.0000  -126.0000
                0.0000   0.0000   2.0000   -72.0000
                0.0000   0.0000   0.0000     1.0000

Besides slight differences in grid dimensions and orientation, the two grids would be 1-mm apart along the x-axis, as different softwares have different ways to determine output grid.

I don't know if it's still an issue if both output dimensions and output resolution are specified.