junifer 0.0.2.dev138__tar.gz → 0.0.2.dev140__tar.gz

{junifer-0.0.2.dev138 → junifer-0.0.2.dev140}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: junifer
-Version: 0.0.2.dev138
+Version: 0.0.2.dev140
 Summary: JUelich NeuroImaging FEature extractoR
 Author-email: Fede Raimondo <f.raimondo@fz-juelich.de>, Synchon Mandal <s.mandal@fz-juelich.de>
 Maintainer-email: Fede Raimondo <f.raimondo@fz-juelich.de>, Synchon Mandal <s.mandal@fz-juelich.de>

{junifer-0.0.2.dev138 → junifer-0.0.2.dev140}/docs/changes/latest.inc

@@ -40,6 +40,9 @@ Enhancements
 - Add support for nilearn computed masks (``compute_epi_mask``, ``compute_brain_mask``, ``compute_background_mask``,
   ``fetch_icbm152_brain_gm_mask``) (:gh:`175` by `Fede Raimondo`_).
 
+- Add fMRIPrep brain masks to the datagrabber patterns for all datagrabbers in the aomic sub-package
+  (:gh:`177` by `Leonard Sasse`_).
+
 Bugs
 ~~~~
 

{junifer-0.0.2.dev138 → junifer-0.0.2.dev140}/docs/using/index.rst

@@ -15,4 +15,18 @@ the results. Finally, we will show how to use the ``queue`` command to interact
 
    codeless
    running
-   queueing
+   queueing
+
+
+.. _using_components:
+
+Using junifer common components
+-------------------------------
+
+The following sections explains common components of junifer that can be used across many steps of the pipeline.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   masks

junifer-0.0.2.dev140/docs/using/masks.rst

@@ -0,0 +1,68 @@
+.. 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

junifer-0.0.2.dev140/junifer/_version.py

@@ -0,0 +1,4 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+__version__ = version = '0.0.2.dev140'
+__version_tuple__ = version_tuple = (0, 0, 2, 'dev140')

{junifer-0.0.2.dev138 → junifer-0.0.2.dev140}/junifer/data/masks.py

@@ -23,6 +23,7 @@ from nilearn.masking import (
     compute_background_mask,
     compute_brain_mask,
     compute_epi_mask,
+    intersect_masks,
 )
 
 from ..utils.logging import logger, raise_error
@@ -36,7 +37,10 @@ if TYPE_CHECKING:
 _masks_path = Path(__file__).parent / "masks"
 
 
