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

junifer/markers/brainprint.py

@@ -8,23 +8,24 @@ from pathlib import Path
 from typing import (
     Any,
     ClassVar,
-    Optional,
-    Union,
 )
 
 import numpy as np
 import numpy.typing as npt
+from pydantic import PositiveInt
 
 from ..api.decorators import register_marker
+from ..datagrabber import DataType
 from ..external.BrainPrint.brainprint.brainprint import (
     compute_asymmetry,
     compute_brainprint,
 )
 from ..external.BrainPrint.brainprint.surfaces import surf_to_vtk
-from ..pipeline import WorkDirManager
+from ..pipeline import ExtDep, WorkDirManager
+from ..storage import StorageType
 from ..typing import Dependencies, ExternalDependencies, MarkerInOutMappings
-from ..utils import logger, run_ext_cmd
-from .base import BaseMarker
+from ..utils import run_ext_cmd
+from .base import BaseMarker, logger
 
 
 __all__ = ["BrainPrint"]
@@ -60,15 +61,15 @@ class BrainPrint(BaseMarker):
         execution speed. Requires the ``scikit-sparse`` library. If it cannot
         be found, an error will be thrown. If False, will use slower LU
         decomposition (default False).
-    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).
 
     """
 
     _EXT_DEPENDENCIES: ClassVar[ExternalDependencies] = [
         {
-            "name": "freesurfer",
+            "name": ExtDep.FreeSurfer,
             "commands": [
                 "mri_binarize",
                 "mri_pretess",
@@ -81,35 +82,25 @@ class BrainPrint(BaseMarker):
     _DEPENDENCIES: ClassVar[Dependencies] = {"lapy", "numpy"}
 
     _MARKER_INOUT_MAPPINGS: ClassVar[MarkerInOutMappings] = {
-        "FreeSurfer": {
-            "eigenvalues": "scalar_table",
-            "areas": "vector",
-            "volumes": "vector",
-            "distances": "vector",
+        DataType.FreeSurfer: {
+            "eigenvalues": StorageType.ScalarTable,
+            "areas": StorageType.Vector,
+            "volumes": StorageType.Vector,
+            "distances": StorageType.Vector,
         }
     }
 
-    def __init__(
-        self,
-        num: int = 50,
-        skip_cortex=False,
-        keep_eigenvectors: bool = False,
-        norm: str = "none",
-        reweight: bool = False,
-        asymmetry: bool = False,
-        asymmetry_distance: str = "euc",
-        use_cholmod: bool = False,
-        name: Optional[str] = None,
-    ) -> None:
-        self.num = num
-        self.skip_cortex = skip_cortex
-        self.keep_eigenvectors = keep_eigenvectors
-        self.norm = norm
-        self.reweight = reweight
-        self.asymmetry = asymmetry
-        self.asymmetry_distance = asymmetry_distance
-        self.use_cholmod = use_cholmod
-        super().__init__(name=name, on="FreeSurfer")
+    num: PositiveInt = 50
+    skip_cortex: bool = False
+    keep_eigenvectors: bool = False
+    norm: str = "none"
+    reweight: bool = False
+    asymmetry: bool = False
+    asymmetry_distance: str = "euc"
+    use_cholmod: bool = False
+
+    _tempdir = Path()
+    _element_tempdir = Path()
 
     def _create_aseg_surface(
         self,
@@ -307,7 +298,7 @@ class BrainPrint(BaseMarker):
 
     def _fix_nan(
         self,
-        input_data: list[Union[float, str, npt.ArrayLike]],
+        input_data: list[float | str | npt.ArrayLike],
     ) -> np.ndarray:  # pragma: no cover
         """Convert BrainPrint output with string NaN to ``numpy.nan``.
 
