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

junifer/markers/functional_connectivity/tests/test_edge_functional_connectivity_maps.py

@@ -0,0 +1,74 @@
+"""Provide tests for edge-centric functional connectivity using maps."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from pathlib import Path
+
+import pytest
+
+from junifer.datagrabber import PatternDataladDataGrabber
+from junifer.datareader import DefaultDataReader
+from junifer.markers import EdgeCentricFCMaps
+from junifer.storage import HDF5FeatureStorage
+
+
+@pytest.mark.parametrize(
+    "conn_method_params",
+    [
+        {"empirical": False},
+        {"empirical": True},
+    ],
+)
+def test_EdgeCentricFCMaps(
+    tmp_path: Path,
+    maps_datagrabber: PatternDataladDataGrabber,
+    conn_method_params: dict[str, bool],
+) -> None:
+    """Test EdgeCentricFCMaps.
+
+    Parameters
+    ----------
+    tmp_path : pathlib.Path
+        The path to the test directory.
+    maps_datagrabber : PatternDataladDataGrabber
+        The testing PatternDataladDataGrabber, as fixture.
+    conn_method_params : dict
+        The parametrized parameters to connectivity measure method.
+
+    """
+    with maps_datagrabber as dg:
+        element = dg[("sub-01", "sub-001", "rest", "1")]
+        element_data = DefaultDataReader().fit_transform(element)
+        # Setup marker
+        marker = EdgeCentricFCMaps(
+            maps="Smith_rsn_10",
+            conn_method="correlation",
+            conn_method_params=conn_method_params,
+        )
+        # Check correct output
+        assert "matrix" == marker.get_output_type(
+            input_type="BOLD", output_feature="functional_connectivity"
+        )
+
+        # Fit-transform the data
+        edge_fc = marker.fit_transform(element_data)
+        edge_fc_bold = edge_fc["BOLD"]["functional_connectivity"]
+
+        # For 10 ROIs we should get (10 * (10 -1) / 2) edges in the ETS
+        n_edges = int(10 * (10 - 1) / 2)
+        assert "data" in edge_fc_bold
+        assert "row_names" in edge_fc_bold
+        assert "col_names" in edge_fc_bold
+        assert edge_fc_bold["data"].shape == (n_edges, n_edges)
+        assert len(set(edge_fc_bold["row_names"])) == n_edges
+        assert len(set(edge_fc_bold["col_names"])) == n_edges
+
+        # Store
+        storage = HDF5FeatureStorage(uri=tmp_path / "test_edge_fc_maps.hdf5")
+        marker.fit_transform(input=element_data, storage=storage)
+        features = storage.list_features()
+        assert any(
+            x["name"] == "BOLD_EdgeCentricFCMaps_functional_connectivity"
+            for x in features.values()
+        )

junifer/markers/functional_connectivity/tests/test_functional_connectivity_maps.py

@@ -0,0 +1,110 @@
+"""Provide tests for functional connectivity using maps."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+from nilearn.connectome import ConnectivityMeasure
+from nilearn.maskers import NiftiMapsMasker
+from numpy.testing import assert_array_almost_equal
+from sklearn.covariance import EmpiricalCovariance, LedoitWolf
+
+from junifer.data import MapsRegistry
+from junifer.datagrabber import PatternDataladDataGrabber
+from junifer.datareader import DefaultDataReader
+from junifer.markers import FunctionalConnectivityMaps
+from junifer.storage import HDF5FeatureStorage
+
+
+if TYPE_CHECKING:
+    from sklearn.base import BaseEstimator
+
+
+@pytest.mark.parametrize(
+    "conn_method_params, cov_estimator",
+    [
+        ({"empirical": False}, LedoitWolf(store_precision=False)),
+        ({"empirical": True}, EmpiricalCovariance(store_precision=False)),
+    ],
+)
+def test_FunctionalConnectivityMaps(
+    tmp_path: Path,
+    maps_datagrabber: PatternDataladDataGrabber,
+    conn_method_params: dict[str, bool],
+    cov_estimator: type["BaseEstimator"],
+) -> None:
+    """Test FunctionalConnectivityParcels.
+
+    Parameters
+    ----------
+    tmp_path : pathlib.Path
+        The path to the test directory.
+    maps_datagrabber : PatternDataladDataGrabber
+        The testing PatternDataladDataGrabber, as fixture.
+    conn_method_params : dict
+        The parametrized parameters to connectivity measure method.
+    cov_estimator : estimator object
+        The parametrized covariance estimator.
+
+    """
+    with maps_datagrabber as dg:
+        element = dg[("sub-01", "sub-001", "rest", "1")]
+        element_data = DefaultDataReader().fit_transform(element)
+        # Setup marker
+        marker = FunctionalConnectivityMaps(
+            maps="Smith_rsn_10",
+            conn_method="correlation",
+            conn_method_params=conn_method_params,
+        )
+        # Check correct output
+        assert "matrix" == marker.get_output_type(
+            input_type="BOLD", output_feature="functional_connectivity"
+        )
+
+        # Fit-transform the data
+        fc = marker.fit_transform(element_data)
+        fc_bold = fc["BOLD"]["functional_connectivity"]
+
+        assert "data" in fc_bold
+        assert "row_names" in fc_bold
+        assert "col_names" in fc_bold
+        assert fc_bold["data"].shape == (10, 10)
+        assert len(set(fc_bold["row_names"])) == 10
+        assert len(set(fc_bold["col_names"])) == 10
+
+        # Compare with nilearn
+        # Load testing maps for the target data
+        maps, _ = MapsRegistry().get(
+            maps="Smith_rsn_10",
+            target_data=element_data["BOLD"],
+        )
+        # Extract timeseries
+        masker = NiftiMapsMasker(maps_img=maps, standardize=False)
+        extracted_timeseries = masker.fit_transform(
+            element_data["BOLD"]["data"]
+        )
+        # Compute the connectivity measure
+        connectivity_measure = ConnectivityMeasure(
+            cov_estimator=cov_estimator,
+            kind="correlation",  # type: ignore
+        ).fit_transform([extracted_timeseries])[0]
+
+        # Check that FC are almost equal
+        assert_array_almost_equal(
+            connectivity_measure, fc_bold["data"], decimal=3
+        )
+
+        # Store
+        storage = HDF5FeatureStorage(
+            uri=tmp_path / "test_fc_maps.hdf5",
+        )
+        marker.fit_transform(input=element_data, storage=storage)
+        features = storage.list_features()
+        assert any(
+            x["name"]
+            == "BOLD_FunctionalConnectivityMaps_functional_connectivity"
+            for x in features.values()
+        )

junifer/markers/maps_aggregation.py

@@ -0,0 +1,201 @@
+"""Provide class for maps aggregation."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from typing import Any, ClassVar, Optional, Union
+
+from nilearn.maskers import NiftiMapsMasker
+
+from ..api.decorators import register_marker
+from ..data import get_data
+from ..stats import get_aggfunc_by_name
+from ..typing import Dependencies, MarkerInOutMappings
+from ..utils import logger, raise_error, warn_with_log
+from .base import BaseMarker
+
+
+__all__ = ["MapsAggregation"]
+
+
+@register_marker
+class MapsAggregation(BaseMarker):
+    """Class for maps aggregation.
+
+    Parameters
+    ----------
+    maps : str
+        The name of the map(s) to use.
+        See :func:`.list_data` for options.
+    time_method : str, optional
+        The method to use to aggregate the time series over the time points,
+        after aggregation (only applicable to BOLD data). If None,
+        it will not operate on the time dimension (default None).
+    time_method_params : dict, optional
+        The parameters to pass to the time aggregation method (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).
+    on : {"T1w", "T2w", "BOLD", "VBM_GM", "VBM_WM", "VBM_CSF", "fALFF", \
+        "GCOR", "LCOR"} or list of the options, optional
+        The data types to apply the marker to. If None, will work on all
+        available data (default None).
+    name : str, optional
+        The name of the marker. If None, will use the class name (default
+        None).
+
+    Raises
+    ------
+    ValueError
+        If ``time_method`` is specified for non-BOLD data or if
+        ``time_method_params`` is not None when ``time_method`` is None.
+
+    """
+
+    _DEPENDENCIES: ClassVar[Dependencies] = {"nilearn", "numpy"}
+
+    _MARKER_INOUT_MAPPINGS: ClassVar[MarkerInOutMappings] = {
+        "T1w": {
+            "aggregation": "vector",
+        },
+        "T2w": {
+            "aggregation": "vector",
+        },
+        "BOLD": {
+            "aggregation": "timeseries",
+        },
+        "VBM_GM": {
+            "aggregation": "vector",
+        },
+        "VBM_WM": {
+            "aggregation": "vector",
+        },
+        "VBM_CSF": {
+            "aggregation": "vector",
+        },
+        "fALFF": {
+            "aggregation": "vector",
+        },
+        "GCOR": {
+            "aggregation": "vector",
+        },
+        "LCOR": {
+            "aggregation": "vector",
+        },
+    }
+
+    def __init__(
+        self,
+        maps: str,
+        time_method: Optional[str] = None,
+        time_method_params: Optional[dict[str, Any]] = None,
+        masks: Union[str, dict, list[Union[dict, str]], None] = None,
+        on: Union[list[str], str, None] = None,
+        name: Optional[str] = None,
+    ) -> None:
+        self.maps = maps
+        self.masks = masks
+        super().__init__(on=on, name=name)
+
+        # Verify after super init so self._on is set
+        if "BOLD" not in self._on and time_method is not None:
+            raise_error(
+                "`time_method` can only be used with BOLD data. "
+                "Please remove `time_method` parameter."
+            )
+        if time_method is None and time_method_params is not None:
+            raise_error(
+                "`time_method_params` can only be used with `time_method`. "
+                "Please remove `time_method_params` parameter."
+            )
+        self.time_method = time_method
+        self.time_method_params = time_method_params or {}
+
+    def compute(
+        self, input: dict[str, Any], extra_input: Optional[dict] = None
+    ) -> dict:
+        """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. 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
+
+        Warns
+        -----
+        RuntimeWarning
+            If time aggregation is required but only time point is available.
+
+        """
+        t_input_img = input["data"]
+        logger.debug("Maps aggregation")
+
+        # Get maps tailored to target image
+        maps_img, labels = get_data(
+            kind="maps",
+            names=self.maps,
+            target_data=input,
+            extra_input=extra_input,
+        )
+
+        # Load mask
+        mask_img = None
+        if self.masks is not None:
+            logger.debug(f"Masking with {self.masks}")
+            # Get tailored mask
+            mask_img = get_data(
+                kind="mask",
+                names=self.masks,
+                target_data=input,
+                extra_input=extra_input,
+            )
+
+        # Initialize masker
+        logger.debug("Masking")
+        masker = NiftiMapsMasker(
+            maps_img=maps_img,
+            mask_img=mask_img,
+            target_affine=t_input_img.affine,
+        )
+        # Mask the input data and extract data
+        data = masker.fit_transform(t_input_img)
+
+        # Apply time dimension aggregation if required
+        if self.time_method is not None:
+            if data.shape[0] > 1:
+                logger.debug("Aggregating time dimension")
+                time_agg_func = get_aggfunc_by_name(
+                    self.time_method, func_params=self.time_method_params
+                )
+                data = time_agg_func(data, axis=0)
+            else:
+                warn_with_log(
+                    "No time dimension to aggregate as only one time point is "
+                    "available."
+                )
+        # Format the output
+        return {
+            "aggregation": {
+                "data": data,
+                "col_names": labels,
+            },
+        }

junifer/markers/reho/__init__.pyi

@@ -1,4 +1,5 @@
-__all__ = ["ReHoParcels", "ReHoSpheres"]
+__all__ = ["ReHoMaps", "ReHoParcels", "ReHoSpheres"]
 
+from .reho_maps import ReHoMaps
 from .reho_parcels import ReHoParcels
 from .reho_spheres import ReHoSpheres

junifer/markers/reho/reho_maps.py

@@ -0,0 +1,161 @@
+"""Provide class for regional homogeneity (ReHo) on maps."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from typing import Any, Optional, Union
+
+import numpy as np
+
+from ...api.decorators import register_marker
+from ...utils import logger
+from ..maps_aggregation import MapsAggregation
+from .reho_base import ReHoBase
+
+
+__all__ = ["ReHoMaps"]
+
+
+@register_marker
+class ReHoMaps(ReHoBase):
+    """Class for regional homogeneity 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 ReHo:
+
+        * "junifer" : Use ``junifer``'s own ReHo implementation
+        * "afni" : Use AFNI's ``3dReHo``
+
+    reho_params : dict, optional
+        Extra parameters for computing ReHo map as a dictionary (default None).
+        If ``using="afni"``, then the valid keys are:
+
+        * ``nneigh`` : {7, 19, 27}, optional (default 27)
+            Number of voxels in the neighbourhood, inclusive. Can be:
+
+            - 7 : for facewise neighbours only
+            - 19 : for face- and edge-wise neighbours
+            - 27 : for face-, edge-, and node-wise neighbors
+
+        * ``neigh_rad`` : positive float, optional
+            The radius of a desired neighbourhood (default None).
+        * ``neigh_x`` : positive float, optional
+            The semi-radius for x-axis of ellipsoidal volumes (default None).
+        * ``neigh_y`` : positive float, optional
+            The semi-radius for y-axis of ellipsoidal volumes (default None).
+        * ``neigh_z`` : positive float, optional
+            The semi-radius for z-axis of ellipsoidal volumes (default None).
+        * ``box_rad`` : positive int, optional
+            The number of voxels outward in a given cardinal direction for a
+            cubic box centered on a given voxel (default None).
+        * ``box_x`` : positive int, optional
+            The number of voxels for +/- x-axis of cuboidal volumes
+            (default None).
+        * ``box_y`` : positive int, optional
+            The number of voxels for +/- y-axis of cuboidal volumes
+            (default None).
+        * ``box_z`` : positive int, optional
+            The number of voxels for +/- z-axis of cuboidal volumes
+            (default None).
+
+        else if ``using="junifer"``, then the valid keys are:
+
+        * ``nneigh`` : {7, 19, 27, 125}, optional (default 27)
+            Number of voxels in the neighbourhood, inclusive. Can be:
+
+            * 7 : for facewise neighbours only
+            * 19 : for face- and edge-wise neighbours
+            * 27 : for face-, edge-, and node-wise neighbors
+            * 125 : for 5x5 cuboidal volume
+
+    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).
+
+    """
+
+    def __init__(
+        self,
+        maps: str,
+        using: str,
+        reho_params: Optional[dict] = 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__(using=using, name=name)
+        self.maps = maps
+        self.reho_params = reho_params
+        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:
+
+            * ``reho`` : dictionary with the following keys:
+
+              - ``data`` : ROI values as ``numpy.ndarray``
+              - ``col_names`` : ROI labels as list of str
+
+        """
+        logger.info("Calculating ReHo for maps")
+
+        # Compute voxelwise reho
+        # If the input data space is "native", then reho_file_path points to
+        # the input data path as it might be required for parcellation
+        # transformation to native space.
+        if self.reho_params is not None:
+            reho_map, reho_file_path = self._compute(
+                input_data=input, **self.reho_params
+            )
+        else:
+            reho_map, reho_file_path = self._compute(input_data=input)
+
+        # Perform aggregation on reho map
+        aggregation_input = dict(input.items())
+        aggregation_input["data"] = reho_map
+        aggregation_input["path"] = reho_file_path
+        maps_aggregation = MapsAggregation(
+            maps=self.maps,
+            masks=self.masks,
+            on="BOLD",
+        ).compute(
+            input=aggregation_input,
+            extra_input=extra_input,
+        )
+
+        return {
+            "reho": {
+                # Only use the first row and expand row dimension
+                "data": maps_aggregation["aggregation"]["data"][0][
+                    np.newaxis, :
+                ],
+                "col_names": maps_aggregation["aggregation"]["col_names"],
+            }
+        }

junifer/markers/reho/tests/test_reho_maps.py

@@ -0,0 +1,135 @@
+"""Provide tests for ReHoMaps."""
+
+# 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 ReHoMaps
+from junifer.pipeline import WorkDirManager
+from junifer.pipeline.utils import _check_afni
+from junifer.storage import HDF5FeatureStorage
+
+
+def test_ReHoMaps(
+    caplog: pytest.LogCaptureFixture,
+    tmp_path: Path,
+    maps_datagrabber: PatternDataladDataGrabber,
+) -> None:
+    """Test ReHoMaps.
+
+    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 = ReHoMaps(
+                maps="Smith_rsn_10",
+                using="junifer",
+            )
+            # Check correct output
+            assert "vector" == marker.get_output_type(
+                input_type="BOLD", output_feature="reho"
+            )
+
+            # Fit transform marker on data
+            output = marker.fit_transform(element_data)
+
+            assert "Creating cache" in caplog.text
+
+            # Get BOLD output
+            assert "BOLD" in output
+            output_bold = output["BOLD"]["reho"]
+            # 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 BOLD output data is normalized
+            assert (output_bold_data > 0).all() and (
+                output_bold_data < 1
+            ).all()
+
+            # Reset log capture
+            caplog.clear()
+            # Initialize storage
+            storage = HDF5FeatureStorage(tmp_path / "reho_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"] == "BOLD_ReHoMaps_reho" 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_ReHoMaps_comparison(
+    tmp_path: Path, maps_datagrabber: PatternDataladDataGrabber
+) -> None:
+    """Test ReHoMaps 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 = ReHoMaps(maps="Smith_rsn_10", using="junifer")
+        # Fit transform marker on data
+        junifer_output = junifer_marker.fit_transform(element_data)
+        # Get BOLD output
+        junifer_output_bold = junifer_output["BOLD"]["reho"]
+
+        # Initialize marker
+        afni_marker = ReHoMaps(maps="Smith_rsn_10", using="afni")
+        # Fit transform marker on data
+        afni_output = afni_marker.fit_transform(element_data)
+        # Get BOLD output
+        afni_output_bold = afni_output["BOLD"]["reho"]
+
+        # Check for Pearson correlation coefficient
+        r, _ = sp.stats.pearsonr(
+            junifer_output_bold["data"].flatten(),
+            afni_output_bold["data"].flatten(),
+        )
+        assert r >= 0.2  # this is very bad, but they differ...

junifer/markers/temporal_snr/__init__.pyi

@@ -1,4 +1,5 @@
-__all__ = ["TemporalSNRParcels", "TemporalSNRSpheres"]
+__all__ = ["TemporalSNRMaps", "TemporalSNRParcels", "TemporalSNRSpheres"]
 
+from .temporal_snr_maps import TemporalSNRMaps
 from .temporal_snr_parcels import TemporalSNRParcels
 from .temporal_snr_spheres import TemporalSNRSpheres