-def _fetch_icbm152_brain_gm_mask(target_img: "Nifti1Image", **kwargs):
+def _fetch_icbm152_brain_gm_mask(
+    target_img: "Nifti1Image",
+    **kwargs,
+):
     """Fetch ICBM152 brain mask and resample.
 
     Parameters
@@ -65,6 +69,9 @@ data.
 
 The built-in masks are files that are shipped with the package in the
 data/masks directory. The user can also register their own masks.
+
+Callable masks should be functions that take at least one parameter:
+* `target_img`: the image to which the mask will be applied.
 """
 _available_masks: Dict[str, Dict[str, Any]] = {
     "GM_prob0.2": {"family": "Vickery-Patil"},
@@ -146,19 +153,23 @@ def list_masks() -> List[str]:
 
 
 def get_mask(
-    mask: Union[str, Dict],
+    masks: Union[str, Dict, List[Union[Dict, str]]],
     target_data: Dict[str, Any],
+    extra_input: Optional[Dict[str, Any]] = None,
 ) -> "Nifti1Image":
     """Get mask, tailored for the target image.
 
     Parameters
     ----------
-    masks : str or dict
+    masks : str, dict or list of dict or str
         The name of the mask, or the name of a callable mask and the parameters
-        of the mask.
+        of the mask as a dictionary. Several masks can be passed as a list.
     target_data : dict
         The corresponding item of the data object to which the mask will be
         applied.
+    extra_input : dict, optional
+        The other fields in the data object. Useful for accessing other data
+        kinds that needs to be used in the computation of masks (default None).
 
     Returns
     -------
@@ -167,37 +178,98 @@ def get_mask(
     """
     # Get the min of the voxels sizes and use it as the resolution
     target_img = target_data["data"]
+    inherited_mask_item = target_data.get("mask_item", None)
     resolution = np.min(target_img.header.get_zooms()[:3])
 
-    if isinstance(mask, dict):
-        if len(mask) != 1:
-            raise_error(
-                "The mask dictionary must have only one key, "
-                "the name of the mask."
-            )
-        mask_name = list(mask.keys())[0]
-        mask_params = mask[mask_name]
-    else:
-        mask_name = mask
-        mask_params = None
+    if not isinstance(masks, list):
+        masks = [masks]
 
-    mask_object, _ = load_mask(
-        mask_name, path_only=False, resolution=resolution
-    )
-    if callable(mask_object):
-        if mask_params is None:
-            mask_params = {}
-        mask_img = mask_object(target_img, **mask_params)
-    else:  # Mask is a Nifti1Image
-        if mask_params is not None:
-            raise_error("Cannot pass callable params to a non-callable mask.")
-        mask_img = resample_to_img(
-            mask_object,
-            target_img,
-            interpolation="nearest",
-            copy=True,
+    # Check that dicts have only one key
+    invalid_elements = [
+        x for x in masks if isinstance(x, dict) and len(x) != 1
+    ]
+    if len(invalid_elements) > 0:
+        raise_error(
+            "Each of the masks dictionary must have only one key, "
+            "the name of the mask. The following dictionaries are invalid: "
+            f"{invalid_elements}"
         )
 
+    # Check params for the intersection function
+    intersect_params = {}
+    true_masks = []
+    for t_mask in masks:
+        if isinstance(t_mask, dict):
+            if "threshold" in t_mask:
+                intersect_params["threshold"] = t_mask["threshold"]
+                continue
+            elif "connected" in t_mask:
+                intersect_params["connected"] = t_mask["connected"]
+                continue
+        # All the other elements are masks
+        true_masks.append(t_mask)
+
+    if len(true_masks) == 0:
+        raise_error("No mask was passed. At least one mask is required.")
+    # Get all the masks
+    all_masks = []
+    for t_mask in true_masks:
+        if isinstance(t_mask, dict):
+            mask_name = list(t_mask.keys())[0]
+            mask_params = t_mask[mask_name]
+        else:
+            mask_name = t_mask
+            mask_params = None
+
+        if mask_name == "inherit":
+            if extra_input is None:
+                raise_error(
+                    "Cannot inherit mask from another data item "
+                    "because no extra data was passed."
+                )
+            if inherited_mask_item is None:
+                raise_error(
+                    "Cannot inherit mask from another data item "
+                    "because no mask item was specified "
+                    "(missing `mask_item` key in the data object)."
+                )
+            if inherited_mask_item not in extra_input:
+                raise_error(
+                    "Cannot inherit mask from another data item "
+                    f"because the item ({inherited_mask_item}) does not exist."
+                )
+            mask_img = extra_input[inherited_mask_item]["data"]
+        else:
+            mask_object, _ = load_mask(
+                mask_name, path_only=False, resolution=resolution
+            )
+            if callable(mask_object):
+                if mask_params is None:
+                    mask_params = {}
+                mask_img = mask_object(target_img, **mask_params)
+            else:  # Mask is a Nifti1Image
+                if mask_params is not None:
+                    raise_error(
+                        "Cannot pass callable params to a non-callable mask."
+                    )
+                mask_img = resample_to_img(
+                    mask_object,
+                    target_img,
+                    interpolation="nearest",
+                    copy=True,
+                )
+        all_masks.append(mask_img)
+    if len(all_masks) > 1:
+        mask_img = intersect_masks(all_masks, **intersect_params)
+    else:
+        if len(intersect_params) > 0:
+            # Yes, I'm this strict!
+            raise_error(
+                "Cannot pass parameters to the intersection function "
+                "when there is only one mask."
+            )
+        mask_img = all_masks[0]
+
     return mask_img
 
 

{junifer-0.0.2.dev138 → junifer-0.0.2.dev140}/junifer/data/tests/test_masks.py

@@ -6,8 +6,9 @@
 # License: AGPL
 
 from pathlib import Path
-from typing import Callable, Dict, Union
+from typing import Callable, Dict, List, Union
 
+import numpy as np
 import pytest
 from nilearn.datasets import fetch_icbm152_brain_gm_mask
 from nilearn.image import resample_to_img
@@ -15,6 +16,7 @@ from nilearn.masking import (
     compute_background_mask,
     compute_brain_mask,
     compute_epi_mask,
+    intersect_masks,
 )
 from numpy.testing import assert_array_almost_equal, assert_array_equal
 
@@ -56,7 +58,9 @@ def test_register_mask_already_registered() -> None:
         name="testmask",
         mask_path="testmask.nii.gz",
     )
-    assert load_mask("testmask", path_only=True)[1].name == "testmask.nii.gz"
+    out = load_mask("testmask", path_only=True)
+    assert out[1] is not None
+    assert out[1].name == "testmask.nii.gz"
 
     # Try registering again
     with pytest.raises(ValueError, match=r"already registered."):
@@ -70,7 +74,9 @@ def test_register_mask_already_registered() -> None:
         overwrite=True,
     )
 
