Add support for extraction of signals using user-supplied mask

[m-miedema]

So far this is a quick addition to the data_loader: I added a new function (nifti2arraywmask) that allows the use of the 3-D mask file to extract BOLD signals. I also modified the main data loader function (nifti2timeseries) to support its use - at least for single subject/single session data.

To-dos from here could include adding multi-session support, adding in an example of usage to the demos, and providing more guidance on creating a mask (I have a script I can contribute to that).

[mtorabi59]

Suggested change

	if mask_file is not None and n_rois is not None:
	print("Warning: specified mask_file will be used, ignoring n_rois.")
	if mask_file is not None and n_rois is not None:
	n_rois = None
	warnings.warn("specified mask_file will be used, ignoring n_rois.")

[mtorabi59]

and maybe import warnings

[mtorabi59]

it's better to raise an error here:

Suggested change

	if mask_file is None and n_rois is None:
	print("Either mask_file or n_rois must be defined.")
	if mask_file is None and n_rois is None:
	raise ValueError("Either mask_file or n_rois must be defined.")

[mtorabi59]

@m-miedema Thanks so much for implementing this new functionality! Overall it looks good. I have put a few suggestions. Also, since nifti2arraywmask has a lot in common with nifti2array I think it makes sense if we merge them, so it's just nifti2array with a new argument and a bit of change.
Additionally, since nilearn supports different kinds of maskers - NiftiLabelsMasker, NiftiMapsMasker, NiftiSpheresMasker, even SurfaceMasker, it'd be useful for the user if we clarify that this added functionality is only using NiftiLabelsMasker for now. So for instance we can call the mask_file, labels_img, or sth like labels_masker_file. What do you think?

[mtorabi59]

And regarding an example, I think that's a great idea. If we can have a separate example dedicated to use casing of your functionality, based on the script you already have, it'll be super useful for the users.

[mtorabi59]

@m-miedema , please take a look at the new changes I made to the data_loader module once you pull them. I have implemented support for NiftiSpheresMasker. Let me know if it works for what you want to do!

[m-miedema]

The new additions look good to me! Would you prefer I create a separate demo notebook to add to the future examples directory? I think they will be a good place to highlight considerations for mask creation and to document several potential pitfalls that come with specifying a list of labels I've encountered while testing on my own masks and data.

[mtorabi59]

The new additions look good to me! Would you prefer I create a separate demo notebook to add to the future examples directory? I think they will be a good place to highlight considerations for mask creation and to document several potential pitfalls that come with specifying a list of labels I've encountered while testing on my own masks and data.

Creating a new notebook is a great idea @m-miedema ! I'll create a new directory for examples containing a copy of the current demos and then you can add your new notebook there!

[mtorabi59]

@m-miedema you can pull the new directory now