junifer 0.0.4.dev829__py3-none-any.whl → 0.0.5__py3-none-any.whl

junifer/data/__init__.py

@@ -1,4 +1,4 @@
-"""Provide imports for data sub-package."""
+"""Parcellations, coordinates and masks."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Synchon Mandal <s.mandal@fz-juelich.de>
@@ -28,3 +28,23 @@ 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 @@
-"""Provide functions for list of coordinates."""
+"""Functions for coordinates manipulation."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Synchon Mandal <s.mandal@fz-juelich.de>
@@ -13,7 +13,15 @@ import pandas as pd
 from numpy.typing import ArrayLike
 
 from ..pipeline import WorkDirManager
-from ..utils import logger, raise_error, run_ext_cmd, warn_with_log
+from ..utils import logger, raise_error, run_ext_cmd
+
+
+__all__ = [
+    "register_coordinates",
+    "list_coordinates",
+    "get_coordinates",
+    "load_coordinates",
+]
 
 
 # Path to the VOIs
@@ -377,11 +385,6 @@ 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:
@@ -389,18 +392,6 @@ 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 @@
-"""Provide functions for masks."""
+"""Functions for mask manipulation."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Synchon Mandal <s.mandal@fz-juelich.de>
@@ -19,7 +19,6 @@ 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,
@@ -28,7 +27,7 @@ from nilearn.masking import (
 )
 
 from ..pipeline import WorkDirManager
-from ..utils import logger, raise_error, run_ext_cmd, warn_with_log
+from ..utils import logger, raise_error, run_ext_cmd
 from .template_spaces import get_template, get_xfm
 from .utils import closest_resolution
 
@@ -36,6 +35,16 @@ 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"
 
@@ -121,46 +130,6 @@ 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.
 
@@ -194,10 +163,9 @@ _available_masks: Dict[str, Dict[str, Any]] = {
         "func": compute_epi_mask,
         "space": "inherit",
     },
-    "fetch_icbm152_brain_gm_mask": {
-        "family": "Callable",
-        "func": _fetch_icbm152_brain_gm_mask,
-        "space": "MNI152NLin2009aAsym",
+    "UKB_15K_GM": {
+        "family": "UKB",
+        "space": "MNI152NLin6Asym",
     },
 }
 
@@ -292,14 +260,12 @@ def get_mask(  # noqa: C901
     Raises
     ------
     RuntimeError
-        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.
+        If warp / transformation file extension is not ".mat" or ".h5".
     ValueError
         If extra key is provided in addition to mask name in ``masks`` or
         if no mask is provided 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 ``masks = "inherit"`` and ``mask`` key for the ``target_data`` is
+        not found 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
@@ -358,8 +324,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 data type for the input data type's mask
-    inherited_mask_item = target_data.get("mask_item", None)
+    # Get the nested mask data type for the input data type
+    inherited_mask_item = target_data.get("mask", None)
 
     # Create component-scoped tempdir
     tempdir = WorkDirManager().get_tempdir(prefix="masks")
@@ -378,45 +344,18 @@ def get_mask(  # noqa: C901
             mask_name = t_mask
             mask_params = None
 
-        # If mask is being inherited from previous steps like preprocessing
+        # If mask is being inherited from the datagrabber or a preprocessor,
+        # check that it's accessible
         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 another data item "
-                    "because no mask item was specified "
-                    "(missing `mask_item` key in the data object)."
+                    "Cannot inherit mask from the target data. Either the "
+                    "DataGrabber or a Preprocessor does not provide `mask` "
+                    "for the target data type."
                 )
-            # 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"]
+            mask_img = 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
@@ -632,6 +571,8 @@ 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.")
 
@@ -697,3 +638,33 @@ 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 @@
-"""Provide functions for parcellation."""
+"""Functions for parcellation manipulation."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Vera Komeyer <v.komeyer@fz-juelich.de>
@@ -30,6 +30,15 @@ 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.
 