-    assert load_mask("testmask", path_only=True)[1].name == "testmask2.nii.gz"
+    out = load_mask("testmask", path_only=True)
+    assert out[1] is not None
+    assert out[1].name == "testmask2.nii.gz"
 
 
 @pytest.mark.parametrize(
@@ -110,6 +116,7 @@ def test_register_mask(
     # Load registered mask
     _, fname = load_mask(name=name, path_only=True)
     # Check values for registered mask
+    assert fname is not None
     assert fname.name == f"{name}.nii.gz"
 
 
@@ -146,6 +153,7 @@ def test_vickery_patil() -> None:
         mask.header["pixdim"][1:4], [1.5, 1.5, 1.5]  # type: ignore
     )
 
+    assert fname is not None
     assert fname.name == "CAT12_IXI555_MNI152_TMP_GS_GMprob0.2_clean.nii.gz"
 
     mask, fname = load_mask("GM_prob0.2", resolution=3)
@@ -153,6 +161,7 @@ def test_vickery_patil() -> None:
         mask.header["pixdim"][1:4], [3.0, 3.0, 3.0]  # type: ignore
     )
 
+    assert fname is not None
     assert (
         fname.name == "CAT12_IXI555_MNI152_TMP_GS_GMprob0.2_clean_3mm.nii.gz"
     )
@@ -162,6 +171,7 @@ def test_vickery_patil() -> None:
         mask.header["pixdim"][1:4], [3.0, 3.0, 3.0]  # type: ignore
     )
 
+    assert fname is not None
     assert fname.name == "GMprob0.2_cortex_3mm_NA_rm.nii.gz"
 
     with pytest.raises(ValueError, match=r"find a Vickery-Patil mask "):
@@ -176,7 +186,7 @@ def test_get_mask() -> None:
         input = reader.fit_transform(input)
         vbm_gm = input["VBM_GM"]
         vbm_gm_img = vbm_gm["data"]
-        mask = get_mask(mask="GM_prob0.2", target_data=vbm_gm)
+        mask = get_mask(masks="GM_prob0.2", target_data=vbm_gm)
 
         assert mask.shape == vbm_gm_img.shape
         assert_array_equal(mask.affine, vbm_gm_img.affine)
@@ -204,7 +214,7 @@ def test_mask_callable() -> None:
         input = reader.fit_transform(input)
         vbm_gm = input["VBM_GM"]
         vbm_gm_img = vbm_gm["data"]
-        mask = get_mask(mask="identity", target_data=vbm_gm)
+        mask = get_mask(masks="identity", target_data=vbm_gm)
 
         assert_array_equal(mask.get_fdata(), vbm_gm_img.get_fdata())
 
@@ -218,11 +228,48 @@ def test_get_mask_errors() -> None:
         input = dg["sub-01"]
         input = reader.fit_transform(input)
         vbm_gm = input["VBM_GM"]
+        # Test wrong masks definitions (more than one key per dict)
         with pytest.raises(ValueError, match=r"only one key"):
-            get_mask(mask={"GM_prob0.2": {}, "Other": {}}, target_data=vbm_gm)
+            get_mask(masks={"GM_prob0.2": {}, "Other": {}}, target_data=vbm_gm)
 
+        # Test wrong masks definitions (pass paramaeters to non-callable mask)
         with pytest.raises(ValueError, match=r"callable params"):
