junifer 0.0.7.dev332__py3-none-any.whl → 0.0.8__py3-none-any.whl

junifer/markers/maps_aggregation.py

@@ -3,20 +3,36 @@
 # Authors: Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
-from typing import Any, ClassVar, Optional, Union
+from typing import Annotated, Any, ClassVar, Literal
 
+import numpy as np
 from nilearn.maskers import NiftiMapsMasker
+from pydantic import BeforeValidator
 
 from ..api.decorators import register_marker
 from ..data import get_data
+from ..datagrabber import DataType
 from ..stats import get_aggfunc_by_name
+from ..storage import StorageType
 from ..typing import Dependencies, MarkerInOutMappings
-from ..utils import logger, raise_error, warn_with_log
-from .base import BaseMarker
+from ..utils import ensure_list_or_none, raise_error, warn_with_log
+from .base import BaseMarker, logger
 
 
 __all__ = ["MapsAggregation"]
 
+_on = Literal[
+    DataType.T1w,
+    DataType.T2w,
+    DataType.BOLD,
+    DataType.VBM_GM,
+    DataType.VBM_WM,
+    DataType.VBM_CSF,
+    DataType.FALFF,
+    DataType.GCOR,
+    DataType.LCOR,
+]
+
 
 @register_marker
 class MapsAggregation(BaseMarker):
@@ -27,23 +43,26 @@ class MapsAggregation(BaseMarker):
     maps : str
         The name of the map(s) to use.
         See :func:`.list_data` for options.
-    time_method : str, optional
-        The method to use to aggregate the time series over the time points,
-        after aggregation (only applicable to BOLD data). If None,
+    time_method : str or None, optional
+        The aggregation function to use for time series after applying
+        :term:`method` (only applicable to BOLD data). If None,
         it will not operate on the time dimension (default None).
-    time_method_params : dict, optional
+    time_method_params : dict or None, optional
         The parameters to pass to the time aggregation method (default None).
-    masks : str, dict or list of dict or str, optional
+    on : {``DataType.T1w``, ``DataType.T2w``, ``DataType.BOLD``, \
+         ``DataType.VBM_GM``, ``DataType.VBM_WM``, ``DataType.VBM_CSF``, \
+         ``DataType.FALFF``, ``DataType.GCOR``, ``DataType.LCOR``} or \
+         list of them or None, optional
+        The data type(s) to apply the marker on.
+        If None, will work on all available data.
+        Check :enum:`.DataType` for valid values (default None).
+    masks : str, dict, list of them or None, optional
         The specification of the masks to apply to regions before extracting
         signals. Check :ref:`Using Masks <using_masks>` for more details.
         If None, will not apply any mask (default None).
-    on : {"T1w", "T2w", "BOLD", "VBM_GM", "VBM_WM", "VBM_CSF", "fALFF", \
-        "GCOR", "LCOR"} or list of the options, optional
-        The data types to apply the marker to. If None, will work on all
-        available data (default None).
-    name : str, optional
-        The name of the marker. If None, will use the class name (default
-        None).
+    name : str or None, optional
+        The name of the marker.
+        If None, will use the class name (default None).
 
     Raises
     ------
