junifer 0.0.5__py3-none-any.whl → 0.0.5.dev24__py3-none-any.whl

junifer/data/__init__.py

@@ -1,4 +1,4 @@
-"""Parcellations, coordinates and masks."""
+"""Provide imports for data sub-package."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Synchon Mandal <s.mandal@fz-juelich.de>
@@ -28,23 +28,3 @@ from .masks import (
 from .template_spaces import get_template, get_xfm
 
 from . import utils
-
-
-__all__ = [
-    "list_coordinates",
-    "load_coordinates",
-    "register_coordinates",
-    "get_coordinates",
-    "list_parcellations",
-    "load_parcellation",
-    "register_parcellation",
-    "merge_parcellations",
-    "get_parcellation",
-    "list_masks",
-    "load_mask",
-    "register_mask",
-    "get_mask",
-    "get_template",
-    "get_xfm",
-    "utils",
-]

junifer/data/coordinates.py

@@ -1,4 +1,4 @@
-"""Functions for coordinates manipulation."""
+"""Provide functions for list of coordinates."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Synchon Mandal <s.mandal@fz-juelich.de>
@@ -13,15 +13,7 @@ import pandas as pd
 from numpy.typing import ArrayLike
 
 from ..pipeline import WorkDirManager
-from ..utils import logger, raise_error, run_ext_cmd
-
-
-__all__ = [
-    "register_coordinates",
-    "list_coordinates",
-    "get_coordinates",
-    "load_coordinates",
-]
+from ..utils import logger, raise_error, run_ext_cmd, warn_with_log
 
 
 # Path to the VOIs
@@ -385,6 +377,11 @@ def load_coordinates(name: str) -> Tuple[ArrayLike, List[str], str]:
     ValueError
         If ``name`` is invalid.
 
