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

junifer/markers/complexity/range_entropy_auc.py

@@ -0,0 +1,145 @@
+"""Provide class for the AUC of 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 RangeEntropyAUC(ComplexityBase):
+    """Class for AUC of range entropy values of a time series over r = 0 to 1.
+
+    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, "delay": 1, "n_r": 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 RangeEntropyAUC`` 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, "delay": 1, "n_r": 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 range entropy according to
+        the method outlined in [1] across the range of tolerance value r from 0
+        to 1, and compute its area under the curve.
+
+        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 AUC of range entropy.")
+
+        emb_dim = self.params["m"]
+        delay = self.params["delay"]
+        n_r = self.params["n_r"]
+
+        assert isinstance(emb_dim, int), "Embedding dimension must be integer."
+        assert isinstance(delay, int), "Delay must be integer."
+        assert isinstance(n_r, int), "n_r must be an integer."
+
+        r_span = np.arange(0, 1, 1 / n_r)  # Tolerance r span
+        _, n_roi = extracted_bold_values.shape
+        range_en_auc_roi = np.zeros((n_roi, 1))
+
+        for idx_roi in range(n_roi):
+            sig = extracted_bold_values[:, idx_roi]
+
+            range_ent_vec = np.zeros(n_r)
+            idx_r = 0
+            for tolerance in r_span:
+                range_en_auc_roi_tmp = nk.entropy_range(
+                    sig,
+                    dimension=emb_dim,
+                    delay=delay,
+                    tolerance=tolerance,
+                    method="mSampEn",  # RangeEn B
+                )
+
+                range_ent_vec[idx_r] = range_en_auc_roi_tmp[0]
+                idx_r = idx_r + 1
+
+            range_en_auc_roi[idx_roi] = np.trapz(range_ent_vec)
+
+        range_en_auc_roi = range_en_auc_roi / n_r
+
+        if np.isnan(np.sum(range_en_auc_roi)):
+            warn_with_log("There is NaN in the auc of range entropy values!")
+
+        return range_en_auc_roi.T  # 1 X n_roi

junifer/markers/complexity/sample_entropy.py

@@ -0,0 +1,134 @@
+"""Provide class for sample 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 SampleEntropy(ComplexityBase):
+    """Class for sample 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 sample entropy calculation function.
+        For more information, check out
+        ``junifer.markers.utils._sample_entropy``.
+        If None, value is set to
+        {"m": 2, "delay": 1, "tol": 0.5} (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 SampleEntropy`` 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, "tol": 0.5}
+        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 sample entropy [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] Richman, J., Moorman, J.
+               Physiological time-series analysis using approximate entropy and
+               sample entropy.
+               Am. J. Physiol. Heart Circ. Physiol., 278 (6) (2000),
+               pp. H2039-2049
+
+        See Also
+        --------
+        neurokit2.entropy_sample
+
+        """
+        logger.info("Calculating sample entropy.")
+
+        emb_dim = self.params["m"]
+        delay = self.params["delay"]
+        tol = self.params["tol"]
+
+        assert isinstance(emb_dim, int), "Embedding dimension must be integer."
+        assert isinstance(delay, int), "Delay must be integer."
+        assert isinstance(
+            tol, float
+        ), "Tolerance must be a positive float number."
+
+        _, n_roi = extracted_bold_values.shape
+        samp_en_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_sample(
+                sig, dimension=emb_dim, delay=delay, tolerance=tol_corrected
+            )
+
+            samp_en_roi[idx_roi] = tmp[0]
+
+        if np.isnan(np.sum(samp_en_roi)):
+            warn_with_log("There is NaN in the entropy values!")
+
+        return samp_en_roi.T  # 1 X n_roi

junifer/markers/complexity/tests/test_complexity_base.py

@@ -0,0 +1,19 @@
+"""Provide tests for base complexity marker."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+import pytest
+
+
+pytest.importorskip("neurokit2")
+
+from junifer.markers.complexity.complexity_base import (  # noqa: E402
+    ComplexityBase,
+)
+
+
+def test_base_complexity_marker_abstractness() -> None:
+    """Test ComplexityBase is an abstract base class."""
+    with pytest.raises(TypeError, match="abstract"):
+        ComplexityBase()

junifer/markers/complexity/tests/test_hurst_exponent.py

