User warning when data is being upsampled when masked

[FrancoisPgm]

The default beahaviour of maskers is to resample the data to the mask's affine, but when the data has a lower resolution than the mask, it upsamples the data, requiring more computation and memory than necessary. Throwing a warning when it happens could help users to specify a target affine when it is relevant.

Benefits to the change

Users can realise when they upsample their data, and that they can save computation time and memory by specifying a target affine (or a resampling strategy).

Pseudocode for the new behavior, if applicable

## in transform_single_imgs
if imgs.resolution < self.mask_img_.resolution:
    raise UserWarning("Images are being upsampled to the mask's resolution, "
        "you might want to provide a target_affine to save memory and computation time.")

[jeromedockes]

we can improve the warning message but I like the idea!

[FrancoisPgm]

Actually now that I'm trying to write a check to catch the upsampling, I'm not so sure anymore that it's always the default behaviour. It for sure has happened to me but I might need to investigate deeper into how I got it to happen.

[alexisthual]

I'm going to see this warning so often haha 😆

[ymzayek]

Hi @FrancoisPgm sorry it took me a while to get back to you. So the resampling to the mask is indeed the default behavior of the NiftiMasker class (and MultiNiftiMasker by inheritance). These maskers use a function called _filter_and_mask in nilearn.maskers.nifti_masker.py to call another function to perform resampling and timeseries extraction. An appropriate place to add your check and warning would therefore be under this _filter_and_mask function. More precisely, in line 103 of nifti_masker.py there is a check if resampling is necessary, you can put your code under this conditional.

It is the case that the default behavior for the other maskers is different and they do not need this warning.

[ymzayek]

@mtorabi59 can you also have a look at this? I think implementing this warning can only be helpful in the meantime while we haven't made a decision about making this behavior consistent across all maskers.

[mtorabi59]

@ymzayek sure, I will put it at the top of my list!