junifer 0.0.7.dev153__tar.gz → 0.0.7.dev169__tar.gz

{junifer-0.0.7.dev153 → junifer-0.0.7.dev169}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: junifer
-Version: 0.0.7.dev153
+Version: 0.0.7.dev169
 Summary: JUelich NeuroImaging FEature extractoR
 Author-email: Fede Raimondo <f.raimondo@fz-juelich.de>, Synchon Mandal <s.mandal@fz-juelich.de>
 Maintainer-email: Fede Raimondo <f.raimondo@fz-juelich.de>, Synchon Mandal <s.mandal@fz-juelich.de>

{junifer-0.0.7.dev153 → junifer-0.0.7.dev169}/docs/builtin.rst

@@ -209,22 +209,30 @@ Available
      - Apply parcellation and perform aggregation function
      - Done
      - 0.0.1
-   * - :class:`.FunctionalConnectivityParcels`
-     - Compute functional connectivity over parcellation
+   * - :class:`.SphereAggregation`
+     - Spherical aggregation using mean
      - Done
      - 0.0.1
-   * - :class:`.CrossParcellationFC`
-     - Compute functional connectivity across two parcellations
+   * - :class:`.MapsAggregation`
+     - Apply maps (probabilistic atlas) and extract mean time series per region
      - Done
-     - 0.0.1
-   * - :class:`.SphereAggregation`
-     - Spherical aggregation using mean
+     - 0.0.7
+   * - :class:`.FunctionalConnectivityParcels`
+     - Compute functional connectivity over parcellation
      - Done
      - 0.0.1
    * - :class:`.FunctionalConnectivitySpheres`
      - Compute functional connectivity over spheres placed on coordinates
      - Done
      - 0.0.1
+   * - :class:`.FunctionalConnectivityMaps`
+     - Compute functional connectivity over maps (probabilistic atlas)
+     - Done
+     - 0.0.7
+   * - :class:`.CrossParcellationFC`
+     - Compute functional connectivity across two parcellations
+     - Done
+     - 0.0.1
    * - :class:`.RSSETSMarker`
      - Compute root sum of squares of edgewise timeseries
      - Done
@@ -237,6 +245,10 @@ Available
      - Calculate regional homogeneity over spheres placed on coordinates
      - Done
      - 0.0.1
+   * - :class:`.ReHoMaps`
+     - Calculate regional homogeneity over maps (probabilistic atlas)
+     - Done
+     - 0.0.7
    * - :class:`.ALFFParcels`
      - Calculate (f)ALFF and aggregate using parcellations
      - Done
@@ -245,6 +257,10 @@ Available
      - Calculate (f)ALFF and aggregate using spheres placed on coordinates
      - Done
      - 0.0.1
+   * - :class:`.ALFFMaps`
+     - Calculate (f)ALFF and aggregate using maps (probabilistic atlas)
+     - Done
+     - 0.0.7
    * - :class:`.EdgeCentricFCParcels`
      - | Calculate edge-centric functional connectivity over parcellation, as
        | found in
@@ -257,6 +273,12 @@ Available
        | `Jo et al. (2021) <https://doi.org/10.1016/j.neuroimage.2021.118204>`_
      - Done
      - 0.0.2
+   * - :class:`.EdgeCentricFCMaps`
+     - | Calculate edge-centric functional connectivity over maps (probabilistic atlas),
+       | as found in
+       | `Jo et al. (2021) <https://doi.org/10.1016/j.neuroimage.2021.118204>`_
+     - Done
+     - 0.0.7
    * - :class:`.TemporalSNRParcels`
      - Calculate temporal signal-to-noise ratio using parcellations
      - Done
@@ -266,6 +288,10 @@ Available
        | coordinates
      - Done
      - 0.0.2
+   * - :class:`.TemporalSNRMaps`
+     - Calculate temporal signal-to-noise ratio using maps (probabilistic atlas)
+     - Done
+     - 0.0.7
    * - :class:`.HurstExponent`
      - | Calculate Hurst exponent of a time series as found in
        | `Peng et al. (1995) <https://doi.org/10.1063/1.166141>`_

junifer-0.0.7.dev169/docs/changes/newsfragments/460.feature

@@ -0,0 +1 @@
+Introduce :class:`.MapsAggregation`, :class:`.FunctionalConnectivityMaps`, :class:`.EdgeCentricFCMaps`, :class:`.ReHoMaps`, :class:`.ALFFMaps` and :class:`.TemporalSNRMaps` by `Synchon Mandal`_

{junifer-0.0.7.dev153 → junifer-0.0.7.dev169}/docs/extending/maps.rst

@@ -116,7 +116,7 @@ file, we can save the above code in a Python file, say
 Afterwards continue configuring the rest of the pipeline in this YAML file, and
 you will be able to use this maps using the name you gave the
 maps when registering it. For example, we can add a
-``MapsAggregation`` Marker to demonstrate how this can be done:
+:class:`.MapsAggregation` Marker to demonstrate how this can be done:
 
 .. code-block:: yaml
 
@@ -124,7 +124,6 @@ maps when registering it. For example, we can add a
     - name: CustomMaps_mean
       kind: MapsAggregation
       maps: my_custom_maps
-      method: mean
 
 Now, you can simply use this YAML file to run your pipeline.
 

{junifer-0.0.7.dev153 → junifer-0.0.7.dev169}/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.dev169'
+__version_tuple__ = version_tuple = (0, 0, 7, 'dev169')
 
-__commit_id__ = commit_id = 'g42a09b3a7'
+__commit_id__ = commit_id = 'g130238f84'

junifer-0.0.7.dev169/junifer/conftest.py

@@ -0,0 +1,57 @@
+"""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
+
+
+@pytest.fixture(autouse=True)
+def reset_singletons() -> None:
+    """Reset all singletons."""
+    to_clean = ["WorkDirManager"]
+    to_remove = [
+        v for k, v in Singleton.instances.items() if k.__name__ in to_clean
+    ]
+    Singleton.instances = {
+        k: v
+        for k, v in Singleton.instances.items()
+        if k.__name__ not in to_clean
+    }
+    # 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-0.0.7.dev153 → junifer-0.0.7.dev169}/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-0.0.7.dev169/junifer/markers/falff/__init__.pyi

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

junifer-0.0.7.dev169/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-0.0.7.dev169/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-0.0.7.dev153 → junifer-0.0.7.dev169}/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-0.0.7.dev169/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,
+            },
+        }