.. include:: ../links.inc

.. _using_masks:

Masks
=====

Masks are essentially boolean arrays that are used to constrain the extraction of features to voxels that are
meaningful. For example, in an fMRI imaging study, a mask can be used to constrain the extraction of features to
voxels that contain a certain ratio of gray matter to white matter / cerebrospinal fluid, ensuring that the features
are not extracted from voxels that contain mostly white matter or cerebrospinal fluid, which could add noise to the
BOLD signal.

Junifer provides a number of built-in masks, which can be listed using the :func:`junifer.data.masks.list_masks`. Some
masks are images, while other masks can be computed using :ref:`nilearn` functions. 

For markers and steps that accept ``masks`` as an argument, the mask can be specified as a string, which will be the
name of a built-in mask, or as a dictionary in which the **only** key is the built-in mask name and the value is a 
dictionary of keyword arguments to pass to the mask function. 

For example, the following is a valid mask specification that specified the ``GM_prob0.2`` mask.

.. code-block:: yaml

    masks: GM_prob0.2

The following is a valid mask specification that specifies the ``compute_brain_mask``  mask (function from nilearn),
with a threshold of 0.5.

.. code-block:: yaml

    masks: 
        compute_brain_mask:
            threshold: 0.5

Furthermore, junifer allows you to combine several masks using :func:`nilearn.masking.intersect_masks`. This is done by
specifying a list of masks, where each mask is a string or dictionary as described above. For example, the following
is a valid mask specification that specifies the intersection of the ``GM_prob0.2`` and ``compute_brain_mask`` masks.

.. code-block:: yaml

    masks: 
        - GM_prob0.2
        - compute_brain_mask:
            threshold: 0.5

We can also specify the arguments of :func:`nilearn.masking.intersect_masks` (``threshold`` and ``connected``). The
following example combines the same masks as the previous one, but computing the full intersection.


.. code-block:: yaml

    masks: 
        - GM_prob0.2
        - compute_brain_mask:
            threshold: 0.5
        - threshold: 1  # intersection

Alternatively, we can also compute the union, even if the voxels do not form a connected component:

.. code-block:: yaml

    masks: 
        - GM_prob0.2
        - compute_brain_mask:
            threshold: 0.5
        - threshold: 0  # union
        - connected: False  # keep disconnected components