Nilearn.masking.compute_gray_matter_mask does not output gray matter mask?

I am using NiftiMasker to extract data from my images. I am interested only in gray matter. I have one control condition where I do not provide a mask image to mask_img. I set mask_strategy to mask_strategy='template', which according to nilearn documentations means, that it will compute a mask using nilearn.masking.compute_gray_matter_mask which will

“extract the gray matter part of your data by resampling the MNI152 brain mask for your data’s field of view”

Furthermore, in the documentation of nilearn.masking.compute_gray_matter_mask it says:

“Compute a mask corresponding to the gray matter part of the brain. The gray matter part is calculated through the resampling of MNI152 template gray matter mask onto the target image.”

According to the documentation I expected the mask image to look something like this (this is a gray matter mask image provided from SDM):

But when I look at the fitted mask_img_ in the NiftiMasker instance the mask looks like this:

Correct me if I am wrong, maybe I have a different conception about whole brain / gray matter and this is a misunderstanding, but the second mask image looks like a whole brain mask and not a gray matter mask. Can someone explain what is going on here?

Here’s my code:

from nilearn.datasets import fetch_oasis_vbm
from nilearn.input_data import NiftiMasker
from nilearn import plotting

# fetch OASIS dataset
oasis_img_paths = fetch_oasis_vbm(n_subjects=10)['gray_matter_maps']

# mask images and get data
niftimasker = NiftiMasker(mask_img=None,

X = niftimasker.fit_transform(oasis_img_paths)

# check used mask image
niftimasker_mask_img_ = niftimasker.mask_img_
html_view = plotting.view_img(niftimasker_mask_img_)

Indeed, the teamplte that is used in the function is a brain mask, not a gm mask.
There are 2 possibilities:

  • Either we consider that a brain mask is OK, and we view this as a documentationbug
  • Or we consider that a gray matter mask is really important and we should add options.
    I am leaning toward the first option, since you can alwaus come up with your preferred gm image and resample it to the target image, then threshold it.
    WDYT ?

I also think that the first option is the best.
a gray matter mask can be obtained in nilearn by thresholding nilearn.datasets.fetch_icbm152_2009().gm
@JohannesWiesner would you consider opening an issue or PR to fix the documentation?

I am not sure about this. Personally, I think a grey matter masking should be built-in, since this a common-needed masking-procedure (I guess that most of the users would want to focus either on grey or white matter in the first place). @jeromedockes Sure, I will open an issue on GitHub and wrap this up!

Maybe one last question here on Neurostars (just to avoid basic questions that do not belong to the actual issue):

I don’t really get what the arguments threshold, connected and opening in masking.compute_gray_matter_mask are for? Once again, I find nilearn a little bit underdocumented here, especially in the eyes of a relatively new user like me. If the function ‘only’ resamples the mni gray matter mask to the data images affine, what do these keyword arguments contribute to the whole mask creation?

1 Like