junifer 0.0.3.dev188__py3-none-any.whl → 0.0.4__py3-none-any.whl

junifer/markers/complexity/complexity_base.py

@@ -0,0 +1,149 @@
+"""Provide base class for complexity."""
+
+# Authors: Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
+# License: AGPL
+
+from abc import abstractmethod
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Set,
+    Union,
+)
+
+from ...utils import raise_error
+from ..base import BaseMarker
+from ..parcel_aggregation import ParcelAggregation
+
+
+if TYPE_CHECKING:
+    import numpy as np
+
+
+class ComplexityBase(BaseMarker):
+    """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`.
+    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 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).
+
+    """
+
+    _DEPENDENCIES: ClassVar[Set[str]] = {"nilearn", "neurokit2"}
+
+    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)
+
+    @abstractmethod
+    def compute_complexity(
+        self,
+        extracted_bold_values: "np.ndarray",
+    ) -> "np.ndarray":
+        """Compute complexity measure."""
+        raise_error(
+            msg="Concrete classes need to implement compute_complexity().",
+            klass=NotImplementedError,
+        )
+
+    def get_valid_inputs(self) -> List[str]:
+        """Get valid data types for input.
+
+        Returns
+        -------
+        list of str
+            The list of data types that can be used as input for this marker.
+
+        """
+        return ["BOLD"]
+
+    def get_output_type(self, input_type: str) -> str:
+        """Get output type.
+
+        Parameters
+        ----------
+        input_type : str
+            The data type input to the marker.
+
+        Returns
+        -------
+        str
+            The storage type output by the marker.
+
+        """
+        return "vector"
+
+    def compute(
+        self,
+        input: Dict[str, Any],
+        extra_input: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Compute.
+
+        Parameters
+        ----------
+        input : dict
+            A single input from the pipeline data object in which to compute
+            the marker.
+        extra_input : dict, optional
+            The other fields in the pipeline data object. Useful for accessing
+            other data kind that needs to be used in the computation.
+
+        Returns
+        -------
+        dict
+            The computed result as dictionary. The following keys will be
+            included in the dictionary:
+
+           * ``data`` : ROI-wise complexity measures as ``numpy.ndarray``
+           * ``col_names`` : ROI labels for the complexity measures as list
+
+        """
+        # Initialize a ParcelAggregation
+        parcel_aggregation = ParcelAggregation(
+            parcellation=self.parcellation,
+            method=self.agg_method,
+            method_params=self.agg_method_params,
+            masks=self.masks,
+            on="BOLD",
+        )
+        # Extract the 2D time series using parcel aggregation
+        parcel_aggregation_map = parcel_aggregation.compute(
+            input=input, extra_input=extra_input
+        )
+
+        # Compute complexity measure
+        parcel_aggregation_map["data"] = self.compute_complexity(
+            parcel_aggregation_map["data"]
+        )
+
+        return parcel_aggregation_map

junifer/markers/complexity/hurst_exponent.py

@@ -0,0 +1,136 @@
+"""Provide class for Hurst exponent of a time series."""
+
+# Authors: Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
+#          Leonard Sasse <l.sasse@fz-juelich.de>
+# License: AGPL
+
+from typing import Dict, List, Optional, Union
+
+import neurokit2 as nk
+import numpy as np
+
+from ...api.decorators import register_marker
+from ...utils import logger, warn_with_log
+from .complexity_base import ComplexityBase
+
+
+@register_marker
+class HurstExponent(ComplexityBase):
+    """Class for Hurst exponent of a time series.
+
+    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`.
+    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 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).
+
+    Warnings
+    --------
+    This class is not automatically imported by junifer and requires you to
+    import it explicitly. You can do it programmatically by
+    ``from junifer.markers.complexity import HurstExponent`` or in the YAML by
+    ``with: junifer.markers.complexity``.
+
+    """
+
+    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:
+            self.params = {"method": "dfa"}
+        else:
+            self.params = params
+
+    def compute_complexity(
+        self,
+        extracted_bold_values: np.ndarray,
+    ) -> np.ndarray:
+        """Compute complexity measure.
+
+        Take a timeseries of brain areas, and calculate Hurst exponent using
+        the detrended fluctuation analysis method assuming the data is
+        monofractal [1].
+
+        Parameters
+        ----------
+        extracted_bold_values : numpy.ndarray
+            The BOLD values extracted via parcel aggregation.
+
+        Returns
+        -------
+        numpy.ndarray
+            The values after computing complexity measure.
+
+        References
+        ----------
+        .. [1] Peng, C.; Havlin, S.; Stanley, H.E.; Goldberger, A.L.
+               Quantification of scaling exponents and crossover phenomena in
+               nonstationary heartbeat time series.
+               Chaos Interdiscip. J. Nonlinear Sci., 5, 82-87, 1995.
+
+        See Also
+        --------
+        neurokit2.fractal_dfa
+
+        """
+        logger.info(f"Calculating Hurst exponent ({self.params['method']}).")
+
+        _, n_roi = extracted_bold_values.shape
+        hurst_roi = np.zeros((n_roi, 1))
+
+        if self.params["method"] == "dfa":
+            for idx_roi in range(n_roi):
+                sig = extracted_bold_values[:, idx_roi]
+                tmp = nk.fractal_dfa(
+                    sig,
+                    scale="default",
+                    overlap=True,
+                    integrate=True,
+                    order=1,
+                    multifractal=False,
+                    q="default",  # q = 2 for monofractal Hurst exponent
+                    maxdfa=False,
+                    show=False,
+                )
+
+                hurst_roi[idx_roi] = tmp[0]
+
+        else:
+            hurst_roi = np.empty((n_roi, 1))
+            hurst_roi[:] = np.nan
+            warn_with_log("The DFA method is available only!")
+
+        if np.isnan(np.sum(hurst_roi)):
+            warn_with_log("There is NaN in the Hurst exponent values!")
+
+        return hurst_roi.T  # 1 X n_roi

junifer/markers/complexity/multiscale_entropy_auc.py

@@ -0,0 +1,140 @@
+"""Provide class for the AUC of multiscale entropy of a time series."""
+
+# Authors: Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
+#          Leonard Sasse <l.sasse@fz-juelich.de>
+# License: AGPL
+
+from typing import Dict, List, Optional, Union
+
+import neurokit2 as nk
+import numpy as np
+
+from ...api.decorators import register_marker
+from ...utils import logger, warn_with_log
+from .complexity_base import ComplexityBase
+
+
+@register_marker
+class MultiscaleEntropyAUC(ComplexityBase):
+    """Class for AUC of multiscale entropy of a time series.
+
+    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`.
+    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 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
+        (default None).
+
+    Warnings
+    --------
+    This class is not automatically imported by junifer and requires you to
+    import it explicitly. You can do it programmatically by
+    ``from junifer.markers.complexity import MultiscaleEntropyAUC`` or in the
+    YAML by ``with: junifer.markers.complexity``.
+
+    """
+
+    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:
+            self.params = {"m": 2, "tol": 0.5, "scale": 10}
+        else:
+            self.params = params
+
+    def compute_complexity(
+        self,
+        extracted_bold_values: np.ndarray,
+    ) -> np.ndarray:
+        """Compute complexity measure.
+
+        Take a timeseries of brain areas, calculate multiscale entropy for each
+        region and calculate the AUC of the entropy curves leading to a
+        region-wise map of the brain [1].
+
+        Parameters
+        ----------
+        extracted_bold_values : numpy.ndarray
+            The BOLD values extracted via parcel aggregation.
+
+        Returns
+        -------
+        numpy.ndarray
+            The values after computing complexity measure.
+
+        References
+        ----------
+        .. [1] Costa, M., Goldberger, A. L., & Peng, C. K.
+               Multiscale entropy analysis of complex physiologic time series.
+               Physical review letters, 89(6), 068102, 2002.
+
+        See Also
+        --------
+        neurokit2.entropy_multiscale
+
+        """
+        logger.info("Calculating AUC of multiscale entropy.")
+
+        emb_dim = self.params["m"]
+        tol = self.params["tol"]
+        scale = self.params["scale"]
+
+        assert isinstance(emb_dim, int), "Embedding dimension must be integer."
+        assert isinstance(scale, int), "Scale must be integer."
+        assert isinstance(
+            tol, float
+        ), "Tolerance must be a positive float number."
+
+        _, n_roi = extracted_bold_values.shape
+        MSEn_auc_roi = np.zeros((n_roi, 1))
+        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",
+            )
+
+            MSEn_auc_roi[idx_roi] = tmp[0]
+
+        if np.isnan(np.sum(MSEn_auc_roi)):
+            warn_with_log(
+                "There is NaN in the entropy values, likely due "
+                "to too short data length. A possible solution "
+                "may be to choose a smaller value for 'scale'."
+            )
+
+        return MSEn_auc_roi.T  # 1 X n_roi

junifer/markers/complexity/perm_entropy.py

@@ -0,0 +1,132 @@
+"""Provide class for permutation entropy of a time series."""
+
+# Authors: Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
+#          Leonard Sasse <l.sasse@fz-juelich.de>
+# License: AGPL
+
+from typing import Dict, List, Optional, Union
+
+import neurokit2 as nk
+import numpy as np
+
+from ...api.decorators import register_marker
+from ...utils import logger, warn_with_log
+from .complexity_base import ComplexityBase
+
+
+@register_marker
+class PermEntropy(ComplexityBase):
+    """Class for permutation entropy of a time series.
+
+    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`.
+    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 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).
+
+    Warnings
+    --------
+    This class is not automatically imported by junifer and requires you to
+    import it explicitly. You can do it programmatically by
+    ``from junifer.markers.complexity import PermEntropy`` or in the YAML by
+    ``with: junifer.markers.complexity``.
+
+    """
+
+    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:
+            self.params = {"m": 4, "delay": 1}
+        else:
+            self.params = params
+
+    def compute_complexity(
+        self,
+        extracted_bold_values: np.ndarray,
+    ) -> np.ndarray:
+        """Compute complexity measure.
+
+        Take a timeseries of brain areas, and calculate permutation entropy
+        according to the method outlined in [1].
+
+        Parameters
+        ----------
+        extracted_bold_values : numpy.ndarray
+            The BOLD values extracted via parcel aggregation.
+
+        Returns
+        -------
+        numpy.ndarray
+            The values after computing complexity measure.
+
+        References
+        ----------
+        .. [1] Bandt, C., & Pompe, B. (2002)
+               Permutation entropy: a natural complexity measure for time
+               series.
+               Physical review letters, 88(17), 174102.
+
+        See Also
+        --------
+        neurokit2.entropy_permutation
+
+        """
+        logger.info("Calculating permutation entropy.")
+
+        emb_dim = self.params["m"]
+        delay = self.params["delay"]
+
+        assert isinstance(emb_dim, int), "Embedding dimension must be integer."
+        assert isinstance(delay, int), "Delay must be integer."
+
+        _, n_roi = extracted_bold_values.shape
+        perm_en_roi = np.zeros((n_roi, 1))
+
+        for idx_roi in range(n_roi):
+            sig = extracted_bold_values[:, idx_roi]
+            tmp = nk.entropy_permutation(
+                sig,
+                dimension=emb_dim,
+                delay=delay,
+                weighted=False,  # PE, not wPE
+                corrected=True,  # Normalized PE
+            )
+
+            perm_en_roi[idx_roi] = tmp[0]
+
+        if np.isnan(np.sum(perm_en_roi)):
+            warn_with_log("There is NaN in the permutation entropy values!")
+
+        return perm_en_roi.T  # 1 X n_roi

junifer/markers/complexity/range_entropy.py

@@ -0,0 +1,136 @@
+"""Provide class for range entropy of a time series."""
+
+# Authors: Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
+#          Leonard Sasse <l.sasse@fz-juelich.de>
+# License: AGPL
+
+from typing import Dict, List, Optional, Union
+
+import neurokit2 as nk
+import numpy as np
+
+from ...api.decorators import register_marker
+from ...utils import logger, warn_with_log
+from .complexity_base import ComplexityBase
+
+
+@register_marker
+class RangeEntropy(ComplexityBase):
+    """Class for range entropy of a time series.
+
+    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`.
+    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 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 range entropy calculation function. For more
+        information, check out ``junifer.markers.utils._range_entropy``.
+        If None, value is set to {"m": 2, "tol": 0.5, "delay": 1}
+        (default None).
+    name : str, optional
+        The name of the marker. If None, it will use the class name
+        (default None).
+
+    Warnings
+    --------
+    This class is not automatically imported by junifer and requires you to
+    import it explicitly. You can do it programmatically by
+    ``from junifer.markers.complexity import RangeEntropy`` or in the YAML by
+    ``with: junifer.markers.complexity``.
+
+    """
+
+    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:
+            self.params = {"m": 2, "tol": 0.5, "delay": 1}
+        else:
+            self.params = params
+
+    def compute_complexity(
+        self,
+        extracted_bold_values: np.ndarray,
+    ) -> np.ndarray:
+        """Compute complexity measure.
+
+        Take a timeseries of brain areas, and calculate
+        range entropy according to the method outlined in [1].
+
+        Parameters
+        ----------
+        extracted_bold_values : numpy.ndarray
+            The BOLD values extracted via parcel aggregation.
+
+        Returns
+        -------
+        numpy.ndarray
+            The values after computing complexity measure.
+
+        References
+        ----------
+        .. [1] A. Omidvarnia et al. (2018)
+               Range Entropy: A Bridge between Signal Complexity and
+               Self-Similarity.
+               Entropy, vol. 20, no. 12, p. 962, 2018.
+
+        See Also
+        --------
+        neurokit2.entropy_range
+
+        """
+        logger.info("Calculating range entropy.")
+
+        emb_dim = self.params["m"]
+        delay = self.params["delay"]
+        tolerance = self.params["tol"]
+
+        assert isinstance(emb_dim, int), "Embedding dimension must be integer."
+        assert isinstance(delay, int), "Delay must be integer."
+        assert isinstance(
+            tolerance, float
+        ), "Tolerance must be a float number between 0 and 1."
+
+        _, n_roi = extracted_bold_values.shape
+        range_en_roi = np.zeros((n_roi, 1))
+
+        for idx_roi in range(n_roi):
+            sig = extracted_bold_values[:, idx_roi]
+            tmp = nk.entropy_range(
+                sig,
+                dimension=emb_dim,
+                delay=delay,
+                tolerance=tolerance,
+                method="mSampEn",  # RangeEn B
+            )
+
+            range_en_roi[idx_roi] = tmp[0]
+
+        if np.isnan(np.sum(range_en_roi)):
+            warn_with_log("There is NaN in the range entropy values!")
+
+        return range_en_roi.T  # 1 X n_roi