junifer 0.0.7.dev153__py3-none-any.whl → 0.0.7.dev171__py3-none-any.whl

junifer/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.7.dev153'
-__version_tuple__ = version_tuple = (0, 0, 7, 'dev153')
+__version__ = version = '0.0.7.dev171'
+__version_tuple__ = version_tuple = (0, 0, 7, 'dev171')
 
 __commit_id__ = commit_id = None

junifer/conftest.py

@@ -1,10 +1,14 @@
 """Provide conftest for pytest."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
+from pathlib import Path
+
 import pytest
 
+from junifer.datagrabber import PatternDataladDataGrabber
 from junifer.utils.singleton import Singleton
 
 
@@ -23,3 +27,31 @@ def reset_singletons() -> None:
     # Force deleting the singletons
     for elem in to_remove:
         del elem
+
+
+@pytest.fixture
+def maps_datagrabber(tmp_path: Path) -> PatternDataladDataGrabber:
+    """Return a PatternDataladDataGrabber for maps testing.
+
+    Parameters
+    ----------
+    tmp_path : pathlib.Path
+        The path to the test directory.
+
+    """
+    dg = PatternDataladDataGrabber(
+        uri="https://github.com/OpenNeuroDatasets/ds005226.git",
+        types=["BOLD"],
+        patterns={
+            "BOLD": {
+                "pattern": (
+                    "derivatives/pre-processed_data/space-MNI/{subject}/"
+                    "{subject-padded}_task-{task}_run-{run}_space-MNI152NLin6Asym"
+                    "_res-2_desc-preproc_bold.nii.gz"
+                ),
+                "space": "MNI152NLin6Asym",
+            },
+        },
+        replacements=["subject", "subject-padded", "task", "run"],
+    )
+    return dg

junifer/markers/__init__.pyi

@@ -1,17 +1,23 @@
 __all__ = [
     "BaseMarker",
     "RSSETSMarker",
+    "MapsAggregation",
     "ParcelAggregation",
     "SphereAggregation",
+    "FunctionalConnectivityMaps",
     "FunctionalConnectivityParcels",
     "FunctionalConnectivitySpheres",
     "CrossParcellationFC",
+    "EdgeCentricFCMaps",
     "EdgeCentricFCParcels",
     "EdgeCentricFCSpheres",
+    "ReHoMaps",
     "ReHoParcels",
     "ReHoSpheres",
+    "ALFFMaps",
     "ALFFParcels",
     "ALFFSpheres",
+    "TemporalSNRMaps",
     "TemporalSNRParcels",
     "TemporalSNRSpheres",
     "BrainPrint",
@@ -19,18 +25,22 @@ __all__ = [
 
 from .base import BaseMarker
 from .ets_rss import RSSETSMarker
+from .maps_aggregation import MapsAggregation
 from .parcel_aggregation import ParcelAggregation
 from .sphere_aggregation import SphereAggregation
 from .functional_connectivity import (
+    FunctionalConnectivityMaps,
     FunctionalConnectivityParcels,
     FunctionalConnectivitySpheres,
     CrossParcellationFC,
+    EdgeCentricFCMaps,
     EdgeCentricFCParcels,
     EdgeCentricFCSpheres,
 )
-from .reho import ReHoParcels, ReHoSpheres
-from .falff import ALFFParcels, ALFFSpheres
+from .reho import ReHoMaps, ReHoParcels, ReHoSpheres
+from .falff import ALFFMaps, ALFFParcels, ALFFSpheres
 from .temporal_snr import (
+    TemporalSNRMaps,
     TemporalSNRParcels,
     TemporalSNRSpheres,
 )

junifer/markers/falff/__init__.pyi

@@ -1,4 +1,5 @@
-__all__ = ["ALFFParcels", "ALFFSpheres"]
+__all__ = ["ALFFMaps", "ALFFParcels", "ALFFSpheres"]
 
+from .falff_maps import ALFFMaps
 from .falff_parcels import ALFFParcels
 from .falff_spheres import ALFFSpheres

junifer/markers/falff/falff_maps.py

@@ -0,0 +1,151 @@
+"""Provide class for ALFF / fALFF on maps."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from typing import Any, Optional, Union
+
+from ...api.decorators import register_marker
+from ...utils import logger
+from ..maps_aggregation import MapsAggregation
+from .falff_base import ALFFBase
+
+
+__all__ = ["ALFFMaps"]
+
+
+@register_marker
+class ALFFMaps(ALFFBase):
+    """Class for ALFF / fALFF on maps.
+
+    Parameters
+    ----------
+    maps : str
+        The name of the map(s) to use.
+        See :func:`.list_data` for options.
+    using : {"junifer", "afni"}
+        Implementation to use for computing ALFF:
+
+        * "junifer" : Use ``junifer``'s own ALFF implementation
+        * "afni" : Use AFNI's ``3dRSFC``
+
+    highpass : positive float, optional
+        The highpass cutoff frequency for the bandpass filter. If 0,
+        it will not apply a highpass filter (default 0.01).
+    lowpass : positive float, optional
+        The lowpass cutoff frequency for the bandpass filter (default 0.1).
+    tr : positive float, optional
+        The Repetition Time of the BOLD data. If None, will extract
+        the TR from NIfTI header (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, will use the class name (default
+        None).
+
+    Notes
+    -----
+    The ``tr`` parameter is crucial for the correctness of fALFF/ALFF
+    computation. If a dataset is correctly preprocessed, the ``tr`` should be
+    extracted from the NIfTI without any issue. However, it has been
+    reported that some preprocessed data might not have the correct ``tr`` in
+    the NIfTI header.
+
+    ALFF/fALFF are computed using a bandpass butterworth filter. See
+    :func:`scipy.signal.butter` and :func:`scipy.signal.filtfilt` for more
+    details.
+
+    """
+
+    def __init__(
+        self,
+        maps: str,
+        using: str,
+        highpass: float = 0.01,
+        lowpass: float = 0.1,
+        tr: Optional[float] = None,
+        masks: Union[str, dict, list[Union[dict, str]], None] = None,
+        name: Optional[str] = None,
+    ) -> None:
+        # Superclass init first to validate `using` parameter
+        super().__init__(
+            highpass=highpass,
+            lowpass=lowpass,
+            using=using,
+            tr=tr,
+            name=name,
+        )
+        self.maps = maps
+        self.masks = masks
+
+    def compute(
+        self,
+        input: dict[str, Any],
+        extra_input: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Compute.
+
+        Parameters
+        ----------
+        input : dict
+            The BOLD data as dictionary.
+        extra_input : dict, optional
+            The other fields in the pipeline data object (default None).
+
+        Returns
+        -------
+        dict
+            The computed result as dictionary. This will be either returned
+            to the user or stored in the storage by calling the store method
+            with this as a parameter. The dictionary has the following keys:
+
+            * ``alff`` : dictionary with the following keys:
+
+              - ``data`` : ROI values as ``numpy.ndarray``
+              - ``col_names`` : ROI labels as list of str
+
+            * ``falff`` : dictionary with the following keys:
+
+              - ``data`` : ROI values as ``numpy.ndarray``
+              - ``col_names`` : ROI labels as list of str
+
+        """
+        logger.info("Calculating ALFF / fALFF for maps")
+
+        # Compute ALFF + fALFF
+        alff_output, falff_output, alff_output_path, falff_output_path = (
+            self._compute(input_data=input)
+        )
+
+        # Perform aggregation on ALFF + fALFF
+        aggregation_alff_input = dict(input.items())
+        aggregation_falff_input = dict(input.items())
+        aggregation_alff_input["data"] = alff_output
+        aggregation_falff_input["data"] = falff_output
+        aggregation_alff_input["path"] = alff_output_path
+        aggregation_falff_input["path"] = falff_output_path
+
+        return {
+            "alff": {
+                **MapsAggregation(
+                    maps=self.maps,
+                    masks=self.masks,
+                    on="BOLD",
+                ).compute(
+                    input=aggregation_alff_input,
+                    extra_input=extra_input,
+                )["aggregation"],
+            },
+            "falff": {
+                **MapsAggregation(
+                    maps=self.maps,
+                    masks=self.masks,
+                    on="BOLD",
+                ).compute(
+                    input=aggregation_falff_input,
+                    extra_input=extra_input,
+                )["aggregation"],
+            },
+        }

junifer/markers/falff/tests/test_falff_maps.py

@@ -0,0 +1,167 @@
+"""Provide tests for ALFFMaps."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+import logging
+from pathlib import Path
+
+import pytest
+import scipy as sp
+
+from junifer.datagrabber import PatternDataladDataGrabber
+from junifer.datareader import DefaultDataReader
+from junifer.markers import ALFFMaps
+from junifer.pipeline import WorkDirManager
+from junifer.pipeline.utils import _check_afni
+from junifer.storage import HDF5FeatureStorage
+
+
+MAPS = "Smith_rsn_10"
+
+
+@pytest.mark.parametrize(
+    "feature",
+    [
+        "alff",
+        "falff",
+    ],
+)
+def test_ALFFMaps_get_output_type(feature: str) -> None:
+    """Test ALFFMaps get_output_type().
+
+    Parameters
+    ----------
+    feature : str
+        The parametrized feature name.
+
+    """
+    assert "vector" == ALFFMaps(
+        maps=MAPS,
+        using="junifer",
+    ).get_output_type(input_type="BOLD", output_feature=feature)
+
+
+def test_ALFFMaps(
+    caplog: pytest.LogCaptureFixture,
+    tmp_path: Path,
+    maps_datagrabber: PatternDataladDataGrabber,
+) -> None:
+    """Test ALFFMaps.
+
+    Parameters
+    ----------
+    caplog : pytest.LogCaptureFixture
+        The pytest.LogCaptureFixture object.
+    tmp_path : pathlib.Path
+        The path to the test directory.
+    maps_datagrabber : PatternDataladDataGrabber
+        The testing PatternDataladDataGrabber, as fixture.
+
+    """
+    # Update workdir to current test's tmp_path
+    WorkDirManager().workdir = tmp_path
+
+    with caplog.at_level(logging.DEBUG):
+        with maps_datagrabber as dg:
+            element = dg[("sub-01", "sub-001", "rest", "1")]
+            element_data = DefaultDataReader().fit_transform(element)
+
+            # Initialize marker
+            marker = ALFFMaps(
+                maps=MAPS,
+                using="junifer",
+            )
+            # Check correct output
+            for name in ["alff", "falff"]:
+                assert "vector" == marker.get_output_type(
+                    input_type="BOLD", output_feature=name
+                )
+
+            # Fit transform marker on data
+            output = marker.fit_transform(element_data)
+
+            assert "Creating cache" in caplog.text
+
+            # Get BOLD output
+            assert "BOLD" in output
+            for feature in output["BOLD"].keys():
+                output_bold = output["BOLD"][feature]
+                # Assert BOLD output keys
+                assert "data" in output_bold
+                assert "col_names" in output_bold
+
+                output_bold_data = output_bold["data"]
+                # Assert BOLD output data dimension
+                assert output_bold_data.ndim == 2
+                assert output_bold_data.shape == (1, 10)
+
+            # Reset log capture
+            caplog.clear()
+            # Initialize storage
+            storage = HDF5FeatureStorage(tmp_path / "falff_maps.hdf5")
+            # Fit transform marker on data with storage
+            marker.fit_transform(
+                input=element_data,
+                storage=storage,
+            )
+            # Check stored feature name
+            features = storage.list_features()
+            assert any(
+                x["name"] in ["BOLD_ALFFMaps_alff", "BOLD_ALFFMaps_falff"]
+                for x in features.values()
+            )
+            # Cache working correctly
+            assert "Creating cache" not in caplog.text
+
+
+@pytest.mark.skipif(
+    _check_afni() is False, reason="requires AFNI to be in PATH"
+)
+def test_ALFFMaps_comparison(
+    tmp_path: Path, maps_datagrabber: PatternDataladDataGrabber
+) -> None:
+    """Test ALFFMaps implementation comparison.
+
+    Parameters
+    ----------
+    tmp_path : pathlib.Path
+        The path to the test directory.
+    maps_datagrabber : PatternDataladDataGrabber
+        The testing PatternDataladDataGrabber, as fixture.
+
+    """
+    # Update workdir to current test's tmp_path
+    WorkDirManager().workdir = tmp_path
+
+    with maps_datagrabber as dg:
+        element = dg[("sub-01", "sub-001", "rest", "1")]
+        element_data = DefaultDataReader().fit_transform(element)
+
+        # Initialize marker
+        junifer_marker = ALFFMaps(
+            maps=MAPS,
+            using="junifer",
+        )
+        # Fit transform marker on data
+        junifer_output = junifer_marker.fit_transform(element_data)
+        # Get BOLD output
+        junifer_output_bold = junifer_output["BOLD"]
+
+        # Initialize marker
+        afni_marker = ALFFMaps(
+            maps=MAPS,
+            using="afni",
+        )
+        # Fit transform marker on data
+        afni_output = afni_marker.fit_transform(element_data)
+        # Get BOLD output
+        afni_output_bold = afni_output["BOLD"]
+
+        for feature in afni_output_bold.keys():
+            # Check for Pearson correlation coefficient
+            r, _ = sp.stats.pearsonr(
+                junifer_output_bold[feature]["data"][0],
+                afni_output_bold[feature]["data"][0],
+            )
+            assert r > 0.97

junifer/markers/functional_connectivity/__init__.pyi

@@ -1,13 +1,17 @@
 __all__ = [
+    "FunctionalConnectivityMaps",
     "FunctionalConnectivityParcels",
     "FunctionalConnectivitySpheres",
     "CrossParcellationFC",
+    "EdgeCentricFCMaps",
     "EdgeCentricFCParcels",
     "EdgeCentricFCSpheres",
 ]
 
+from .functional_connectivity_maps import FunctionalConnectivityMaps
 from .functional_connectivity_parcels import FunctionalConnectivityParcels
 from .functional_connectivity_spheres import FunctionalConnectivitySpheres
 from .crossparcellation_functional_connectivity import CrossParcellationFC
+from .edge_functional_connectivity_maps import EdgeCentricFCMaps
 from .edge_functional_connectivity_parcels import EdgeCentricFCParcels
 from .edge_functional_connectivity_spheres import EdgeCentricFCSpheres

junifer/markers/functional_connectivity/edge_functional_connectivity_maps.py

@@ -0,0 +1,115 @@
+"""Provide class for edge-centric functional connectivity using maps."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from typing import Any, Optional, Union
+
+from ...api.decorators import register_marker
+from ..maps_aggregation import MapsAggregation
+from ..utils import _ets
+from .functional_connectivity_base import FunctionalConnectivityBase
+
+
+__all__ = ["EdgeCentricFCMaps"]
+
+
+@register_marker
+class EdgeCentricFCMaps(FunctionalConnectivityBase):
+    """Class for edge-centric FC using maps.
+
+    Parameters
+    ----------
+    maps : str
+        The name of the map(s) to use.
+        See :func:`.list_data` for options.
+    conn_method : str, optional
+        The method to perform connectivity measure using.
+        See :class:`.JuniferConnectivityMeasure` for options
+        (default "correlation").
+    conn_method_params : dict, optional
+        Parameters to pass to :class:`.JuniferConnectivityMeasure`.
+        If None, ``{"empirical": True}`` will be used, which would mean
+        :class:`sklearn.covariance.EmpiricalCovariance` is used to compute
+        covariance. If usage of :class:`sklearn.covariance.LedoitWolf` is
+        desired, ``{"empirical": False}`` should be passed
+        (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, will use
+        ``BOLD_EdgeCentricFCParcels`` (default None).
+
+    References
+    ----------
+    .. [1] Jo et al. (2021)
+           Subject identification using edge-centric functional connectivity.
+           https://doi.org/10.1016/j.neuroimage.2021.118204
+
+    """
+
+    def __init__(
+        self,
+        maps: str,
+        conn_method: str = "correlation",
+        conn_method_params: Optional[dict] = None,
+        masks: Union[str, dict, list[Union[dict, str]], None] = None,
+        name: Optional[str] = None,
+    ) -> None:
+        self.maps = maps
+        super().__init__(
+            conn_method=conn_method,
+            conn_method_params=conn_method_params,
+            masks=masks,
+            name=name,
+        )
+
+    def aggregate(
+        self, input: dict[str, Any], extra_input: Optional[dict] = None
+    ) -> dict:
+        """Perform maps aggregation and ETS computation.
+
+        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. For
+            example, the functional connectivity markers can make use of the
+            confounds if available (default None).
+
+        Returns
+        -------
+        dict
+            The computed result as dictionary. This will be either returned
+            to the user or stored in the storage by calling the store method
+            with this as a parameter. The dictionary has the following keys:
+
+            * ``aggregation`` : dictionary with the following keys:
+
+                - ``data`` : ROI values as ``numpy.ndarray``
+                - ``col_names`` : ROI labels as list of str
+
+        """
+        # Perform aggregation
+        aggregation = MapsAggregation(
+            maps=self.maps,
+            masks=self.masks,
+            on="BOLD",
+        ).compute(input, extra_input=extra_input)
+        # Compute edgewise timeseries
+        ets, edge_names = _ets(
+            bold_ts=aggregation["aggregation"]["data"],
+            roi_names=aggregation["aggregation"]["col_names"],
+        )
+
+        return {
+            "aggregation": {
+                "data": ets,
+                "col_names": edge_names,
+            },
+        }

junifer/markers/functional_connectivity/functional_connectivity_maps.py

@@ -0,0 +1,95 @@
+"""Provide class for functional connectivity using maps."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from typing import Any, Optional, Union
+
+from ...api.decorators import register_marker
+from ..maps_aggregation import MapsAggregation
+from .functional_connectivity_base import FunctionalConnectivityBase
+
+
+__all__ = ["FunctionalConnectivityMaps"]
+
+
+@register_marker
+class FunctionalConnectivityMaps(FunctionalConnectivityBase):
+    """Class for functional connectivity using maps.
+
+    Parameters
+    ----------
+    maps : str
+        The name of the map(s) to use.
+        See :func:`.list_data` for options.
+    conn_method : str, optional
+        The method to perform connectivity measure using.
+        See :class:`.JuniferConnectivityMeasure` for options
+        (default "correlation").
+    conn_method_params : dict, optional
+        Parameters to pass to :class:`.JuniferConnectivityMeasure`.
+        If None, ``{"empirical": True}`` will be used, which would mean
+        :class:`sklearn.covariance.EmpiricalCovariance` is used to compute
+        covariance. If usage of :class:`sklearn.covariance.LedoitWolf` is
+        desired, ``{"empirical": False}`` should be passed
+        (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, will use
+        ``BOLD_FunctionalConnectivityMaps`` (default None).
+
+    """
+
+    def __init__(
+        self,
+        maps: str,
+        conn_method: str = "correlation",
+        conn_method_params: Optional[dict] = None,
+        masks: Union[str, dict, list[Union[dict, str]], None] = None,
+        name: Optional[str] = None,
+    ) -> None:
+        self.maps = maps
+        super().__init__(
+            conn_method=conn_method,
+            conn_method_params=conn_method_params,
+            masks=masks,
+            name=name,
+        )
+
+    def aggregate(
+        self, input: dict[str, Any], extra_input: Optional[dict] = None
+    ) -> dict:
+        """Perform maps aggregation.
+
+        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. For
+            example, the functional connectivity markers can make use of the
+            confounds if available (default None).
+
+        Returns
+        -------
+        dict
+            The computed result as dictionary. This will be either returned
+            to the user or stored in the storage by calling the store method
+            with this as a parameter. The dictionary has the following keys:
+
+            * ``aggregation`` : dictionary with the following keys:
+
+                - ``data`` : ROI values as ``numpy.ndarray``
+                - ``col_names`` : ROI labels as list of str
+
+        """
+        return MapsAggregation(
+            maps=self.maps,
+            masks=self.masks,
+            on="BOLD",
+        ).compute(input=input, extra_input=extra_input)