@@ -56,64 +75,62 @@ class MapsAggregation(BaseMarker):
     _DEPENDENCIES: ClassVar[Dependencies] = {"nilearn", "numpy"}
 
     _MARKER_INOUT_MAPPINGS: ClassVar[MarkerInOutMappings] = {
-        "T1w": {
-            "aggregation": "vector",
+        DataType.T1w: {
+            "aggregation": StorageType.Vector,
         },
-        "T2w": {
-            "aggregation": "vector",
+        DataType.T2w: {
+            "aggregation": StorageType.Vector,
         },
-        "BOLD": {
-            "aggregation": "timeseries",
+        DataType.BOLD: {
+            "aggregation": StorageType.Timeseries,
         },
-        "VBM_GM": {
-            "aggregation": "vector",
+        DataType.VBM_GM: {
+            "aggregation": StorageType.Vector,
         },
-        "VBM_WM": {
-            "aggregation": "vector",
+        DataType.VBM_WM: {
+            "aggregation": StorageType.Vector,
         },
-        "VBM_CSF": {
-            "aggregation": "vector",
+        DataType.VBM_CSF: {
+            "aggregation": StorageType.Vector,
         },
-        "fALFF": {
-            "aggregation": "vector",
+        DataType.FALFF: {
+            "aggregation": StorageType.Vector,
         },
-        "GCOR": {
-            "aggregation": "vector",
+        DataType.GCOR: {
+            "aggregation": StorageType.Vector,
         },
-        "LCOR": {
-            "aggregation": "vector",
+        DataType.LCOR: {
+            "aggregation": StorageType.Vector,
         },
     }
 
-    def __init__(
-        self,
-        maps: str,
-        time_method: Optional[str] = None,
-        time_method_params: Optional[dict[str, Any]] = None,
-        masks: Union[str, dict, list[Union[dict, str]], None] = None,
-        on: Union[list[str], str, None] = None,
-        name: Optional[str] = None,
-    ) -> None:
-        self.maps = maps
-        self.masks = masks
-        super().__init__(on=on, name=name)
-
-        # Verify after super init so self._on is set
-        if "BOLD" not in self._on and time_method is not None:
+    maps: str
+    time_method: str | None = None
+    time_method_params: dict[str, Any] | None = None
+    masks: Annotated[
+        dict | str | list[dict | str] | None,
+        BeforeValidator(ensure_list_or_none),
+    ] = None
+    on: Annotated[
+        _on | list[_on] | None, BeforeValidator(ensure_list_or_none)
+    ] = None
+
+    def validate_marker_params(self) -> None:
+        """Run extra logical validation for marker."""
+        # self.on is set already
+        if "BOLD" not in self.on and self.time_method is not None:
             raise_error(
                 "`time_method` can only be used with BOLD data. "
                 "Please remove `time_method` parameter."
             )
-        if time_method is None and time_method_params is not None:
+        if self.time_method is None and self.time_method_params is not None:
             raise_error(
                 "`time_method_params` can only be used with `time_method`. "
                 "Please remove `time_method_params` parameter."
             )
-        self.time_method = time_method
-        self.time_method_params = time_method_params or {}
 
     def compute(
-        self, input: dict[str, Any], extra_input: Optional[dict] = None
+        self, input: dict[str, Any], extra_input: dict | None = None
     ) -> dict:
         """Compute.
 
@@ -169,15 +186,20 @@ class MapsAggregation(BaseMarker):
                 extra_input=extra_input,
             )
 
-        # Initialize masker
+        # Initialize masker; the maps (and mask) are already tailored to the
+        # input image, so no resampling is needed
         logger.debug("Masking")
         masker = NiftiMapsMasker(
             maps_img=maps_img,
             mask_img=mask_img,
-            target_affine=t_input_img.affine,
+            resampling_target=None,
+            standardize=None,
+            # Not used, and computing their data at fit time reads the data
+            reports=False,
         )
         # Mask the input data and extract data
-        data = masker.fit_transform(t_input_img)
+        # nilearn maskers return 1D arrays for 3D images, keep 2D
+        data = np.atleast_2d(masker.fit_transform(t_input_img))
 
         # Apply time dimension aggregation if required
         if self.time_method is not None:

junifer/markers/parcel_aggregation.py

@@ -4,22 +4,42 @@
 #          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
-from typing import Any, ClassVar, Optional, Union
+from typing import Annotated, Any, ClassVar, Literal
 
 import numpy as np
 from nilearn.image import math_img
 from nilearn.maskers import NiftiMasker
+from pydantic import BeforeValidator
 
 from ..api.decorators import register_marker
 from ..data import get_data
+from ..datagrabber import DataType
 from ..stats import get_aggfunc_by_name
+from ..storage import StorageType
 from ..typing import Dependencies, MarkerInOutMappings
-from ..utils import logger, raise_error, warn_with_log
-from .base import BaseMarker
+from ..utils import (
+    ensure_list,
+    ensure_list_or_none,
+    raise_error,
+    warn_with_log,
+)
+from .base import BaseMarker, logger
 
 
 __all__ = ["ParcelAggregation"]
 
+_on = Literal[
+    DataType.T1w,
+    DataType.T2w,
+    DataType.BOLD,
+    DataType.VBM_GM,
+    DataType.VBM_WM,
+    DataType.VBM_CSF,
+    DataType.FALFF,
+    DataType.GCOR,
+    DataType.LCOR,
+]
+
 
 @register_marker
 class ParcelAggregation(BaseMarker):
@@ -30,29 +50,33 @@ class ParcelAggregation(BaseMarker):
     parcellation : str or list of str
         The name(s) of the parcellation(s) to use.
         See :func:`.list_data` for options.
-    method : str
-        The method to perform aggregation using. Check valid options in
-        :func:`.get_aggfunc_by_name`.
-    method_params : dict, optional
-        Parameters to pass to the aggregation function. Check valid options in
-        :func:`.get_aggfunc_by_name`.
-    time_method : str, optional
-        The method to use to aggregate the time series over the time points,
-        after applying :term:`method` (only applicable to BOLD data). If None,
+    method : str, optional
+        The aggregation function to use.
+        See :func:`.get_aggfunc_by_name` for options
+        (default "mean").
+    method_params : dict or None, optional
+        The parameters to pass to the aggregation function.
+        See :func:`.get_aggfunc_by_name` for options (default None).
+    time_method : str or None, optional
+        The aggregation function to use for time series after applying
+        :term:`method` (only applicable to BOLD data). If None,
         it will not operate on the time dimension (default None).
-    time_method_params : dict, optional
-        The parameters to pass to the time aggregation method (default None).
-    masks : str, dict or list of dict or str, optional
+    time_method_params : dict or None, optional
+        The parameters to pass to the time aggregation function (default None).
+    on : {``DataType.T1w``, ``DataType.T2w``, ``DataType.BOLD``, \
+         ``DataType.VBM_GM``, ``DataType.VBM_WM``, ``DataType.VBM_CSF``, \
+         ``DataType.FALFF``, ``DataType.GCOR``, ``DataType.LCOR``} or \
+         list of them or None, optional
+        The data type(s) to apply the marker on.
+        If None, will work on all available data.
+        Check :enum:`.DataType` for valid values (default None).
+    masks : str, dict, list of them or None, optional
         The specification of the masks to apply to regions before extracting
         signals. Check :ref:`Using Masks <using_masks>` for more details.
         If None, will not apply any mask (default None).
-    on : {"T1w", "T2w", "BOLD", "VBM_GM", "VBM_WM", "VBM_CSF", "fALFF", \
-        "GCOR", "LCOR"} or list of the options, optional
-        The data types to apply the marker to. If None, will work on all
-        available data (default None).
-    name : str, optional
-        The name of the marker. If None, will use the class name (default
-        None).
+    name : str or None, optional
+        The name of the marker.
+        If None, will use the class name (default None).
 
     Raises
     ------
@@ -65,70 +89,64 @@ class ParcelAggregation(BaseMarker):
     _DEPENDENCIES: ClassVar[Dependencies] = {"nilearn", "numpy"}
 
     _MARKER_INOUT_MAPPINGS: ClassVar[MarkerInOutMappings] = {
-        "T1w": {
-            "aggregation": "vector",
+        DataType.T1w: {
+            "aggregation": StorageType.Vector,
         },
-        "T2w": {
-            "aggregation": "vector",
+        DataType.T2w: {
+            "aggregation": StorageType.Vector,
         },
-        "BOLD": {
-            "aggregation": "timeseries",
+        DataType.BOLD: {
+            "aggregation": StorageType.Timeseries,
         },
-        "VBM_GM": {
-            "aggregation": "vector",
+        DataType.VBM_GM: {
+            "aggregation": StorageType.Vector,
         },
-        "VBM_WM": {
-            "aggregation": "vector",
+        DataType.VBM_WM: {
+            "aggregation": StorageType.Vector,
         },
-        "VBM_CSF": {
-            "aggregation": "vector",
+        DataType.VBM_CSF: {
+            "aggregation": StorageType.Vector,
         },
-        "fALFF": {
-            "aggregation": "vector",
+        DataType.FALFF: {
+            "aggregation": StorageType.Vector,
         },
-        "GCOR": {
-            "aggregation": "vector",
+        DataType.GCOR: {
+            "aggregation": StorageType.Vector,
         },
-        "LCOR": {
-            "aggregation": "vector",
+        DataType.LCOR: {
+            "aggregation": StorageType.Vector,
         },
     }
 
-    def __init__(
-        self,
-        parcellation: Union[str, list[str]],
-        method: str,
-        method_params: Optional[dict[str, Any]] = None,
-        time_method: Optional[str] = None,
-        time_method_params: Optional[dict[str, Any]] = None,
-        masks: Union[str, dict, list[Union[dict, str]], None] = None,
-        on: Union[list[str], str, None] = None,
-        name: Optional[str] = None,
-    ) -> None:
-        if not isinstance(parcellation, list):
-            parcellation = [parcellation]
-        self.parcellation = parcellation
-        self.method = method
-        self.method_params = method_params or {}
-        self.masks = masks
-        super().__init__(on=on, name=name)
-
-        # Verify after super init so self._on is set
-        if "BOLD" not in self._on and time_method is not None:
+    parcellation: Annotated[str | list[str], BeforeValidator(ensure_list)]
+    method: str = "mean"
+    method_params: dict[str, Any] | None = None
+    time_method: str | None = None
+    time_method_params: dict[str, Any] | None = None
+    masks: Annotated[
+        dict | str | list[dict | str] | None,
+        BeforeValidator(ensure_list_or_none),
+    ] = None
+    on: Annotated[
+        _on | list[_on] | None, BeforeValidator(ensure_list_or_none)
+    ] = None
+
+    def validate_marker_params(self) -> None:
+        """Run extra logical validation for marker."""
+        # self.on is set already
+        if "BOLD" not in self.on and self.time_method is not None:
             raise_error(
                 "`time_method` can only be used with BOLD data. "
                 "Please remove `time_method` parameter."
             )
-        if time_method is None and time_method_params is not None:
+        if self.time_method is None and self.time_method_params is not None:
             raise_error(
                 "`time_method_params` can only be used with `time_method`. "
                 "Please remove `time_method_params` parameter."
             )
-        self.time_method = time_method
-        self.time_method_params = time_method_params or {}
 
     def compute(
-        self, input: dict[str, Any], extra_input: Optional[dict] = None
+        self, input: dict[str, Any], extra_input: dict | None = None
     ) -> dict:
         """Compute.
 
@@ -198,13 +216,16 @@ class ParcelAggregation(BaseMarker):
                 mask=mask_img,
             )
 
-        # Initialize masker
+        # Initialize masker; the parcellation (and mask) are already
+        # tailored to the input image, so no target affine is needed (it
+        # would make nilearn crop and copy the input image)
         logger.debug("Masking")
-        masker = NiftiMasker(
-            parcellation_bin, target_affine=t_input_img.affine
-        )
+        # No reports, as they are not used and computing their data at fit
+        # time reads the data
+        masker = NiftiMasker(parcellation_bin, standardize=None, reports=False)
         # Mask the input data and the parcellation
-        data = masker.fit_transform(t_input_img)
+        # nilearn maskers return 1D arrays for 3D images, keep 2D
+        data = np.atleast_2d(masker.fit_transform(t_input_img))
         parcellation_values = np.squeeze(
             masker.transform(parcellation_img)
         ).astype(int)

junifer/markers/reho/__init__.pyi

@@ -1,5 +1,11 @@
-__all__ = ["ReHoMaps", "ReHoParcels", "ReHoSpheres"]
+__all__ = [
+    "ReHoImpl",
+    "ReHoMaps",
+    "ReHoParcels",
+    "ReHoSpheres",
+]
 
+from .reho_base import ReHoImpl
 from .reho_maps import ReHoMaps
 from .reho_parcels import ReHoParcels
 from .reho_spheres import ReHoSpheres

junifer/markers/reho/_afni_reho.py

@@ -3,20 +3,21 @@
 # Authors: Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
+import atexit
 from functools import lru_cache
 from pathlib import Path
 from typing import (
     TYPE_CHECKING,
     ClassVar,
-    Optional,
 )
 
 import nibabel as nib
 
-from ...pipeline import WorkDirManager
+from ...pipeline import ExtDep, WorkDirManager
 from ...typing import ExternalDependencies
-from ...utils import logger, run_ext_cmd
+from ...utils import run_ext_cmd
 from ...utils.singleton import Singleton
+from ..base import logger
 
 
 if TYPE_CHECKING:
@@ -36,13 +37,15 @@ class AFNIReHo(metaclass=Singleton):
 
     _EXT_DEPENDENCIES: ClassVar[ExternalDependencies] = [
         {
-            "name": "afni",
+            "name": ExtDep.AFNI,
             "commands": ["3dReHo", "3dAFNItoNIFTI"],
         },
     ]
 
-    def __del__(self) -> None:  # pragma: no cover
-        """Terminate the class."""
+    def __init__(self) -> None:
+        atexit.register(self._del)
+
+    def _del(self) -> None:
         # Clear the computation cache
         logger.debug("Clearing cache for ReHo computation via AFNI")
         self.compute.cache_clear()
@@ -52,14 +55,15 @@ class AFNIReHo(metaclass=Singleton):
         self,
         input_path: Path,
         nneigh: int = 27,
-        neigh_rad: Optional[float] = None,
-        neigh_x: Optional[float] = None,
-        neigh_y: Optional[float] = None,
-        neigh_z: Optional[float] = None,
-        box_rad: Optional[int] = None,
-        box_x: Optional[int] = None,
-        box_y: Optional[int] = None,
-        box_z: Optional[int] = None,
+        mask_path: Path | None = None,
+        neigh_rad: float | None = None,
+        neigh_x: float | None = None,
+        neigh_y: float | None = None,
+        neigh_z: float | None = None,
+        box_rad: int | None = None,
+        box_x: int | None = None,
+        box_y: int | None = None,
+        box_z: int | None = None,
     ) -> tuple["Nifti1Image", Path]:
         """Compute ReHo map.
 
@@ -75,6 +79,9 @@ class AFNIReHo(metaclass=Singleton):
             * 27 : for face-, edge-, and node-wise neighbors
 
             (default 27).
+        mask_path : pathlib.Path or None, optional
+            Path to the mask to restrict the computation to, passed to
+            ``3dReHo`` as ``-mask``. If None, no mask is used (default None).
         neigh_rad : positive float, optional
             The radius of a desired neighbourhood (default None).
         neigh_x : positive float, optional
@@ -140,6 +147,8 @@ class AFNIReHo(metaclass=Singleton):
             f"-prefix {reho_out_path_prefix.resolve()}",
             f"-inset {input_path.resolve()}",
         ]
+        if mask_path is not None:
+            reho_cmd.append(f"-mask {mask_path.resolve()}")
         # Check ellipsoidal / cuboidal volume arguments
         if neigh_rad:
             reho_cmd.append(f"-neigh_RAD {neigh_rad}")