-            get_mask(mask={"GM_prob0.2": {"param": 1}}, target_data=vbm_gm)
+            get_mask(masks={"GM_prob0.2": {"param": 1}}, target_data=vbm_gm)
+
+        # Pass only parametesr to the intersection function
+        with pytest.raises(
+            ValueError, match=r" At least one mask is required."
+        ):
+            get_mask(masks={"threshold": 1}, target_data=vbm_gm)
+
+        # Pass parameters to the intersection function when only one mask
+        with pytest.raises(
+            ValueError, match=r"parameters to the intersection"
+        ):
+            get_mask(
+                masks=["GM_prob0.2", {"threshold": 1}], target_data=vbm_gm
+            )
+
+        # Test "inherited" masks errors
+
+        # 1) No extra_data parameter
+        with pytest.raises(ValueError, match=r"no extra data was passed"):
+            get_mask(masks="inherit", target_data=vbm_gm)
+
+        extra_input = {"VBM_MASK": {}}
+
+        # 2) No mask_item key in target_data
+        with pytest.raises(ValueError, match=r"no mask item was specified"):
+            get_mask(
+                masks="inherit", target_data=vbm_gm, extra_input=extra_input
+            )
+
+        # 3) mask_item not in extra data
+        with pytest.raises(ValueError, match=r"does not exist"):
+            vbm_gm["mask_item"] = "wrong"
+            get_mask(
+                masks="inherit", target_data=vbm_gm, extra_input=extra_input
+            )
 
 
 @pytest.mark.parametrize(
@@ -271,7 +318,7 @@ def test_nilearn_compute_masks(
         else:
             mask_spec = {mask_name: params}
 
-        mask = get_mask(mask=mask_spec, target_data=bold)
+        mask = get_mask(masks=mask_spec, target_data=bold)
 
         assert_array_equal(mask.affine, bold_img.affine)
 
@@ -287,3 +334,114 @@ def test_nilearn_compute_masks(
                 copy=True,
             )
         assert_array_equal(mask.get_fdata(), ni_mask.get_fdata())
+
+
+def test_get_mask_inherit() -> None:
+    """Test using the inherit mask functionality."""
+    reader = DefaultDataReader()
+    with SPMAuditoryTestingDatagrabber() as dg:
+        input = dg["sub001"]
+        input = reader.fit_transform(input)
+        # Compute brain mask using nilearn
+        gm_mask = compute_brain_mask(input["BOLD"]["data"], threshold=0.2)
+
+        # Get mask using the compute_brain_mask function
+        mask1 = get_mask(
+            masks={"compute_brain_mask": {"threshold": 0.2}},
+            target_data=input["BOLD"],
+        )
+
+        # Now get the mask using the inherit functionality, passing the
+        # computed mask as extra data
+        extra_input = {"BOLD_MASK": {"data": gm_mask}}
+        input["BOLD"]["mask_item"] = "BOLD_MASK"
+        mask2 = get_mask(
+            masks="inherit", target_data=input["BOLD"], extra_input=extra_input
+        )
+
+        # Both masks should be equal
+        assert_array_equal(mask1.get_fdata(), mask2.get_fdata())
+
+
+@pytest.mark.parametrize(
+    "masks,params",
+    [
+        (["GM_prob0.2", "compute_brain_mask"], {}),
+        (
+            ["GM_prob0.2", "compute_brain_mask"],
+            {"threshold": 0.2},
+        ),
+        (
+            [
+                "GM_prob0.2",
+                "compute_brain_mask",
+                "fetch_icbm152_brain_gm_mask",
+            ],
+            {"threshold": 1, "connected": True},
+        ),
+    ],
+)
+def test_get_mask_multiple(
+    masks: Union[str, Dict, List[Union[Dict, str]]], params: Dict
+) -> None:
+    """Test getting multiple masks.
+
+    Parameters
+    ----------
+    masks : str, dict, list of str or dict
+        Masks to get, junifer style.
+    params : dict
+        Parameters to pass to the intersect_masks function.
+    """
+    reader = DefaultDataReader()
+    with SPMAuditoryTestingDatagrabber() as dg:
+        input = dg["sub001"]
+        input = reader.fit_transform(input)
+        if not isinstance(masks, list):
+            junifer_masks = [masks]
+        else:
+            junifer_masks = masks.copy()
+        if len(params) > 0:
+            # Convert params to junifer style (one dict per param)
+            junifer_params = [{k: params[k]} for k in params.keys()]
+            junifer_masks.extend(junifer_params)
+        target_img = input["BOLD"]["data"]
+        resolution = np.min(target_img.header.get_zooms()[:3])
+
+        computed = get_mask(masks=junifer_masks, target_data=input["BOLD"])
+
+        masks_names = [
+            list(x.keys())[0] if isinstance(x, dict) else x for x in masks
+        ]
+
+        mask_funcs = [
+            x
+            for x in masks_names
+            if _available_masks[x]["family"] == "Callable"
+        ]
+        mask_files = [
+            x
+            for x in masks_names
+            if _available_masks[x]["family"] != "Callable"
+        ]
+
+        mask_imgs = [
+            load_mask(t_mask, path_only=False, resolution=resolution)[0]
+            for t_mask in mask_files
+        ]
+
+        for t_func in mask_funcs:
+            mask_imgs.append(_available_masks[t_func]["func"](target_img))
+
+        mask_imgs = [
+            resample_to_img(
+                t_mask,
+                target_img,
+                interpolation="nearest",
+                copy=True,
+            )
+            for t_mask in mask_imgs
+        ]
+
+        expected = intersect_masks(mask_imgs, **params)
+        assert_array_equal(computed.get_fdata(), expected.get_fdata())

{junifer-0.0.2.dev138 → junifer-0.0.2.dev140}/junifer/datagrabber/aomic/id1000.py

@@ -7,7 +7,7 @@
 # License: AGPL
 
 from pathlib import Path
-from typing import Union
+from typing import Union, Dict
 
 from junifer.datagrabber import PatternDataladDataGrabber
 
@@ -34,7 +34,9 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
         types = [
             "BOLD",
             "BOLD_confounds",
+            "BOLD_mask",
             "T1w",
+            "T1w_mask",
             "probseg_CSF",
             "probseg_GM",
             "probseg_WM",
@@ -52,11 +54,22 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
                 "sub-{subject}_task-moviewatching_"
                 "desc-confounds_regressors.tsv"
             ),
+            "BOLD_mask": (
+                "derivatives/fmriprep/sub-{subject}/func/"
+                "sub-{subject}_task-moviewatching_"
+                "space-MNI152NLin2009cAsym_"
+                "desc-brain_mask.nii.gz"
+            ),
             "T1w": (
                 "derivatives/fmriprep/sub-{subject}/anat/"
                 "sub-{subject}_space-MNI152NLin2009cAsym_"
                 "desc-preproc_T1w.nii.gz"
             ),
+            "T1w_mask": (
+                "derivatives/fmriprep/sub-{subject}/anat/"
+                "sub-{subject}_space-MNI152NLin2009cAsym_"
+                "desc-brain_mask.nii.gz"
+            ),
             "probseg_CSF": (
                 "derivatives/fmriprep/sub-{subject}/anat/"
                 "sub-{subject}_space-MNI152NLin2009cAsym_label-"
@@ -88,3 +101,22 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
             replacements=replacements,
             confounds_format="fmriprep",
         )
+
+    def get_item(self, subject: str) -> Dict:
+        """Index one element in the dataset.
+
+        Parameters
+        ----------
+        subject : str
+            The subject ID.
+
+        Returns
+        -------
+        out : dict
+            Dictionary of paths for each type of data required for the
+            specified element.
+        """
+        out = super().get_item(subject=subject)
+        out["BOLD"]["mask_item"] = "BOLD_mask"
+        out["T1w"]["mask_item"] = "T1w_mask"
+        return out

{junifer-0.0.2.dev138 → junifer-0.0.2.dev140}/junifer/datagrabber/aomic/piop1.py

@@ -41,7 +41,9 @@ class DataladAOMICPIOP1(PatternDataladDataGrabber):
         types = [
             "BOLD",
             "BOLD_confounds",
+            "BOLD_mask",
             "T1w",
+            "T1w_mask",
             "probseg_CSF",
             "probseg_GM",
             "probseg_WM",
@@ -83,11 +85,21 @@ class DataladAOMICPIOP1(PatternDataladDataGrabber):
                 "sub-{subject}_task-{task}_"
                 "desc-confounds_regressors.tsv"
             ),
+            "BOLD_mask": (
+                "derivatives/fmriprep/sub-{subject}/func/"
+                "sub-{subject}_task-{task}_"
+                "space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz"
+            ),
             "T1w": (
                 "derivatives/fmriprep/sub-{subject}/anat/"
                 "sub-{subject}_space-MNI152NLin2009cAsym_"
                 "desc-preproc_T1w.nii.gz"
             ),
+            "T1w_mask": (
+                "derivatives/fmriprep/sub-{subject}/anat/"
+                "sub-{subject}_space-MNI152NLin2009cAsym_"
+                "desc-brain_mask.nii.gz"
+            ),
             "probseg_CSF": (
                 "derivatives/fmriprep/sub-{subject}/anat/"
                 "sub-{subject}_space-MNI152NLin2009cAsym_label-"
@@ -149,6 +161,8 @@ class DataladAOMICPIOP1(PatternDataladDataGrabber):
         new_task = f"{task}_acq-{acq}"
 
         out = super().get_item(subject=subject, task=new_task)
+        out["BOLD"]["mask_item"] = "BOLD_mask"
+        out["T1w"]["mask_item"] = "T1w_mask"
         return out
 
     def get_elements(self) -> List: