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

junifer/markers/complexity/tests/test_sample_entropy.py

@@ -0,0 +1,68 @@
+"""Provide test for sample 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 SampleEntropy  # 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 SampleEntropy compute()."""
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Fetch element
+        element = dg["sub001"]
+        # Fetch element data
+        element_data = DefaultDataReader().fit_transform(element)
+        # Initialize the marker
+        marker = SampleEntropy(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 SampleEntropy get_output_type()."""
+    marker = SampleEntropy(parcellation=PARCELLATION)
+    assert marker.get_output_type("BOLD") == "vector"
+
+
+def test_store(tmp_path: Path) -> None:
+    """Test SampleEntropy 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 = SampleEntropy(parcellation=PARCELLATION)
+        # Create storage
+        storage = SQLiteFeatureStorage(
+            uri=tmp_path / "test_sample_entropy.sqlite"
+        )
+        # Compute the marker and store
+        marker.fit_transform(input=element_data, storage=storage)

junifer/markers/complexity/tests/test_weighted_perm_entropy.py

@@ -0,0 +1,68 @@
+"""Provide test for weighted 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 WeightedPermEntropy  # 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 WeightedPermEntropy compute()."""
+    with SPMAuditoryTestingDataGrabber() as dg:
+        # Fetch element
+        element = dg["sub001"]
+        # Fetch element data
+        element_data = DefaultDataReader().fit_transform(element)
+        # Initialize the marker
+        marker = WeightedPermEntropy(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 WeightedPermEntropy get_output_type()."""
+    marker = WeightedPermEntropy(parcellation=PARCELLATION)
+    assert marker.get_output_type("BOLD") == "vector"
+
+
+def test_store(tmp_path: Path) -> None:
+    """Test WeightedPermEntropy 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 = WeightedPermEntropy(parcellation=PARCELLATION)
+        # Create storage
+        storage = SQLiteFeatureStorage(
+            uri=tmp_path / "test_weighted_perm_entropy.sqlite"
+        )
+        # Compute the marker and store
+        marker.fit_transform(input=element_data, storage=storage)

junifer/markers/complexity/weighted_perm_entropy.py

@@ -0,0 +1,133 @@
+"""Provide class for weighted 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 WeightedPermEntropy(ComplexityBase):
+    """Class for weighted 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 weighted permutation entropy calculation
+        function.
+        For more information, check out
+        ``junifer.markers.utils._weighted_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 WeightedPermEntropy`` 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 weighted 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] Fadlallah, B., Chen, B., Keil, A., & Principe, J. (2013)
+               Weighted-permutation entropy: A complexity measure for
+               time series incorporating amplitude information.
+               Physical Review E, 87(2), 022911.
+
+        See Also
+        --------
+        neurokit2.entropy_permutation
+
+        """
+        logger.info("Calculating weighted 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
+        wperm_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=True,  # Weighted PE
+                corrected=True,  # Normalized PE
+            )
+
+            wperm_en_roi[idx_roi] = tmp[0]
+
+        if np.isnan(np.sum(wperm_en_roi)):
+            warn_with_log("There is NaN in the entropy values!")
+
+        return wperm_en_roi.T  # 1 X n_roi

junifer/markers/falff/_afni_falff.py

@@ -0,0 +1,153 @@
+"""Provide class for computing ALFF using AFNI."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from functools import lru_cache
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Union,
+)
+
+import nibabel as nib
+
+from ...pipeline import WorkDirManager
+from ...pipeline.singleton import singleton
+from ...utils import logger, run_ext_cmd
+
+
+if TYPE_CHECKING:
+    from nibabel import Nifti1Image
+
+
+@singleton
+class AFNIALFF:
+    """Class for computing ALFF using AFNI.
+
+    This class uses AFNI's 3dRSFC to compute ALFF. It's designed as a singleton
+    with caching for efficient computation.
+
+    """
+
+    _EXT_DEPENDENCIES: ClassVar[List[Dict[str, Union[str, List[str]]]]] = [
+        {
+            "name": "afni",
+            "commands": ["3dRSFC", "3dAFNItoNIFTI"],
+        },
+    ]
+
+    def __del__(self) -> None:
+        """Terminate the class."""
+        # Clear the computation cache
+        logger.debug("Clearing cache for ALFF computation via AFNI")
+        self.compute.cache_clear()
+
+    @lru_cache(maxsize=None, typed=True)
+    def compute(
+        self,
+        data: "Nifti1Image",
+        highpass: float,
+        lowpass: float,
+        tr: Optional[float],
+    ) -> Tuple["Nifti1Image", "Nifti1Image", Path, Path]:
+        """Compute ALFF + fALFF map.
+
+        Parameters
+        ----------
+        data : 4D Niimg-like object
+            Images to process.
+        highpass : positive float
+            Highpass cutoff frequency.
+        lowpass : positive float
+            Lowpass cutoff frequency.
+        tr : positive float, optional
+            The Repetition Time of the BOLD data.
+
+        Returns
+        -------
+        Niimg-like object
+            ALFF map.
+        Niimg-like object
+            fALFF map.
+        pathlib.Path
+            The path to the ALFF map as NIfTI.
+        pathlib.Path
+            The path to the fALFF map as NIfTI.
+
+        """
+        logger.debug("Creating cache for ALFF computation via AFNI")
+
+        # Create component-scoped tempdir
+        tempdir = WorkDirManager().get_tempdir(prefix="afni_alff+falff")
+
+        # Save target data to a component-scoped tempfile
+        nifti_in_file_path = tempdir / "input.nii"  # needs to be .nii
+        nib.save(data, nifti_in_file_path)
+
+        # Set 3dRSFC command
+        alff_falff_out_path_prefix = tempdir / "alff_falff"
+        bp_cmd = [
+            "3dRSFC",
+            f"-prefix {alff_falff_out_path_prefix.resolve()}",
+            f"-input {nifti_in_file_path.resolve()}",
+            f"-band {highpass} {lowpass}",
+            "-no_rsfa -nosat -nodetrend",
+        ]
+        # Check tr
+        if tr is not None:
+            bp_cmd.append(f"-dt {tr}")
+        # Call 3dRSFC
+        run_ext_cmd(name="3dRSFC", cmd=bp_cmd)
+
+        # Create element-scoped tempdir so that the ALFF and fALFF maps are
+        # available later as nibabel stores file path reference for
+        # loading on computation
+        element_tempdir = WorkDirManager().get_element_tempdir(
+            prefix="afni_alff_falff"
+        )
+
+        params_suffix = f"_{highpass}_{lowpass}_{tr}"
+
+        # Convert alff afni to nifti
+        alff_afni_to_nifti_out_path = (
+            element_tempdir / f"alff{params_suffix}_output.nii"
+        )  # needs to be .nii
+        convert_alff_cmd = [
+            "3dAFNItoNIFTI",
+            f"-prefix {alff_afni_to_nifti_out_path.resolve()}",
+            f"{alff_falff_out_path_prefix}_ALFF+tlrc.BRIK",
+        ]
+        # Call 3dAFNItoNIFTI
+        run_ext_cmd(name="3dAFNItoNIFTI", cmd=convert_alff_cmd)
+
+        # Convert falff afni to nifti
+        falff_afni_to_nifti_out_path = (
+            element_tempdir / f"falff{params_suffix}_output.nii"
+        )  # needs to be .nii
+        convert_falff_cmd = [
+            "3dAFNItoNIFTI",
+            f"-prefix {falff_afni_to_nifti_out_path.resolve()}",
+            f"{alff_falff_out_path_prefix}_fALFF+tlrc.BRIK",
+        ]
+        # Call 3dAFNItoNIFTI
+        run_ext_cmd(name="3dAFNItoNIFTI", cmd=convert_falff_cmd)
+
+        # Load nifti
+        alff_data = nib.load(alff_afni_to_nifti_out_path)
+        falff_data = nib.load(falff_afni_to_nifti_out_path)
+
+        # Delete tempdir
+        WorkDirManager().delete_tempdir(tempdir)
+
+        return (
+            alff_data,
+            falff_data,
+            alff_afni_to_nifti_out_path,
+            falff_afni_to_nifti_out_path,
+        )  # type: ignore