@@ -0,0 +1,69 @@
+"""Provide test for Hurst exponent."""
+
+# Authors: Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from pathlib import Path
+
+import pytest
+
+
+pytest.importorskip("neurokit2")
+
+
+from junifer.datareader import DefaultDataReader  # noqa: E402
+from junifer.markers.complexity import HurstExponent  # noqa: E402
+from junifer.storage import SQLiteFeatureStorage  # noqa: E402
+from junifer.testing.datagrabbers import (  # noqa: E402
+    SPMAuditoryTestingDataGrabber,
+)
+
+
+# Set parcellation
+PARCELLATION = "Schaefer100x17"
+
+
+def test_compute() -> None:
+    """Test HurstExponent compute()."""
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Fetch element
+        element = dg["sub001"]
+        # Fetch element data
+        element_data = DefaultDataReader().fit_transform(element)
+        # Initialize the marker
+        marker = HurstExponent(parcellation=PARCELLATION)
+        # Compute the marker
+        feature_map = marker.fit_transform(element_data)
+        # Assert the dimension of timeseries
+        assert feature_map["BOLD"]["data"].ndim == 2
+
+
+def test_get_output_type() -> None:
+    """Test HurstExponent get_output_type()."""
+    marker = HurstExponent(parcellation=PARCELLATION)
+    assert marker.get_output_type("BOLD") == "vector"
+
+
+def test_store(tmp_path: Path) -> None:
+    """Test HurstExponent store().
+
+    Parameters
+    ----------
+    tmp_path : pathlib.Path
+        The path to the test directory.
+
+    """
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Fetch element
+        element = dg["sub001"]
+        # Fetch element data
+        element_data = DefaultDataReader().fit_transform(element)
+        # Initialize the marker
+        marker = HurstExponent(parcellation=PARCELLATION)
+        # Create storage
+        storage = SQLiteFeatureStorage(
+            uri=tmp_path / "test_hurst_exponent.sqlite"
+        )
+        # Compute the marker and store
+        marker.fit_transform(input=element_data, storage=storage)

junifer/markers/complexity/tests/test_multiscale_entropy_auc.py

@@ -0,0 +1,68 @@
+"""Provide test for the AUC of multiscale entropy."""
+
+# Authors: Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from pathlib import Path
+
+import pytest
+
+
+pytest.importorskip("neurokit2")
+
+from junifer.datareader import DefaultDataReader  # noqa: E402
+from junifer.markers.complexity import MultiscaleEntropyAUC  # noqa: E402
+from junifer.storage import SQLiteFeatureStorage  # noqa: E402
+from junifer.testing.datagrabbers import (  # noqa: E402
+    SPMAuditoryTestingDataGrabber,
+)
+
+
+# Set parcellation
+PARCELLATION = "Schaefer100x17"
+
+
+def test_compute() -> None:
+    """Test MultiscaleEntropyAUC compute()."""
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Fetch element
+        element = dg["sub001"]
+        # Fetch element data
+        element_data = DefaultDataReader().fit_transform(element)
+        # Initialize the marker
+        marker = MultiscaleEntropyAUC(parcellation=PARCELLATION)
+        # Compute the marker
+        feature_map = marker.fit_transform(element_data)
+        # Assert the dimension of timeseries
+        assert feature_map["BOLD"]["data"].ndim == 2
+
+
+def test_get_output_type() -> None:
+    """Test MultiscaleEntropyAUC get_output_type()."""
+    marker = MultiscaleEntropyAUC(parcellation=PARCELLATION)
+    assert marker.get_output_type("BOLD") == "vector"
+
+
+def test_store(tmp_path: Path) -> None:
+    """Test MultiscaleEntropyAUC store().
+
+    Parameters
+    ----------
+    tmp_path : pathlib.Path
+        The path to the test directory.
+
+    """
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Fetch element
+        element = dg["sub001"]
+        # Fetch element data
+        element_data = DefaultDataReader().fit_transform(element)
+        # Initialize the marker
+        marker = MultiscaleEntropyAUC(parcellation=PARCELLATION)
+        # Create storage
+        storage = SQLiteFeatureStorage(
+            uri=tmp_path / "test_multiscale_entropy_auc.sqlite"
+        )
+        # Compute the marker and store
+        marker.fit_transform(input=element_data, storage=storage)

junifer/markers/complexity/tests/test_perm_entropy.py

@@ -0,0 +1,68 @@
+"""Provide test for permutation entropy."""
+
+# Authors: Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from pathlib import Path
+
+import pytest
+
+
+pytest.importorskip("neurokit2")
+
+from junifer.datareader import DefaultDataReader  # noqa: E402
+from junifer.markers.complexity import PermEntropy  # noqa: E402
+from junifer.storage import SQLiteFeatureStorage  # noqa: E402
+from junifer.testing.datagrabbers import (  # noqa: E402
+    SPMAuditoryTestingDataGrabber,
+)
+
+
+# Set parcellation
+PARCELLATION = "Schaefer100x17"
+
+
+def test_compute() -> None:
+    """Test PermEntropy compute()."""
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Fetch element
+        element = dg["sub001"]
+        # Fetch element data
+        element_data = DefaultDataReader().fit_transform(element)
+        # Initialize the marker
+        marker = PermEntropy(parcellation=PARCELLATION)
+        # Compute the marker
+        feature_map = marker.fit_transform(element_data)
+        # Assert the dimension of timeseries
+        assert feature_map["BOLD"]["data"].ndim == 2
+
+
+def test_get_output_type() -> None:
+    """Test PermEntropy get_output_type()."""
+    marker = PermEntropy(parcellation=PARCELLATION)
+    assert marker.get_output_type("BOLD") == "vector"
+
+
+def test_store(tmp_path: Path) -> None:
+    """Test PermEntropy store().
+
+    Parameters
+    ----------
+    tmp_path : pathlib.Path
+        The path to the test directory.
+
+    """
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Fetch element
+        element = dg["sub001"]
+        # Fetch element data
+        element_data = DefaultDataReader().fit_transform(element)
+        # Initialize the marker
+        marker = PermEntropy(parcellation=PARCELLATION)
+        # Create storage
+        storage = SQLiteFeatureStorage(
+            uri=tmp_path / "test_perm_entropy.sqlite"
+        )
+        # Compute the marker and store
+        marker.fit_transform(input=element_data, storage=storage)