@@ -329,7 +320,7 @@ class BrainPrint(BaseMarker):
     def compute(
         self,
         input: dict[str, Any],
-        extra_input: Optional[dict] = None,
+        extra_input: dict | None = None,
     ) -> dict:  # pragma: no cover
         """Compute.
 
@@ -353,7 +344,7 @@ class BrainPrint(BaseMarker):
                 - ``col_names`` : surface labels as list of str
                 - ``row_names`` : eigenvalue count labels as list of str
                 - ``row_header_col_name`` : "eigenvalue"
-                                ()
+
             * ``areas`` : dictionary with the following keys:
 
                 - ``data`` : areas as ``np.ndarray``
@@ -364,7 +355,7 @@ class BrainPrint(BaseMarker):
                 - ``data`` : volumes as ``np.ndarray``
                 - ``col_names`` : surface labels as list of str
 
-            * ``distances`` : dictionary with the following keys
+            * ``distances`` : dictionary with the following keys \
                               if ``asymmetry = True``:
 
                 - ``data`` : distances as ``np.ndarray``

junifer/markers/complexity/__init__.py

@@ -15,7 +15,24 @@ if find_spec("neurokit2") is None:
         msg="Could not find `neurokit2`, make sure the package is installed.",
         klass=ImportError,
     )
-else:
-    import lazy_loader as lazy
 
-    __getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__)
+# Not lazy: importing the sub-package (e.g., with ``with:`` in the YAML)
+# registers the markers, as they are not built-in components of the registry
+from .hurst_exponent import HurstExponent  # noqa: E402
+from .range_entropy import RangeEntropy  # noqa: E402
+from .range_entropy_auc import RangeEntropyAUC  # noqa: E402
+from .perm_entropy import PermEntropy  # noqa: E402
+from .weighted_perm_entropy import WeightedPermEntropy  # noqa: E402
+from .sample_entropy import SampleEntropy  # noqa: E402
+from .multiscale_entropy_auc import MultiscaleEntropyAUC  # noqa: E402
+
+
+__all__ = [
+    "HurstExponent",
+    "RangeEntropy",
+    "RangeEntropyAUC",
+    "PermEntropy",
+    "WeightedPermEntropy",
+    "SampleEntropy",
+    "MultiscaleEntropyAUC",
+]

junifer/markers/complexity/complexity_base.py

@@ -1,75 +1,71 @@
 """Provide base class for complexity."""
 
 # Authors: Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
 from abc import abstractmethod
 from typing import (
-    TYPE_CHECKING,
+    Annotated,
     Any,
     ClassVar,
-    Optional,
-    Union,
 )
 
+import numpy as np
+from pydantic import BeforeValidator
+
+from ...datagrabber import DataType
+from ...storage import StorageType
 from ...typing import Dependencies, MarkerInOutMappings
-from ...utils import raise_error
+from ...utils import ensure_list, ensure_list_or_none, raise_error
 from ..base import BaseMarker
 from ..parcel_aggregation import ParcelAggregation
-
-
-if TYPE_CHECKING:
-    import numpy as np
+from ..utils import _has_data
 
 
 __all__ = ["ComplexityBase"]
 
 
 class ComplexityBase(BaseMarker):
-    """Base class for complexity computation.
+    """Abstract base class for complexity computation.
 
     Parameters
     ----------
     parcellation : str or list of str
-        The name(s) of the parcellation(s). Check valid options by calling
-        :func:`junifer.data.parcellations.list_parcellations`.
+        The name(s) of the parcellation(s) to use.
+        See :func:`.list_data` for options.
     agg_method : str, optional
-        The method to perform aggregation using. Check valid options in
-        :func:`junifer.stats.get_aggfunc_by_name` (default "mean").
-    agg_method_params : dict, optional
-        Parameters to pass to the aggregation function. Check valid options in
-        :func:`junifer.stats.get_aggfunc_by_name` (default None).
-    masks : str, dict or list of dict or str, optional
+        The aggregation function to use.
+        See :func:`.get_aggfunc_by_name` for options
+        (default "mean").
+    agg_method_params : dict or None, optional
+        The parameters to pass to the aggregation function.
+        See :func:`.get_aggfunc_by_name` for options (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).
-    name : str, optional
-        The name of the marker. If None, it 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).
 
     """
 
     _DEPENDENCIES: ClassVar[Dependencies] = {"nilearn", "neurokit2"}
 
     _MARKER_INOUT_MAPPINGS: ClassVar[MarkerInOutMappings] = {
-        "BOLD": {
-            "complexity": "vector",
+        DataType.BOLD: {
+            "complexity": StorageType.Vector,
         },
     }
 
-    def __init__(
-        self,
-        parcellation: Union[str, list[str]],
-        agg_method: str = "mean",
-        agg_method_params: Optional[dict] = None,
-        masks: Union[str, dict, list[Union[dict, str]], None] = None,
-        name: Optional[str] = None,
-    ) -> None:
-        self.parcellation = parcellation
-        self.agg_method = agg_method
-        self.agg_method_params = agg_method_params
-        self.masks = masks
-        super().__init__(on="BOLD", name=name)
+    parcellation: Annotated[str | list[str], BeforeValidator(ensure_list)]
+    agg_method: str = "mean"
+    agg_method_params: dict | None = None
+    masks: Annotated[
+        dict | str | list[dict | str] | None,
+        BeforeValidator(ensure_list_or_none),
+    ] = None
 
     @abstractmethod
     def compute_complexity(
@@ -85,7 +81,7 @@ class ComplexityBase(BaseMarker):
     def compute(
         self,
         input: dict[str, Any],
-        extra_input: Optional[dict[str, Any]] = None,
+        extra_input: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         """Compute.
 
@@ -117,14 +113,17 @@ class ComplexityBase(BaseMarker):
             method=self.agg_method,
             method_params=self.agg_method_params,
             masks=self.masks,
-            on="BOLD",
+            on=DataType.BOLD,
         ).compute(input=input, extra_input=extra_input)
-        # Compute complexity measure
+        # Compute complexity measure on the regions with data (e.g. regions
+        # lost in resampling have none) and set the others to NaN
+        data = parcel_aggregation["aggregation"]["data"]
+        has_data = _has_data(data)
+        complexity = np.full((1, data.shape[1]), np.nan)
+        complexity[:, has_data] = self.compute_complexity(data[:, has_data])
         return {
             "complexity": {
-                "data": self.compute_complexity(
-                    parcel_aggregation["aggregation"]["data"]
-                ),
+                "data": complexity,
                 "col_names": parcel_aggregation["aggregation"]["col_names"],
             }
         }

junifer/markers/complexity/hurst_exponent.py

@@ -2,15 +2,15 @@
 
 # Authors: Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
 #          Leonard Sasse <l.sasse@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
-from typing import Optional, Union
-
 import neurokit2 as nk
 import numpy as np
 
 from ...api.decorators import register_marker
-from ...utils import logger, warn_with_log
+from ...utils import warn_with_log
+from ..base import logger
 from .complexity_base import ComplexityBase
 
 
@@ -27,22 +27,23 @@ class HurstExponent(ComplexityBase):
         The name(s) of the parcellation(s) to use.
         See :func:`.list_data` for options.
     agg_method : str, optional
-        The method to perform aggregation using. Check valid options in
-        :func:`junifer.stats.get_aggfunc_by_name` (default "mean").
-    agg_method_params : dict, optional
-        Parameters to pass to the aggregation function. Check valid options in
-        :func:`junifer.stats.get_aggfunc_by_name` (default None).
-    masks : str, dict or list of dict or str, optional
+        The aggregation function to use.
+        See :func:`.get_aggfunc_by_name` for options
+        (default "mean").
+    agg_method_params : dict or None, optional
+        The parameters to pass to the aggregation function.
+        See :func:`.get_aggfunc_by_name` for options (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).
-    params : dict, optional
-        Parameters to pass to the Hurst exponent calculation function. For more
-        information, check out ``junifer.markers.utils._hurst_exponent``.
-        If None, value is set to {"method": "dfa"} (default None).
-    name : str, optional
-        The name of the marker. If None, it will use the class name
-        (default None).
+    params : dict or None, optional
+        The parameters to pass to the Hurst exponent calculation function.
+        See ``junifer.markers.utils._hurst_exponent`` for more information.
+        If None, value is set to ``{"method": "dfa"}`` (default None).
+    name : str or None, optional
+        The name of the marker.
+        If None, will use the class name (default None).
 
     Warnings
     --------
@@ -53,26 +54,12 @@ class HurstExponent(ComplexityBase):
 
     """
 
-    def __init__(
-        self,
-        parcellation: Union[str, list[str]],
-        agg_method: str = "mean",
-        agg_method_params: Optional[dict] = None,
-        masks: Union[str, dict, list[Union[dict, str]], None] = None,
-        params: Optional[dict] = None,
-        name: Optional[str] = None,
-    ) -> None:
-        super().__init__(
-            parcellation=parcellation,
-            agg_method=agg_method,
-            agg_method_params=agg_method_params,
-            masks=masks,
-            name=name,
-        )
-        if params is None:
+    params: dict | None = None
+
+    def validate_marker_params(self) -> None:
+        """Run extra logical validation for marker."""
+        if self.params is None:
             self.params = {"method": "dfa"}
-        else:
-            self.params = params
 
     def compute_complexity(
         self,

junifer/markers/complexity/multiscale_entropy_auc.py

@@ -2,21 +2,44 @@
 
 # Authors: Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
 #          Leonard Sasse <l.sasse@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
-from typing import Optional, Union
+from collections.abc import Generator
+from contextlib import contextmanager
 
 import neurokit2 as nk
 import numpy as np
 
 from ...api.decorators import register_marker
-from ...utils import logger, warn_with_log
+from ...utils import warn_with_log
+from ..base import logger
 from .complexity_base import ComplexityBase
 
 
 __all__ = ["MultiscaleEntropyAUC"]
 
 
+# TODO: remove once the neurokit2 pin (0.2.12) can be raised (0.2.13
+# requires pandas < 3 and setuptools < 82)
+@contextmanager
+def _numpy_trapz() -> Generator[None, None, None]:
+    """Provide ``numpy.trapz`` for ``neurokit2.entropy_multiscale``.
+
+    ``numpy.trapz`` was removed in numpy 2.4 in favour of
+    ``numpy.trapezoid``, but neurokit2 <= 0.2.12 still uses it.
+
+    """
+    if hasattr(np, "trapz"):
+        yield
+        return
+    np.trapz = np.trapezoid
+    try:
+        yield
+    finally:
+        del np.trapz
+
+
 @register_marker
 class MultiscaleEntropyAUC(ComplexityBase):
     """Class for AUC of multiscale entropy of a time series.
@@ -27,23 +50,25 @@ class MultiscaleEntropyAUC(ComplexityBase):
         The name(s) of the parcellation(s) to use.
         See :func:`.list_data` for options.
     agg_method : str, optional
-        The method to perform aggregation using. Check valid options in
-        :func:`junifer.stats.get_aggfunc_by_name` (default "mean").
-    agg_method_params : dict, optional
-        Parameters to pass to the aggregation function. Check valid options in
-        :func:`junifer.stats.get_aggfunc_by_name` (default None).
-    masks : str, dict or list of dict or str, optional
+        The aggregation function to use.
+        See :func:`.get_aggfunc_by_name` for options
+        (default "mean").
+    agg_method_params : dict or None, optional
+        The parameters to pass to the aggregation function.
+        See :func:`.get_aggfunc_by_name` for options (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).
-    params : dict, optional
-        Parameters to pass to the AUC of multiscale entropy calculation
-        function. For more information, check out
-        ``junifer.markers.utils._multiscale_entropy_auc``. If None, value
-        is set to {"m": 2, "tol": 0.5, "scale": 10} (default None).
-    name : str, optional
-        The name of the marker. If None, it will use the class name
+    params : dict or None, optional
+        The parameters to pass to the AUC of multiscale entropy calculation
+        function. See
+        ``junifer.markers.utils._multiscale_entropy_auc`` for more information.
+        If None, value is set to ``{"m": 2, "tol": 0.5, "scale": 10}``
         (default None).
+    name : str or None, optional
+        The name of the marker.
+        If None, will use the class name (default None).
 
     Warnings
     --------
@@ -54,26 +79,12 @@ class MultiscaleEntropyAUC(ComplexityBase):
 
     """
 
-    def __init__(
-        self,
-        parcellation: Union[str, list[str]],
-        agg_method: str = "mean",
-        agg_method_params: Optional[dict] = None,
-        masks: Union[str, dict, list[Union[dict, str]], None] = None,
-        params: Optional[dict] = None,
-        name: Optional[str] = None,
-    ) -> None:
-        super().__init__(
-            parcellation=parcellation,
-            agg_method=agg_method,
-            agg_method_params=agg_method_params,
-            masks=masks,
-            name=name,
-        )
-        if params is None:
+    params: dict | None = None
+
+    def validate_marker_params(self) -> None:
+        """Run extra logical validation for marker."""
+        if self.params is None:
             self.params = {"m": 2, "tol": 0.5, "scale": 10}
-        else:
-            self.params = params
 
     def compute_complexity(
         self,
@@ -123,13 +134,14 @@ class MultiscaleEntropyAUC(ComplexityBase):
         for idx_roi in range(n_roi):
             sig = extracted_bold_values[:, idx_roi]
             tol_corrected = tol * np.std(sig)
-            tmp = nk.entropy_multiscale(
-                sig,
-                scale=scale,
-                dimension=emb_dim,
-                tolerance=tol_corrected,
-                method="MSEn",
-            )
+            with _numpy_trapz():
+                tmp = nk.entropy_multiscale(
+                    sig,
+                    scale=scale,
+                    dimension=emb_dim,
+                    tolerance=tol_corrected,
+                    method="MSEn",
+                )
 
             MSEn_auc_roi[idx_roi] = tmp[0]
 

junifer/markers/complexity/perm_entropy.py

@@ -2,15 +2,15 @@
 
 # Authors: Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
 #          Leonard Sasse <l.sasse@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
-from typing import Optional, Union
-
 import neurokit2 as nk
 import numpy as np
 
 from ...api.decorators import register_marker
-from ...utils import logger, warn_with_log
+from ...utils import warn_with_log
+from ..base import logger
 from .complexity_base import ComplexityBase
 
 
@@ -27,23 +27,23 @@ class PermEntropy(ComplexityBase):
         The name(s) of the parcellation(s) to use.
         See :func:`.list_data` for options.
     agg_method : str, optional
-        The method to perform aggregation using. Check valid options in
-        :func:`junifer.stats.get_aggfunc_by_name` (default "mean").
-    agg_method_params : dict, optional
-        Parameters to pass to the aggregation function. Check valid options in
-        :func:`junifer.stats.get_aggfunc_by_name` (default None).
-    masks : str, dict or list of dict or str, optional
+        The aggregation function to use.
+        See :func:`.get_aggfunc_by_name` for options
+        (default "mean").
+    agg_method_params : dict or None, optional
+        The parameters to pass to the aggregation function.
+        See :func:`.get_aggfunc_by_name` for options (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).
-    params : dict, optional
-        Parameters to pass to the permutation entropy calculation function.
-        For more information, check out
-        ``junifer.markers.utils._perm_entropy``. If None, value is set to
-        {"m": 2, "delay": 1} (default None).
-    name : str, optional
-        The name of the marker. If None, it will use the class name
-        (default None).
+    params : dict or None, optional
+        The parameters to pass to the permutation entropy calculation function.
+        See ``junifer.markers.utils._perm_entropy`` for more information.
+        If None, value is set to ``{"m": 2, "delay": 1}`` (default None).
+    name : str or None, optional
+        The name of the marker.
+        If None, will use the class name (default None).
 
     Warnings
     --------
@@ -54,26 +54,12 @@ class PermEntropy(ComplexityBase):
 
     """
 
-    def __init__(
-        self,
-        parcellation: Union[str, list[str]],
-        agg_method: str = "mean",
-        agg_method_params: Optional[dict] = None,
-        masks: Union[str, dict, list[Union[dict, str]], None] = None,
-        params: Optional[dict] = None,
-        name: Optional[str] = None,
-    ) -> None:
-        super().__init__(
-            parcellation=parcellation,
-            agg_method=agg_method,
-            agg_method_params=agg_method_params,
-            masks=masks,
-            name=name,
-        )
-        if params is None:
+    params: dict | None = None
+
+    def validate_marker_params(self) -> None:
+        """Run extra logical validation for marker."""
+        if self.params is None:
             self.params = {"m": 4, "delay": 1}
-        else:
-            self.params = params
 
     def compute_complexity(
         self,