+    Warns
+    -----
+    DeprecationWarning
+        If ``Power`` is provided as the ``name``.
+
     """
     # Check for valid coordinates name
     if name not in _available_coordinates:
@@ -392,6 +389,18 @@ def load_coordinates(name: str) -> Tuple[ArrayLike, List[str], str]:
             f"Coordinates {name} not found. "
             f"Valid options are: {list_coordinates()}"
         )
+
+    # Put up deprecation notice
+    if name == "Power":
+        warn_with_log(
+            msg=(
+                "`Power` has been replaced with `Power2011` and will be "
+                "removed in the next release. For now, it's available for "
+                "backward compatibility."
+            ),
+            category=DeprecationWarning,
+        )
+
     # Load coordinates
     t_coord = _available_coordinates[name]
     if isinstance(t_coord.get("path"), Path):

junifer/data/masks.py

@@ -1,4 +1,4 @@
-"""Functions for mask manipulation."""
+"""Provide functions for masks."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Synchon Mandal <s.mandal@fz-juelich.de>
@@ -19,6 +19,7 @@ from typing import (
 
 import nibabel as nib
 import numpy as np
+from nilearn.datasets import fetch_icbm152_brain_gm_mask
 from nilearn.image import get_data, new_img_like, resample_to_img
 from nilearn.masking import (
     compute_background_mask,
@@ -27,7 +28,7 @@ from nilearn.masking import (
 )
 
 from ..pipeline import WorkDirManager
-from ..utils import logger, raise_error, run_ext_cmd
+from ..utils import logger, raise_error, run_ext_cmd, warn_with_log
 from .template_spaces import get_template, get_xfm
 from .utils import closest_resolution
 
@@ -35,16 +36,6 @@ from .utils import closest_resolution
 if TYPE_CHECKING:
     from nibabel import Nifti1Image
 
-
-__all__ = [
-    "compute_brain_mask",
-    "register_mask",
-    "list_masks",
-    "get_mask",
-    "load_mask",
-]
-
-
 # Path to the masks
 _masks_path = Path(__file__).parent / "masks"
 
@@ -130,6 +121,46 @@ def compute_brain_mask(
     return new_img_like(target_img, mask)  # type: ignore
 
 
+def _fetch_icbm152_brain_gm_mask(
+    target_img: "Nifti1Image",
+    **kwargs,
+) -> "Nifti1Image":
+    """Fetch ICBM152 brain mask and resample.
+
+    Parameters
+    ----------
+    target_img : nibabel.Nifti1Image
+        The image to which the mask will be resampled.
+    **kwargs : dict
+        Keyword arguments to be passed to
+        :func:`nilearn.datasets.fetch_icbm152_brain_gm_mask`.
+
+    Returns
+    -------
+    nibabel.Nifti1Image
+        The resampled mask.
+
+    Warns
+    -----
+    DeprecationWarning
+        If this function is used.
+
+    """
+    warn_with_log(
+        msg=(
+            "It is recommended to use ``compute_brain_mask`` with "
+            "``mask_type='gm'``. This function will be removed in the next "
+            "release. For now, it's available for backward compatibility."
+        ),
+        category=DeprecationWarning,
+    )
+    mask = fetch_icbm152_brain_gm_mask(**kwargs)
+    mask = resample_to_img(
+        mask, target_img, interpolation="nearest", copy=True
+    )
+    return mask
+
+
 # A dictionary containing all supported masks and their respective file or
 # data.
 
@@ -163,9 +194,10 @@ _available_masks: Dict[str, Dict[str, Any]] = {
         "func": compute_epi_mask,
         "space": "inherit",
     },
-    "UKB_15K_GM": {
-        "family": "UKB",
-        "space": "MNI152NLin6Asym",
+    "fetch_icbm152_brain_gm_mask": {
+        "family": "Callable",
+        "func": _fetch_icbm152_brain_gm_mask,
+        "space": "MNI152NLin2009aAsym",
     },
 }
 
@@ -260,12 +292,14 @@ def get_mask(  # noqa: C901
     Raises
     ------
     RuntimeError
-        If warp / transformation file extension is not ".mat" or ".h5".
+        If warp / transformation file extension is not ".mat" or ".h5" or
+        if fetch_icbm152_brain_gm_mask is used and requires warping to
+        other template space.
     ValueError
         If extra key is provided in addition to mask name in ``masks`` or
         if no mask is provided or
-        if ``masks = "inherit"`` and ``mask`` key for the ``target_data`` is
-        not found or
+        if ``masks = "inherit"`` but ``extra_input`` is None or ``mask_item``
+        is None or ``mask_items``'s value is not in ``extra_input`` or
         if callable parameters are passed to non-callable mask or
         if parameters are passed to :func:`nilearn.masking.intersect_masks`
         when there is only one mask or
@@ -324,8 +358,8 @@ def get_mask(  # noqa: C901
     if len(true_masks) == 0:
         raise_error("No mask was passed. At least one mask is required.")
 
-    # Get the nested mask data type for the input data type
-    inherited_mask_item = target_data.get("mask", None)
+    # Get the data type for the input data type's mask
+    inherited_mask_item = target_data.get("mask_item", None)
 
     # Create component-scoped tempdir
     tempdir = WorkDirManager().get_tempdir(prefix="masks")
@@ -344,18 +378,45 @@ def get_mask(  # noqa: C901
             mask_name = t_mask
             mask_params = None
 
-        # If mask is being inherited from the datagrabber or a preprocessor,
-        # check that it's accessible
+        # If mask is being inherited from previous steps like preprocessing
         if mask_name == "inherit":
+            # Requires extra input to be passed
+            if extra_input is None:
+                raise_error(
+                    "Cannot inherit mask from another data item "
+                    "because no extra data was passed."
+                )
+            # Missing inherited mask item
             if inherited_mask_item is None:
                 raise_error(
-                    "Cannot inherit mask from the target data. Either the "
-                    "DataGrabber or a Preprocessor does not provide `mask` "
-                    "for the target data type."
+                    "Cannot inherit mask from another data item "
+                    "because no mask item was specified "
+                    "(missing `mask_item` key in the data object)."
                 )
-            mask_img = inherited_mask_item["data"]
+            # Missing inherited mask item in extra input
+            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"]
         # Starting with new mask
         else:
+            # Restrict fetch_icbm152_brain_gm_mask if target std space doesn't
+            # match
+            if (
+                mask_name == "fetch_icbm152_brain_gm_mask"
+                and target_std_space != "MNI152NLin2009aAsym"
+            ):
+                raise_error(
+                    (
+                        "``fetch_icbm152_brain_gm_mask`` is deprecated and "
+                        "space transformation to any other template space is "
+                        "prohibited as it will lead to unforeseen errors. "
+                        "``compute_brain_mask`` is a better alternative."
+                    ),
+                    klass=RuntimeError,
+                )
             # Load mask
             mask_object, _, mask_space = load_mask(
                 mask_name, path_only=False, resolution=resolution
@@ -571,8 +632,6 @@ def load_mask(
     elif t_family == "Callable":
         mask_img = mask_definition["func"]
         mask_fname = None
-    elif t_family == "UKB":
-        mask_fname = _load_ukb_mask(name)
     else:
         raise_error(f"I don't know about the {t_family} mask family.")
 
@@ -638,33 +697,3 @@ def _load_vickery_patil_mask(
     mask_fname = _masks_path / "vickery-patil" / mask_fname
 
     return mask_fname
-
-
-def _load_ukb_mask(name: str) -> Path:
-    """Load UKB mask.
-
-    Parameters
-    ----------
-    name : {"UKB_15K_GM"}
-        The name of the mask.
-
-    Returns
-    -------
-    pathlib.Path
-        File path to the mask image.
-
-    Raises
-    ------
-    ValueError
-        If ``name`` is invalid.
-
-    """
-    if name == "UKB_15K_GM":
-        mask_fname = "UKB_15K_GM_template.nii.gz"
-    else:
-        raise_error(f"Cannot find a UKB mask called {name}")
-
-    # Set path for masks
-    mask_fname = _masks_path / "ukb" / mask_fname
-
-    return mask_fname

junifer/data/parcellations.py

@@ -1,4 +1,4 @@
-"""Functions for parcellation manipulation."""
+"""Provide functions for parcellation."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Vera Komeyer <v.komeyer@fz-juelich.de>
@@ -30,15 +30,6 @@ if TYPE_CHECKING:
     from nibabel import Nifti1Image
 
 
-__all__ = [
-    "register_parcellation",
-    "list_parcellations",
-    "get_parcellation",
-    "load_parcellation",
-    "merge_parcellations",
-]
-
-
 # A dictionary containing all supported parcellations and their respective
 # valid parameters.
 
@@ -335,9 +326,7 @@ def get_parcellation(
             # Call antsApplyTransforms
             run_ext_cmd(name="antsApplyTransforms", cmd=apply_transforms_cmd)
 
-            raw_img = nib.load(warped_parcellation_path)
-            # Remove extra dimension added by ANTs
-            img = image.math_img("np.squeeze(img)", img=raw_img)
+            img = nib.load(warped_parcellation_path)
 
         # Resample parcellation to target image
         img_to_merge = image.resample_to_img(
@@ -898,7 +887,7 @@ def _retrieve_tian(
         )
         with open(parcellation_lname, "w") as filehandle:
             for listitem in labels:
-                filehandle.write(f"{listitem}\n")
+                filehandle.write("%s\n" % listitem)
         logger.info(
             "Currently there are no labels provided for the 7T Tian "
             "parcellation. A simple numbering scheme for distinction was "

junifer/data/template_spaces.py

@@ -1,4 +1,4 @@
-"""Functions for template space manipulation."""
+"""Provide functions for template spaces."""
 
 # Authors: Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
@@ -15,9 +15,6 @@ from ..utils import logger, raise_error
 from .utils import closest_resolution
 
 
-__all__ = ["get_xfm", "get_template"]
-
-
 def get_xfm(
     src: str, dst: str, xfms_dir: Union[str, Path, None] = None
 ) -> Path:  # pragma: no cover

junifer/data/tests/test_masks.py

@@ -22,7 +22,6 @@ from numpy.testing import assert_array_almost_equal, assert_array_equal
 
 from junifer.data.masks import (
     _available_masks,
-    _load_ukb_mask,
     _load_vickery_patil_mask,
     compute_brain_mask,
     get_mask,
@@ -213,7 +212,6 @@ def test_register_mask(
     [
         "GM_prob0.2",
         "GM_prob0.2_cortex",
-        "UKB_15K_GM",
     ],
 )
 def test_list_masks_correct(mask_name: str) -> None:
@@ -293,21 +291,6 @@ def test_vickery_patil_error() -> None:
         _load_vickery_patil_mask(name="wrong", resolution=2.0)
 
 
-def test_ukb() -> None:
-    """Test UKB mask."""
-    mask, mask_fname, space = load_mask("UKB_15K_GM", resolution=2.0)
-    assert_array_almost_equal(mask.header["pixdim"][1:4], 2.0)  # type: ignore
-    assert space == "MNI152NLin6Asym"
-    assert mask_fname is not None
-    assert mask_fname.name == "UKB_15K_GM_template.nii.gz"
-
-
-def test_ukb_error() -> None:
-    """Test error for UKB mask."""
-    with pytest.raises(ValueError, match=r"find a UKB mask "):
-        _load_ukb_mask(name="wrong")
-
-
 def test_get_mask() -> None:
     """Test the get_mask function."""
     with OasisVBMTestingDataGrabber() as dg:
@@ -367,7 +350,7 @@ def test_get_mask_errors() -> None:
         with pytest.raises(ValueError, match=r"callable params"):
             get_mask(masks={"GM_prob0.2": {"param": 1}}, target_data=vbm_gm)
 
-        # Pass only parameters to the intersection function
+        # Pass only parametesr to the intersection function
         with pytest.raises(
             ValueError, match=r" At least one mask is required."
         ):
@@ -382,10 +365,35 @@ def test_get_mask_errors() -> None:
                 target_data=vbm_gm,
             )
 
-        # Test "inherited" masks error
-        with pytest.raises(ValueError, match=r"provide `mask`"):
+        # 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
+            )
+
+        # Block fetch_icbm152_brain_gm_mask space transformation
+        with pytest.raises(RuntimeError, match="prohibited"):
+            get_mask(
+                masks="fetch_icbm152_brain_gm_mask",
+                target_data=vbm_gm,
+                extra_input=extra_input,
+            )
+
 
 @pytest.mark.parametrize(
     "mask_name,function,params,resample",
@@ -457,15 +465,18 @@ def test_get_mask_inherit() -> None:
         )
 
         # Now get the mask using the inherit functionality, passing the
-        # computed mask as the data
-        bold_dict = element_data["BOLD"]
-        bold_dict["mask"] = {
-            "data": gm_mask,
-            "space": element_data["BOLD"]["space"],
+        # computed mask as extra data
+        extra_input = {
+            "BOLD_MASK": {
+                "data": gm_mask,
+                "space": element_data["BOLD"]["space"],
+            }
         }
+        element_data["BOLD"]["mask_item"] = "BOLD_MASK"
         mask2 = get_mask(
             masks="inherit",
-            target_data=bold_dict,
+            target_data=element_data["BOLD"],
+            extra_input=extra_input,
         )
 
         # Both masks should be equal

junifer/data/utils.py

@@ -7,9 +7,6 @@ import numpy as np
 from ..utils.logging import logger
 
 
-__all__ = ["closest_resolution"]
-
-
 def closest_resolution(
     resolution: Optional[Union[float, int]],
     valid_resolution: Union[List[float], List[int], np.ndarray],

junifer/datagrabber/__init__.py

@@ -1,4 +1,4 @@
-"""DataGrabbers for datasets' data description."""
+"""Provide imports for datagrabber sub-package."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Leonard Sasse <l.sasse@fz-juelich.de>
@@ -16,20 +16,3 @@ from .aomic import DataladAOMICID1000, DataladAOMICPIOP1, DataladAOMICPIOP2
 from .hcp1200 import HCP1200, DataladHCP1200
 from .multiple import MultipleDataGrabber
 from .dmcc13_benchmark import DMCC13Benchmark
-
-from .pattern_validation_mixin import PatternValidationMixin
-
-__all__ = [
-    "BaseDataGrabber",
-    "DataladDataGrabber",
-    "PatternDataGrabber",
-    "PatternDataladDataGrabber",
-    "DataladAOMICID1000",
-    "DataladAOMICPIOP1",
-    "DataladAOMICPIOP2",
-    "HCP1200",
-    "DataladHCP1200",
-    "MultipleDataGrabber",
-    "DMCC13Benchmark",
-    "PatternValidationMixin",
-]

junifer/datagrabber/aomic/__init__.py

@@ -7,6 +7,3 @@
 from .id1000 import DataladAOMICID1000
 from .piop1 import DataladAOMICPIOP1
 from .piop2 import DataladAOMICPIOP2
-
-
-__all__ = ["DataladAOMICID1000", "DataladAOMICPIOP1", "DataladAOMICPIOP2"]

junifer/datagrabber/aomic/id1000.py

@@ -14,9 +14,6 @@ from ...api.decorators import register_datagrabber
 from ..pattern_datalad import PatternDataladDataGrabber
 
 
-__all__ = ["DataladAOMICID1000"]
-
-
 @register_datagrabber
 class DataladAOMICID1000(PatternDataladDataGrabber):
     """Concrete implementation for datalad-based data fetching of AOMIC ID1000.
@@ -27,8 +24,8 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
         The directory where the datalad dataset will be cloned. If None,
         the datalad dataset will be cloned into a temporary directory
         (default None).
-    types: {"BOLD", "T1w", "VBM_CSF", "VBM_GM", "VBM_WM", "DWI", \
-           "FreeSurfer"} or list of the options, optional
+    types: {"BOLD", "BOLD_confounds", "T1w", "VBM_CSF", "VBM_GM", \
+           "VBM_WM", "DWI"} or a list of the options, optional
         AOMIC data types. If None, all available data types are selected.
         (default None).
     native_t1w : bool, optional
@@ -51,23 +48,24 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
                     "space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz"
                 ),
                 "space": "MNI152NLin2009cAsym",
-                "mask": {
-                    "pattern": (
-                        "derivatives/fmriprep/{subject}/func/"
-                        "{subject}_task-moviewatching_"
-                        "space-MNI152NLin2009cAsym_"
-                        "desc-brain_mask.nii.gz"
-                    ),
-                    "space": "MNI152NLin2009cAsym",
-                },
-                "confounds": {
-                    "pattern": (
-                        "derivatives/fmriprep/{subject}/func/"
-                        "{subject}_task-moviewatching_"
-                        "desc-confounds_regressors.tsv"
-                    ),
-                    "format": "fmriprep",
-                },
+                "mask_item": "BOLD_mask",
+            },
+            "BOLD_confounds": {
+                "pattern": (
+                    "derivatives/fmriprep/{subject}/func/"
+                    "{subject}_task-moviewatching_"
+                    "desc-confounds_regressors.tsv"
+                ),
+                "format": "fmriprep",
+            },
+            "BOLD_mask": {
+                "pattern": (
+                    "derivatives/fmriprep/{subject}/func/"
+                    "{subject}_task-moviewatching_"
+                    "space-MNI152NLin2009cAsym_"
+                    "desc-brain_mask.nii.gz"
+                ),
+                "space": "MNI152NLin2009cAsym",
             },
             "T1w": {
                 "pattern": (
@@ -76,14 +74,15 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
                     "desc-preproc_T1w.nii.gz"
                 ),
                 "space": "MNI152NLin2009cAsym",
-                "mask": {
-                    "pattern": (
-                        "derivatives/fmriprep/{subject}/anat/"
-                        "{subject}_space-MNI152NLin2009cAsym_"
-                        "desc-brain_mask.nii.gz"
-                    ),
-                    "space": "MNI152NLin2009cAsym",
-                },
+                "mask_item": "T1w_mask",
+            },
+            "T1w_mask": {
+                "pattern": (
+                    "derivatives/fmriprep/{subject}/anat/"
+                    "{subject}_space-MNI152NLin2009cAsym_"
+                    "desc-brain_mask.nii.gz"
+                ),
+                "space": "MNI152NLin2009cAsym",
             },
             "VBM_CSF": {
                 "pattern": (
@@ -115,39 +114,6 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
                     "{subject}_desc-preproc_dwi.nii.gz"
                 ),
             },
-            "FreeSurfer": {
-                "pattern": "derivatives/freesurfer/[!f]{subject}/mri/T1.mg[z]",
-                "aseg": {
-                    "pattern": (
-                        "derivatives/freesurfer/[!f]{subject}/mri/aseg.mg[z]"
-                    )
-                },
-                "norm": {
-                    "pattern": (
-                        "derivatives/freesurfer/[!f]{subject}/mri/norm.mg[z]"
-                    )
-                },
-                "lh_white": {
-                    "pattern": (
-                        "derivatives/freesurfer/[!f]{subject}/surf/lh.whit[e]"
-                    )
-                },
-                "rh_white": {
-                    "pattern": (
-                        "derivatives/freesurfer/[!f]{subject}/surf/rh.whit[e]"
-                    )
-                },
-                "lh_pial": {
-                    "pattern": (
-                        "derivatives/freesurfer/[!f]{subject}/surf/lh.pia[l]"
-                    )
-                },
-                "rh_pial": {
-                    "pattern": (
-                        "derivatives/freesurfer/[!f]{subject}/surf/rh.pia[l]"
-                    )
-                },
-            },
         }
         # Use native T1w assets
         self.native_t1w = False
@@ -161,13 +127,14 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
                             "{subject}_desc-preproc_T1w.nii.gz"
                         ),
                         "space": "native",
-                        "mask": {
-                            "pattern": (
-                                "derivatives/fmriprep/{subject}/anat/"
-                                "{subject}_desc-brain_mask.nii.gz"
-                            ),
-                            "space": "native",
-                        },
+                        "mask_item": "T1w_mask",
+                    },
+                    "T1w_mask": {
+                        "pattern": (
+                            "derivatives/fmriprep/{subject}/anat/"
+                            "{subject}_desc-brain_mask.nii.gz"
+                        ),
+                        "space": "native",
                     },
                     "Warp": {
                         "pattern": (