junifer/markers/complexity/tests/test_range_entropy.py

@@ -0,0 +1,69 @@
+"""Provide test for range entropy."""
+
+# Authors: Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from pathlib import Path
+
+import pytest
+
+
+pytest.importorskip("neurokit2")
+
+
+from junifer.datareader import DefaultDataReader  # noqa: E402
+from junifer.markers.complexity import RangeEntropy  # noqa: E402
+from junifer.storage import SQLiteFeatureStorage  # noqa: E402
+from junifer.testing.datagrabbers import (  # noqa: E402
+    SPMAuditoryTestingDataGrabber,
+)
+
+
+# Set parcellation
+PARCELLATION = "Schaefer100x17"
+
+
+def test_compute() -> None:
+    """Test RangeEntropy compute()."""
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Fetch element
+        element = dg["sub001"]
+        # Fetch element data
+        element_data = DefaultDataReader().fit_transform(element)
+        # Initialize the marker
+        marker = RangeEntropy(parcellation=PARCELLATION)
+        # Compute the marker
+        feature_map = marker.fit_transform(element_data)
+        # Assert the dimension of timeseries
+        assert feature_map["BOLD"]["data"].ndim == 2
+
+
+def test_get_output_type() -> None:
+    """Test RangeEntropy get_output_type()."""
+    marker = RangeEntropy(parcellation=PARCELLATION)
+    assert marker.get_output_type("BOLD") == "vector"
+
+
+def test_store(tmp_path: Path) -> None:
+    """Test RangeEntropy store().
+
+    Parameters
+    ----------
+    tmp_path : pathlib.Path
+        The path to the test directory.
+
+    """
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Fetch element
+        element = dg["sub001"]
+        # Fetch element data
+        element_data = DefaultDataReader().fit_transform(element)
+        # Initialize the marker
+        marker = RangeEntropy(parcellation=PARCELLATION)
+        # Create storage
+        storage = SQLiteFeatureStorage(
+            uri=tmp_path / "test_range_entropy.sqlite"
+        )
+        # Compute the marker and store
+        marker.fit_transform(input=element_data, storage=storage)

junifer/markers/complexity/tests/test_range_entropy_auc.py

@@ -0,0 +1,69 @@
+"""Provide test for the AUC of range entropy."""
+
+# Authors: Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from pathlib import Path
+
+import pytest
+
+
+pytest.importorskip("neurokit2")
+
+
+from junifer.datareader import DefaultDataReader  # noqa: E402
+from junifer.markers.complexity import RangeEntropyAUC  # noqa: E402
+from junifer.storage import SQLiteFeatureStorage  # noqa: E402
+from junifer.testing.datagrabbers import (  # noqa: E402
+    SPMAuditoryTestingDataGrabber,
+)
+
+
+# Set parcellation
+PARCELLATION = "Schaefer100x17"
+
+
+def test_compute() -> None:
+    """Test RangeEntropyAUC compute()."""
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Fetch element
+        element = dg["sub001"]
+        # Fetch element data
+        element_data = DefaultDataReader().fit_transform(element)
+        # Initialize the marker
+        marker = RangeEntropyAUC(parcellation=PARCELLATION)
+        # Compute the marker
+        feature_map = marker.fit_transform(element_data)
+        # Assert the dimension of timeseries
+        assert feature_map["BOLD"]["data"].ndim == 2
+
+
+def test_get_output_type() -> None:
+    """Test RangeEntropyAUC get_output_type()."""
+    marker = RangeEntropyAUC(parcellation=PARCELLATION)
+    assert marker.get_output_type("BOLD") == "vector"
+
+
+def test_store(tmp_path: Path) -> None:
+    """Test RangeEntropyAUC store().
+
+    Parameters
+    ----------
+    tmp_path : pathlib.Path
+        The path to the test directory.
+
+    """
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Fetch element
+        element = dg["sub001"]
+        # Fetch element data
+        element_data = DefaultDataReader().fit_transform(element)
+        # Initialize the marker
+        marker = RangeEntropyAUC(parcellation=PARCELLATION)
+        # Create storage
+        storage = SQLiteFeatureStorage(
+            uri=tmp_path / "test_range_entropy_auc.sqlite"
+        )
+        # Compute the marker and store
+        marker.fit_transform(input=element_data, storage=storage)