junifer 0.0.4.dev108__tar.gz → 0.0.4.dev133__tar.gz

{junifer-0.0.4.dev108 → junifer-0.0.4.dev133}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: junifer
-Version: 0.0.4.dev108
+Version: 0.0.4.dev133
 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.4.dev133/docs/changes/newsfragments/264.feature

@@ -0,0 +1 @@
+Introduce :func:`.get_parcellation` to fetch parcellation tailored for the data by `Synchon Mandal`_

junifer-0.0.4.dev133/docs/changes/newsfragments/265.feature

@@ -0,0 +1 @@
+Introduce :func:`.get_coordinates` to fetch coordinates tailored for the data by `Synchon Mandal`_

{junifer-0.0.4.dev108 → junifer-0.0.4.dev133}/junifer/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.0.4.dev108'
-__version_tuple__ = version_tuple = (0, 0, 4, 'dev108')
+__version__ = version = '0.0.4.dev133'
+__version_tuple__ = version_tuple = (0, 0, 4, 'dev133')

{junifer-0.0.4.dev108 → junifer-0.0.4.dev133}/junifer/data/__init__.py

@@ -8,12 +8,14 @@ from .coordinates import (
     list_coordinates,
     load_coordinates,
     register_coordinates,
+    get_coordinates,
 )
 from .parcellations import (
     list_parcellations,
     load_parcellation,
     register_parcellation,
     merge_parcellations,
+    get_parcellation,
 )
 
 from .masks import (

{junifer-0.0.4.dev108 → junifer-0.0.4.dev133}/junifer/data/coordinates.py

@@ -1,11 +1,12 @@
 """Provide functions for list of coordinates."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
 import typing
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple, Union
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 import numpy as np
 import pandas as pd
@@ -57,7 +58,7 @@ def register_coordinates(
     voi_names: List[str],
     overwrite: Optional[bool] = False,
 ) -> None:
-    """Register coordinates.
+    """Register a custom user coordinates.
 
     Parameters
     ----------
@@ -73,6 +74,18 @@ def register_coordinates(
     overwrite : bool, optional
         If True, overwrite an existing list of coordinates with the same name.
         Does not apply to built-in coordinates (default False).
+
+    Raises
+    ------
+    ValueError
+        If the coordinates name is already registered and overwrite is set to
+        False or if the coordinates name is a built-in coordinates or if the
+        ``coordinates`` is not a 2D array or if coordinate value does not have
+        3 components or if the ``voi_names`` shape does not match the
+        ``coordinates`` shape.
+    TypeError
+        If ``coordinates`` is not a ``numpy.ndarray``.
+
     """
     if name in _available_coordinates:
         if isinstance(_available_coordinates[name], Path):
@@ -90,7 +103,8 @@ def register_coordinates(
 
     if not isinstance(coordinates, np.ndarray):
         raise_error(
-            f"Coordinates must be a numpy.ndarray, not {type(coordinates)}."
+            f"Coordinates must be a `numpy.ndarray`, not {type(coordinates)}.",
+            klass=TypeError,
         )
     if coordinates.ndim != 2:
         raise_error(
@@ -102,8 +116,8 @@ def register_coordinates(
         )
     if len(voi_names) != coordinates.shape[0]:
         raise_error(
-            f"Length of voi_names ({len(voi_names)}) does not match the "
-            f"number of coordinates ({coordinates.shape[0]})."
+            f"Length of `voi_names` ({len(voi_names)}) does not match the "
+            f"number of `coordinates` ({coordinates.shape[0]})."
         )
     _available_coordinates[name] = {
         "coords": coordinates,
@@ -112,16 +126,55 @@ def register_coordinates(
 
 
 def list_coordinates() -> List[str]:
-    """List all the available coordinates lists (VOIs).
+    """List all the available coordinates (VOIs).
 
     Returns
     -------
     list of str
         A list with all available coordinates names.
+
     """
     return sorted(_available_coordinates.keys())
 
 
+def get_coordinates(
+    coords: str,
+    target_data: Dict[str, Any],
+    extra_input: Optional[Dict[str, Any]] = None,
+) -> Tuple[ArrayLike, List[str]]:
+    """Get coordinates, tailored for the target image.
+
+    Parameters
+    ----------
+    coords : str
+        The name of the coordinates.
+    target_data : dict
+        The corresponding item of the data object to which the coordinates
+        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 coordinates
+        (default None).
+
+    Returns
+    -------
+    numpy.ndarray
+        The coordinates.
+    list of str
+        The names of the VOIs.
+
+    Raises
+    ------
+    ValueError
+        If ``extra_input`` is None when ``target_data``'s space is not MNI.
+
+    """
+    # Load the coordinates
+    seeds, labels = load_coordinates(name=coords)
+
+    return seeds, labels
+
+
 def load_coordinates(name: str) -> Tuple[ArrayLike, List[str]]:
     """Load coordinates.
 
@@ -137,14 +190,23 @@ def load_coordinates(name: str) -> Tuple[ArrayLike, List[str]]:
     list of str
         The names of the VOIs.
 
+    Raises
+    ------
+    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:
-        raise_error(f"Coordinates {name} not found.")
+        raise_error(
+            f"Coordinates {name} not found. "
+            f"Valid options are: {list_coordinates()}"
+        )
 
     # Put up deprecation notice
     if name == "Power":
@@ -157,8 +219,10 @@ def load_coordinates(name: str) -> Tuple[ArrayLike, List[str]]:
             category=DeprecationWarning,
         )
 
+    # Load coordinates
     t_coord = _available_coordinates[name]
     if isinstance(t_coord, Path):
+        # Load via pandas
         df_coords = pd.read_csv(t_coord, sep="\t", header=None)
         coords = df_coords.iloc[:, [0, 1, 2]].to_numpy()
         names = list(df_coords.iloc[:, [3]].values[:, 0])
@@ -167,4 +231,5 @@ def load_coordinates(name: str) -> Tuple[ArrayLike, List[str]]:
         coords = typing.cast(ArrayLike, coords)
         names = t_coord["voi_names"]
         names = typing.cast(List[str], names)
+
     return coords, names

{junifer-0.0.4.dev108 → junifer-0.0.4.dev133}/junifer/data/parcellations.py

@@ -9,6 +9,7 @@ import io
 import shutil
 import tarfile
 import tempfile
+import typing
 import zipfile
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
@@ -161,8 +162,8 @@ def register_parcellation(
                 )
         else:
             raise_error(
-                f"Parcellation {name} already registered. Set `overwrite=True`"
-                "to update its value."
+                f"Parcellation {name} already registered. Set "
+                "`overwrite=True` to update its value."
             )
     # Convert str to Path
     if not isinstance(parcellation_path, Path):
@@ -187,12 +188,68 @@ def list_parcellations() -> List[str]:
     return sorted(_available_parcellations.keys())
 
 
-# def _check_resolution(resolution, valid_resolution):
-#     if resolution is None:
-#         return None
-#     if resolution not in valid_resolution:
-#         raise ValueError(f'Invalid resolution: {resolution}')
-#     return resolution
+def get_parcellation(
+    parcellation: List[str],
+    target_data: Dict[str, Any],
+    extra_input: Optional[Dict[str, Any]] = None,
+) -> Tuple["Nifti1Image", List[str]]:
+    """Get parcellation, tailored for the target image.
+
+    Parameters
+    ----------
+    parcellation : list of str
+        The name(s) of the parcellation(s).
+    target_data : dict
+        The corresponding item of the data object to which the parcellation
+        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 parcellations
+        (default None).
+
+    Returns
+    -------
+    Nifti1Image
+        The parcellation image.
+    list of str
+        Parcellation labels.
+
+    """
+    # Get the min of the voxels sizes and use it as the resolution
+    target_img = target_data["data"]
+    resolution = np.min(target_img.header.get_zooms()[:3])
+
+    # Load the parcellations
+    all_parcellations = []
+    all_labels = []
+    for name in parcellation:
+        img, labels, _ = load_parcellation(
+            name=name,
+            resolution=resolution,
+        )
+        # Resample all of them to the image
+        resampled_img = image.resample_to_img(
+            source_img=img,
+            target_img=target_img,
+            interpolation="nearest",
+            copy=True,
+        )
+        all_parcellations.append(resampled_img)
+        all_labels.append(labels)
+
+    # Avoid merging if there is only one parcellation
+    if len(all_parcellations) == 1:
+        resampled_parcellation_img = all_parcellations[0]
+        labels = all_labels[0]
+    else:
+        # Merge the parcellations
+        resampled_parcellation_img, labels = merge_parcellations(
+            parcellations_list=all_parcellations,
+            parcellations_names=parcellation,
+            labels_lists=all_labels,
+        )
+
+    return resampled_parcellation_img, labels
 
 
 def load_parcellation(
@@ -203,8 +260,8 @@ def load_parcellation(
 ) -> Tuple[Optional["Nifti1Image"], List[str], Path]:
     """Load a brain parcellation (including a label file).
 
-    If it is a built-in parcellaions and file is not present in the
-    `parcellations_dir` directory, it will be downloaded.
+    If it is a built-in parcellation and the file is not present in the
+    ``parcellations_dir`` directory, it will be downloaded.
 
     Parameters
     ----------
@@ -231,17 +288,25 @@ def load_parcellation(
     pathlib.Path
         File path to the parcellation image.
 
+    Raises
+    ------
+    ValueError
+        If ``name`` is invalid or if the parcellation values and labels
+        don't have equal dimension or if the value range is invalid.
+
     """
-    # Invalid parcellation name
+    # Check for valid parcellation name
     if name not in _available_parcellations:
         raise_error(
             f"Parcellation {name} not found. "
             f"Valid options are: {list_parcellations()}"
         )
 
+    # Copy parcellation definition to avoid edits in original object
     parcellation_definition = _available_parcellations[name].copy()
     t_family = parcellation_definition.pop("family")
 
+    # Check if the parcellation family is custom or built-in
     if t_family == "CustomUserParcellation":
         parcellation_fname = Path(parcellation_definition["path"])
         parcellation_labels = parcellation_definition["labels"]
@@ -253,24 +318,31 @@ def load_parcellation(
             **parcellation_definition,
         )
 
+    # Load parcellation image and values
     logger.info(f"Loading parcellation {parcellation_fname.absolute()!s}")
-
     parcellation_img = None
     if path_only is False:
+        # Load image via nibabel
         parcellation_img = nib.load(parcellation_fname)
+        # Get unique values
         parcel_values = np.unique(parcellation_img.get_fdata())
+        # Check for dimension
         if len(parcel_values) - 1 != len(parcellation_labels):
             raise_error(
                 f"Parcellation {name} has {len(parcel_values) - 1} parcels "
                 f"but {len(parcellation_labels)} labels."
             )
+        # Sort values
         parcel_values.sort()
+        # Check if value range is invalid
         if np.any(np.diff(parcel_values) != 1):
             raise_error(
                 f"Parcellation {name} must have all the values in the range  "
                 f"[0, {len(parcel_values)}]."
             )
 
+    # Type-cast to remove errors
+    parcellation_img = typing.cast("Nifti1Image", parcellation_img)
     return parcellation_img, parcellation_labels, parcellation_fname
 
 

{junifer-0.0.4.dev108 → junifer-0.0.4.dev133}/junifer/data/tests/test_coordinates.py

@@ -8,10 +8,13 @@ import pytest
 from numpy.testing import assert_array_equal
 
 from junifer.data.coordinates import (
+    get_coordinates,
     list_coordinates,
     load_coordinates,
     register_coordinates,
 )
+from junifer.datareader import DefaultDataReader
+from junifer.testing.datagrabbers import OasisVBMTestingDataGrabber
 
 
 def test_register_coordinates_built_in_check() -> None:
@@ -54,7 +57,7 @@ def test_register_coordinates_overwrite() -> None:
 
 def test_register_coordinates_valid_input() -> None:
     """Test coordinates registration check for valid input."""
-    with pytest.raises(ValueError, match=r"numpy.ndarray"):
+    with pytest.raises(TypeError, match=r"numpy.ndarray"):
         register_coordinates(
             name="MyList",
             coordinates=[1, 2],
@@ -105,3 +108,21 @@ def test_load_coordinates_nonexisting() -> None:
     """Test loading coordinates that not exist."""
     with pytest.raises(ValueError, match=r"not found"):
         load_coordinates("NonExisting")
+
+
+def test_get_coordinates() -> None:
+    """Test tailored coordinates fetch."""
+    reader = DefaultDataReader()
+    with OasisVBMTestingDataGrabber() as dg:
+        element = dg["sub-01"]
+        element_data = reader.fit_transform(element)
+        vbm_gm = element_data["VBM_GM"]
+        # Get tailored coordinates
+        tailored_coords, tailored_labels = get_coordinates(
+            coords="DMNBuckner", target_data=vbm_gm
+        )
+        # Get raw coordinates
+        raw_coords, raw_labels = load_coordinates("DMNBuckner")
+        # Both tailored and raw should be same for now
+        assert_array_equal(tailored_coords, raw_coords)
+        assert tailored_labels == raw_labels

{junifer-0.0.4.dev108 → junifer-0.0.4.dev133}/junifer/data/tests/test_parcellations.py

@@ -11,7 +11,7 @@ from typing import List
 import nibabel as nib
 import numpy as np
 import pytest
-from nilearn.image import new_img_like
+from nilearn.image import new_img_like, resample_to_img
 from numpy.testing import assert_array_almost_equal, assert_array_equal
 
 from junifer.data.parcellations import (
@@ -22,11 +22,14 @@ from junifer.data.parcellations import (
     _retrieve_suit,
     _retrieve_tian,
     _retrieve_yan,
+    get_parcellation,
     list_parcellations,
     load_parcellation,
     merge_parcellations,
     register_parcellation,
 )
+from junifer.datareader import DefaultDataReader
+from junifer.testing.datagrabbers import OasisVBMTestingDataGrabber
 
 
 def test_register_parcellation_built_in_check() -> None:
@@ -1078,3 +1081,89 @@ def test_merge_parcellations_3D_multiple_duplicated_labels(
     assert_array_equal(parc_data, merged_parc.get_fdata())
     assert len(labels) == 100
     assert len(np.unique(parc_data)) == 101  # 100 + 1 because background 0
+
+
+def test_get_parcellation_single() -> None:
+    """Test tailored single parcellation fetch."""
+    reader = DefaultDataReader()
+    with OasisVBMTestingDataGrabber() as dg:
+        element = dg["sub-01"]
+        element_data = reader.fit_transform(element)
+        vbm_gm = element_data["VBM_GM"]
+        vbm_gm_img = vbm_gm["data"]
+        # Get tailored parcellation
+        tailored_parcellation, tailored_labels = get_parcellation(
+            parcellation=["Schaefer100x7"],
+            target_data=vbm_gm,
+        )
+        # Check shape and affine with original element data
+        assert tailored_parcellation.shape == vbm_gm_img.shape
+        assert_array_equal(tailored_parcellation.affine, vbm_gm_img.affine)
+        # Get raw parcellation
+        raw_parcellation, raw_labels, _ = load_parcellation(
+            "Schaefer100x7",
+            resolution=1.5,
+        )
+        resampled_raw_parcellation = resample_to_img(
+            source_img=raw_parcellation,
+            target_img=vbm_gm_img,
+            interpolation="nearest",
+            copy=True,
+        )
+        # Check resampled data with tailored data
+        assert_array_equal(
+            tailored_parcellation.get_fdata(),
+            resampled_raw_parcellation.get_fdata(),
+        )
+        assert tailored_labels == raw_labels
+
+
+def test_get_parcellation_multi() -> None:
+    """Test tailored multi parcellation fetch."""
+    reader = DefaultDataReader()
+    with OasisVBMTestingDataGrabber() as dg:
+        element = dg["sub-01"]
+        element_data = reader.fit_transform(element)
+        vbm_gm = element_data["VBM_GM"]
+        vbm_gm_img = vbm_gm["data"]
+        # Get tailored parcellation
+        tailored_parcellation, tailored_labels = get_parcellation(
+            parcellation=[
+                "Schaefer100x7",
+                "TianxS2x3TxMNInonlinear2009cAsym",
+            ],
+            target_data=vbm_gm,
+        )
+        # Check shape and affine with original element data
+        assert tailored_parcellation.shape == vbm_gm_img.shape
+        assert_array_equal(tailored_parcellation.affine, vbm_gm_img.affine)
+        # Get raw parcellations
+        raw_parcellations = []
+        raw_labels = []
+        parcellations_names = [
+            "Schaefer100x7",
+            "TianxS2x3TxMNInonlinear2009cAsym",
+        ]
+        for name in parcellations_names:
+            img, labels, _ = load_parcellation(name=name, resolution=1.5)
+            # Resample raw parcellations
+            resampled_img = resample_to_img(
+                source_img=img,
+                target_img=vbm_gm_img,
+                interpolation="nearest",
+                copy=True,
+            )
+            raw_parcellations.append(resampled_img)
+            raw_labels.append(labels)
+        # Merge resampled parcellations
+        merged_resampled_parcellations, merged_labels = merge_parcellations(
+            parcellations_list=raw_parcellations,
+            parcellations_names=parcellations_names,
+            labels_lists=raw_labels,
+        )
+        # Check resampled data with tailored data
+        assert_array_equal(
+            tailored_parcellation.get_fdata(),
+            merged_resampled_parcellations.get_fdata(),
+        )
+        assert tailored_labels == merged_labels

{junifer-0.0.4.dev108 → junifer-0.0.4.dev133}/junifer/markers/parcel_aggregation.py

@@ -7,11 +7,11 @@
 from typing import Any, ClassVar, Dict, List, Optional, Set, Union
 
 import numpy as np
-from nilearn.image import math_img, resample_to_img
+from nilearn.image import math_img
 from nilearn.maskers import NiftiMasker
 
 from ..api.decorators import register_marker
-from ..data import get_mask, load_parcellation, merge_parcellations
+from ..data import get_mask, get_parcellation
 from ..stats import get_aggfunc_by_name
 from ..utils import logger, raise_error, warn_with_log
 from .base import BaseMarker
@@ -49,6 +49,13 @@ class ParcelAggregation(BaseMarker):
     name : str, optional
         The name of the marker. If None, will use the class name (default
         None).
+
+    Raises
+    ------
+    ValueError
+        If ``time_method`` is specified for non-BOLD data or if
+        ``time_method_params`` is not None when ``time_method`` is None.
+
     """
 
     _DEPENDENCIES: ClassVar[Set[str]] = {"nilearn", "numpy"}
@@ -110,6 +117,11 @@ class ParcelAggregation(BaseMarker):
         str
             The storage type output by the marker.
 
+        Raises
+        ------
+        ValueError
+            If the ``input_type`` is invalid.
+
         """
 
         if input_type in ["VBM_GM", "VBM_WM", "fALFF", "GCOR", "LCOR"]:
@@ -117,7 +129,7 @@ class ParcelAggregation(BaseMarker):
         elif input_type == "BOLD":
             return "timeseries"
         else:
-            raise ValueError(f"Unknown input kind for {input_type}")
+            raise_error(f"Unknown input kind for {input_type}")
 
     def compute(
         self, input: Dict[str, Any], extra_input: Optional[Dict] = None
@@ -145,62 +157,53 @@ class ParcelAggregation(BaseMarker):
             * ``data`` : the actual computed values as a numpy.ndarray
             * ``col_names`` : the column labels for the computed values as list
 
+        Warns
+        -----
+        RuntimeWarning
+            If time aggregation is required but only time point is available.
+
         """
         t_input_img = input["data"]
         logger.debug(f"Parcel aggregation using {self.method}")
+        # Get aggregation function
         agg_func = get_aggfunc_by_name(
             name=self.method, func_params=self.method_params
         )
-        # Get the min of the voxels sizes and use it as the resolution
-        resolution = np.min(t_input_img.header.get_zooms()[:3])
-
-        # Load the parcellations
-        all_parcelations = []
-        all_labels = []
-        for t_parc_name in self.parcellation:
-            t_parcellation, t_labels, _ = load_parcellation(
-                name=t_parc_name, resolution=resolution
-            )
-            # Resample all of them to the image
-            t_parcellation_img_res = resample_to_img(
-                t_parcellation, t_input_img, interpolation="nearest", copy=True
-            )
-            all_parcelations.append(t_parcellation_img_res)
-            all_labels.append(t_labels)
 
-        # Avoid merging if there is only one parcellation
-        if len(all_parcelations) == 1:
-            parcellation_img_res = all_parcelations[0]
-            labels = all_labels[0]
-        else:
-            # Merge the parcellations
-            parcellation_img_res, labels = merge_parcellations(
-                all_parcelations, self.parcellation, all_labels
-            )
+        # Get parcellation tailored to target image
+        parcellation_img, labels = get_parcellation(
+            parcellation=self.parcellation,
+            target_data=input,
+            extra_input=extra_input,
+        )
 
-        parcellation_bin = math_img("img != 0", img=parcellation_img_res)
+        # Get binarized parcellation image for masking
+        parcellation_bin = math_img("img != 0", img=parcellation_img)
 
+        # Load mask
         if self.masks is not None:
             logger.debug(f"Masking with {self.masks}")
+            # Get tailored mask
             mask_img = get_mask(
                 masks=self.masks, target_data=input, extra_input=extra_input
             )
-
+            # Get "logical and" version of parcellation and mask
             parcellation_bin = math_img(
                 "np.logical_and(img, mask)",
                 img=parcellation_bin,
                 mask=mask_img,
             )
 
+        # Initialize masker
         logger.debug("Masking")
         masker = NiftiMasker(
             parcellation_bin, target_affine=t_input_img.affine
-        )  # type: ignore
-
+        )
         # Mask the input data and the parcellation
         data = masker.fit_transform(t_input_img)
-        parcellation_values = masker.transform(parcellation_img_res)
-        parcellation_values = np.squeeze(parcellation_values).astype(int)
+        parcellation_values = np.squeeze(
+            masker.transform(parcellation_img)
+        ).astype(int)
 
         # Get the values for each parcel and apply agg function
         logger.debug("Computing ROI means")
@@ -214,6 +217,7 @@ class ParcelAggregation(BaseMarker):
 
         out_values = np.array(out_values).T
 
+        # Apply time dimension aggregation if required
         if self.time_method is not None:
             if out_values.shape[0] > 1:
                 logger.debug("Aggregating time dimension")
@@ -226,5 +230,6 @@ class ParcelAggregation(BaseMarker):
                     "No time dimension to aggregate as only one time point is "
                     "available."
                 )
+        # Format the output
         out = {"data": out_values, "col_names": labels}
         return out