junifer/markers/falff/_junifer_falff.py

@@ -0,0 +1,142 @@
+"""Provide class for computing ALFF using junifer."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from functools import lru_cache
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    Optional,
+    Set,
+    Tuple,
+)
+
+import nibabel as nib
+import numpy as np
+import scipy as sp
+from nilearn import image as nimg
+
+from ...pipeline import WorkDirManager
+from ...pipeline.singleton import singleton
+from ...utils import logger
+
+
+if TYPE_CHECKING:
+    from nibabel import Nifti1Image
+
+
+@singleton
+class JuniferALFF:
+    """Class for computing ALFF using junifer.
+
+    It's designed as a singleton with caching for efficient computation.
+
+    """
+
+    _DEPENDENCIES: ClassVar[Set[str]] = {"numpy", "nilearn", "scipy"}
+
+    def __del__(self) -> None:
+        """Terminate the class."""
+        # Clear the computation cache
+        logger.debug("Clearing cache for ALFF computation via junifer")
+        self.compute.cache_clear()
+
+    @lru_cache(maxsize=None, typed=True)
+    def compute(
+        self,
+        data: "Nifti1Image",
+        highpass: float,
+        lowpass: float,
+        tr: Optional[float],
+    ) -> Tuple["Nifti1Image", "Nifti1Image", Path, Path]:
+        """Compute ALFF + fALFF map.
+
+        Parameters
+        ----------
+        data : 4D Niimg-like object
+            Images to process.
+        highpass : positive float
+            Highpass cutoff frequency.
+        lowpass : positive float
+            Lowpass cutoff frequency.
+        tr : positive float, optional
+            The Repetition Time of the BOLD data.
+
+        Returns
+        -------
+        Niimg-like object
+            ALFF map.
+        Niimg-like object
+            fALFF map.
+        pathlib.Path
+            The path to the ALFF map as NIfTI.
+        pathlib.Path
+            The path to the fALFF map as NIfTI.
+
+        """
+        logger.debug("Creating cache for ALFF computation via junifer")
+
+        # Get scan data
+        niimg_data = data.get_fdata().copy()
+        if tr is None:
+            tr = float(data.header["pixdim"][4])  # type: ignore
+            logger.info(f"`tr` not provided, using `tr` from header: {tr}")
+
+        # Bandpass the data within the lowpass and highpass cutoff freqs
+        fft_data = sp.fft.fft(niimg_data, axis=-1)
+        fft_freqs = np.abs(sp.fft.fftfreq(niimg_data.shape[-1], tr))
+        # Frequency difference
+        fft_freqs_diff = fft_freqs[1] - fft_freqs[0]
+        # Nyquist frequency
+        nyquist = np.max(fft_freqs)
+        # FFT sample frequency count
+        n_fft = len(fft_freqs)
+        logger.info(
+            f"FFT: nfft = {n_fft}, dFreq = {fft_freqs_diff}, "
+            f"nyquist = {nyquist}"
+        )
+
+        # Compute the denominator on the broadband signal
+        all_freq_mask = fft_freqs > 0
+        denominator = np.sum(np.abs(fft_data[..., all_freq_mask]), axis=-1)
+
+        # Compute the numerator on the bandpassed signal
+        freq_mask = np.logical_and(fft_freqs > highpass, fft_freqs < lowpass)
+
+        # Compute ALFF
+        numerator = np.sum(np.abs(fft_data[..., freq_mask]), axis=-1)
+
+        # Compute fALFF, but avoid division by zero
+        denom_mask = denominator <= 0.000001
+        denominator[denom_mask] = 1  # set to 1 to avoid division by zero
+        # Calculate fALFF
+        falff = np.divide(numerator, denominator)
+        # Set the values where denominator is zero to zero
+        falff[denom_mask] = 0
+
+        # Calculate ALFF
+        alff = numerator / np.sqrt(niimg_data.shape[-1])
+        alff_data = nimg.new_img_like(
+            ref_niimg=data,
+            data=alff,
+        )
+        falff_data = nimg.new_img_like(
+            ref_niimg=data,
+            data=falff,
+        )
+
+        # Create element-scoped tempdir so that the ALFF and fALFF maps are
+        # available later as nibabel stores file path reference for
+        # loading on computation
+        element_tempdir = WorkDirManager().get_element_tempdir(
+            prefix="junifer_alff+falff"
+        )
+        output_alff_path = element_tempdir / "output_alff.nii.gz"
+        output_falff_path = element_tempdir / "output_falff.nii.gz"
+        # Save computed data to file
+        nib.save(alff_data, output_alff_path)
+        nib.save(falff_data, output_falff_path)
+
+        return alff_data, falff_data, output_alff_path, output_falff_path  # type: ignore