@@ -326,7 +335,9 @@ def get_parcellation(
             # Call antsApplyTransforms
             run_ext_cmd(name="antsApplyTransforms", cmd=apply_transforms_cmd)
 
-            img = nib.load(warped_parcellation_path)
+            raw_img = nib.load(warped_parcellation_path)
+            # Remove extra dimension added by ANTs
+            img = image.math_img("np.squeeze(img)", img=raw_img)
 
         # Resample parcellation to target image
         img_to_merge = image.resample_to_img(
@@ -887,7 +898,7 @@ def _retrieve_tian(
         )
         with open(parcellation_lname, "w") as filehandle:
             for listitem in labels:
-                filehandle.write("%s\n" % listitem)
+                filehandle.write(f"{listitem}\n")
         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 @@
-"""Provide functions for template spaces."""
+"""Functions for template space manipulation."""
 
 # Authors: Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
@@ -15,6 +15,9 @@ 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,6 +22,7 @@ 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,
@@ -212,6 +213,7 @@ def test_register_mask(
     [
         "GM_prob0.2",
         "GM_prob0.2_cortex",
+        "UKB_15K_GM",
     ],
 )
 def test_list_masks_correct(mask_name: str) -> None:
@@ -291,6 +293,21 @@ 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:
@@ -350,7 +367,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 parametesr to the intersection function
+        # Pass only parameters to the intersection function
         with pytest.raises(
             ValueError, match=r" At least one mask is required."
         ):
@@ -365,35 +382,10 @@ def test_get_mask_errors() -> None:
                 target_data=vbm_gm,
             )
 
-        # Test "inherited" masks errors
-
-        # 1) No extra_data parameter
-        with pytest.raises(ValueError, match=r"no extra data was passed"):
+        # Test "inherited" masks error
+        with pytest.raises(ValueError, match=r"provide `mask`"):
             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",
@@ -465,18 +457,15 @@ def test_get_mask_inherit() -> None:
         )
 
         # Now get the mask using the inherit functionality, passing the
-        # computed mask as extra data
-        extra_input = {
-            "BOLD_MASK": {
-                "data": gm_mask,
-                "space": element_data["BOLD"]["space"],
-            }
+        # computed mask as the data
+        bold_dict = element_data["BOLD"]
+        bold_dict["mask"] = {
+            "data": gm_mask,
+            "space": element_data["BOLD"]["space"],
         }
-        element_data["BOLD"]["mask_item"] = "BOLD_MASK"
         mask2 = get_mask(
             masks="inherit",
-            target_data=element_data["BOLD"],
-            extra_input=extra_input,
+            target_data=bold_dict,
         )
 
         # Both masks should be equal

junifer/data/utils.py

@@ -7,6 +7,9 @@ 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 @@
-"""Provide imports for datagrabber sub-package."""
+"""DataGrabbers for datasets' data description."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Leonard Sasse <l.sasse@fz-juelich.de>
@@ -16,3 +16,20 @@ 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,3 +7,6 @@
 from .id1000 import DataladAOMICID1000
 from .piop1 import DataladAOMICPIOP1
 from .piop2 import DataladAOMICPIOP2
+
+
+__all__ = ["DataladAOMICID1000", "DataladAOMICPIOP1", "DataladAOMICPIOP2"]

junifer/datagrabber/aomic/id1000.py

@@ -14,6 +14,9 @@ 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.
@@ -24,8 +27,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", "BOLD_confounds", "T1w", "VBM_CSF", "VBM_GM", \
-           "VBM_WM", "DWI"} or a list of the options, optional
+    types: {"BOLD", "T1w", "VBM_CSF", "VBM_GM", "VBM_WM", "DWI", \
+           "FreeSurfer"} or list of the options, optional
         AOMIC data types. If None, all available data types are selected.
         (default None).
     native_t1w : bool, optional
@@ -48,24 +51,23 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
                     "space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz"
                 ),
                 "space": "MNI152NLin2009cAsym",
-                "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",
+                "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",
+                },
             },
             "T1w": {
                 "pattern": (
@@ -74,15 +76,14 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
                     "desc-preproc_T1w.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",
+                "mask": {
+                    "pattern": (
+                        "derivatives/fmriprep/{subject}/anat/"
+                        "{subject}_space-MNI152NLin2009cAsym_"
+                        "desc-brain_mask.nii.gz"
+                    ),
+                    "space": "MNI152NLin2009cAsym",
+                },
             },
             "VBM_CSF": {
                 "pattern": (
@@ -114,6 +115,39 @@ 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
@@ -127,14 +161,13 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
                             "{subject}_desc-preproc_T1w.nii.gz"
                         ),
                         "space": "native",
-                        "mask_item": "T1w_mask",
-                    },
-                    "T1w_mask": {
-                        "pattern": (
-                            "derivatives/fmriprep/{subject}/anat/"
-                            "{subject}_desc-brain_mask.nii.gz"
-                        ),
-                        "space": "native",
+                        "mask": {
+                            "pattern": (
+                                "derivatives/fmriprep/{subject}/anat/"
+                                "{subject}_desc-brain_mask.nii.gz"
+                            ),
+                            "space": "native",
+                        },
                     },
                     "Warp": {
                         "pattern": (