junifer 0.0.7.dev332__py3-none-any.whl → 0.0.8__py3-none-any.whl

junifer/markers/reho/reho_parcels.py

@@ -3,12 +3,15 @@
 # Authors: Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
-from typing import Any, Optional, Union
+from typing import Annotated, Any
 
 import numpy as np
+from pydantic import BeforeValidator
 
 from ...api.decorators import register_marker
-from ...utils import logger
+from ...datagrabber import DataType
+from ...utils import ensure_list
+from ..base import logger
 from ..parcel_aggregation import ParcelAggregation
 from .reho_base import ReHoBase
 
@@ -25,15 +28,10 @@ class ReHoParcels(ReHoBase):
     parcellation : str or list of str
         The name(s) of the parcellation(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
+    using : :enum:`.ReHoImpl`
+    reho_params : dict or None, optional
         Extra parameters for computing ReHo map as a dictionary (default None).
-        If ``using="afni"``, then the valid keys are:
+        If ``using=ReHoImpl.afni``, then the valid keys are:
 
         * ``nneigh`` : {7, 19, 27}, optional (default 27)
             Number of voxels in the neighbourhood, inclusive. Can be:
@@ -63,7 +61,7 @@ class ReHoParcels(ReHoBase):
             The number of voxels for +/- z-axis of cuboidal volumes
             (default None).
 
-        else if ``using="junifer"``, then the valid keys are:
+        else if ``using=ReHoImpl.junifer``, then the valid keys are:
 
         * ``nneigh`` : {7, 19, 27, 125}, optional (default 27)
             Number of voxels in the neighbourhood, inclusive. Can be:
@@ -74,43 +72,28 @@ class ReHoParcels(ReHoBase):
             * 125 : for 5x5 cuboidal volume
 
     agg_method : str, optional
-        The method to perform aggregation using. Check valid options in
-        :func:`.get_aggfunc_by_name` (default "mean").
-    agg_method_params : dict, optional
-        Parameters to pass to the aggregation function. Check valid options in
-        :func:`.get_aggfunc_by_name` (default None).
-    masks : str, dict or list of dict or str, optional
+        The aggregation function to use.
+        See :func:`.get_aggfunc_by_name` for options
+        (default "mean").
+    agg_method_params : dict or None, optional
+        The parameters to pass to the aggregation function.
+        See :func:`.get_aggfunc_by_name` for options (default None).
+    masks : str, dict, list of them or None, 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).
+    name : str or None, optional
+        The name of the marker.
+        If None, it will use the class name (default None).
 
     """
 
-    def __init__(
-        self,
-        parcellation: Union[str, list[str]],
-        using: str,
-        reho_params: Optional[dict] = None,
-        agg_method: str = "mean",
-        agg_method_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.parcellation = parcellation
-        self.reho_params = reho_params
-        self.agg_method = agg_method
-        self.agg_method_params = agg_method_params
-        self.masks = masks
+    parcellation: Annotated[str | list[str], BeforeValidator(ensure_list)]
 
     def compute(
         self,
         input: dict[str, Any],
-        extra_input: Optional[dict[str, Any]] = None,
+        extra_input: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         """Compute.
 
@@ -142,10 +125,12 @@ class ReHoParcels(ReHoBase):
         # transformation to native space.
         if self.reho_params is not None:
             reho_map, reho_file_path = self._compute(
-                input_data=input, **self.reho_params
+                input_data=input, extra_input=extra_input, **self.reho_params
             )
         else:
-            reho_map, reho_file_path = self._compute(input_data=input)
+            reho_map, reho_file_path = self._compute(
+                input_data=input, extra_input=extra_input
+            )
 
         # Perform aggregation on reho map
         aggregation_input = dict(input.items())
@@ -156,7 +141,7 @@ class ReHoParcels(ReHoBase):
             method=self.agg_method,
             method_params=self.agg_method_params,
             masks=self.masks,
-            on="BOLD",
+            on=DataType.BOLD,
         ).compute(
             input=aggregation_input,
             extra_input=extra_input,

junifer/markers/reho/reho_spheres.py

@@ -3,12 +3,14 @@
 # Authors: Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
-from typing import Any, Optional, Union
+from typing import Any, Literal
 
 import numpy as np
+from pydantic import PositiveFloat
 
 from ...api.decorators import register_marker
-from ...utils import logger
+from ...datagrabber import DataType
+from ..base import logger
 from ..sphere_aggregation import SphereAggregation
 from .reho_base import ReHoBase
 
@@ -25,26 +27,18 @@ class ReHoSpheres(ReHoBase):
     coords : str
         The name of the coordinates list 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``
-
-    radius : float, optional
-        The radius of the sphere in millimeters. If None, the signal will be
-        extracted from a single voxel. See
-        :class:`nilearn.maskers.NiftiSpheresMasker` for more information
+    using : :enum:`.ReHoImpl`
+    radius : ``zero`` or positive float or None, optional
+        The radius of the sphere in millimetres.
+        If None, the signal will be extracted from a single voxel.
+        See :class:`.JuniferNiftiSpheresMasker` for more information
         (default None).
     allow_overlap : bool, optional
-        Whether to allow overlapping spheres. If False, an error is raised if
-        the spheres overlap (default is False).
-    use_afni : bool, optional
-        Whether to use AFNI for computing. If None, will use AFNI only
-        if available (default None).
-    reho_params : dict, optional
+        Whether to allow overlapping spheres.
+        If False, an error is raised if the spheres overlap (default False).
+    reho_params : dict or None, optional
         Extra parameters for computing ReHo map as a dictionary (default None).
-        If ``using="afni"``, then the valid keys are:
+        If ``using=ReHoImpl.afni``, then the valid keys are:
 
         * ``nneigh`` : {7, 19, 27}, optional (default 27)
             Number of voxels in the neighbourhood, inclusive. Can be:
@@ -74,7 +68,7 @@ class ReHoSpheres(ReHoBase):
             The number of voxels for +/- z-axis of cuboidal volumes
             (default None).
 
-        else if ``using="junifer"``, then the valid keys are:
+        else if ``using=ReHoImpl.junifer``, then the valid keys are:
 
         * ``nneigh`` : {7, 19, 27, 125}, optional (default 27)
             Number of voxels in the neighbourhood, inclusive. Can be:
@@ -85,47 +79,30 @@ class ReHoSpheres(ReHoBase):
             * 125 : for 5x5 cuboidal volume
 
     agg_method : str, optional
-        The aggregation method to use.
-        See :func:`.get_aggfunc_by_name` for more information
-        (default None).
-    agg_method_params : dict, optional
-        The parameters to pass to the aggregation method (default None).
-    masks : str, dict or list of dict or str, optional
+        The aggregation function to use.
+        See :func:`.get_aggfunc_by_name` for options
+        (default "mean").
+    agg_method_params : dict or None, optional
+        The parameters to pass to the aggregation function.
+        See :func:`.get_aggfunc_by_name` for options (default None).
+    masks : str, dict, list of them or None, 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).
+    name : str or None, optional
+        The name of the marker.
+        If None, it will use the class name (default None).
 
     """
 
-    def __init__(
-        self,
-        coords: str,
-        using: str,
-        radius: Optional[float] = None,
-        allow_overlap: bool = False,
-        reho_params: Optional[dict] = None,
-        agg_method: str = "mean",
-        agg_method_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.coords = coords
-        self.radius = radius
-        self.allow_overlap = allow_overlap
-        self.reho_params = reho_params
-        self.agg_method = agg_method
-        self.agg_method_params = agg_method_params
-        self.masks = masks
+    coords: str
+    radius: Literal[0] | PositiveFloat | None = None
+    allow_overlap: bool = False
 
     def compute(
         self,
         input: dict[str, Any],
-        extra_input: Optional[dict[str, Any]] = None,
+        extra_input: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         """Compute.
 
@@ -157,10 +134,12 @@ class ReHoSpheres(ReHoBase):
         # transformation to native space.
         if self.reho_params is not None:
             reho_map, reho_file_path = self._compute(
-                input_data=input, **self.reho_params
+                input_data=input, extra_input=extra_input, **self.reho_params
             )
         else:
-            reho_map, reho_file_path = self._compute(input_data=input)
+            reho_map, reho_file_path = self._compute(
+                input_data=input, extra_input=extra_input
+            )
 
         # Perform aggregation on reho map
         aggregation_input = dict(input.items())
@@ -173,7 +152,7 @@ class ReHoSpheres(ReHoBase):
             method=self.agg_method,
             method_params=self.agg_method_params,
             masks=self.masks,
-            on="BOLD",
+            on=DataType.BOLD,
         ).compute(input=aggregation_input, extra_input=extra_input)
 
         return {

junifer/markers/reho/tests/test_junifer_reho.py

@@ -0,0 +1,178 @@
+"""Provide tests for ReHo computation using junifer."""
+
+# Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
+# License: AGPL
+
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+import pytest
+import scipy as sp
+from numpy.testing import assert_allclose, assert_array_equal
+
+from junifer.markers.reho._afni_reho import AFNIReHo
+from junifer.markers.reho._junifer_reho import JuniferReHo, _rank_with_ties
+from junifer.pipeline import WorkDirManager
+from junifer.pipeline.utils import _check_afni
+
+
+def _tied_rank_corrections(ranks: np.ndarray) -> np.ndarray:
+    """Compute tied rank corrections one time series at a time."""
+    out = np.zeros(ranks.shape[:-1])
+    for idx in np.ndindex(ranks.shape[:-1]):
+        _, tie_count = np.unique(ranks[idx], return_counts=True)
+        out[idx] = np.sum(tie_count**3 - tie_count)
+    return out
+
+
+@pytest.mark.parametrize(
+    "shape, scale",
+    [
+        ((4, 3, 2, 50), 3),  # many ties
+        ((3, 3, 3, 30), 100),  # few ties
+        ((2, 2, 2, 10), 0),  # all values tied
+    ],
+)
+def test_rank_with_ties(shape: tuple[int, ...], scale: float) -> None:
+    """Test ranking with ties against scipy.
+
+    Parameters
+    ----------
+    shape : tuple of int
+        The shape of the data.
+    scale : float
+        The scale of the data before rounding.
+
+    """
+    data = np.round(np.random.default_rng(0).normal(size=shape) * scale)
+    ranks, tied_rank_corrections = _rank_with_ties(data)
+    expected_ranks = sp.stats.rankdata(data, axis=-1)
+    assert_array_equal(ranks, expected_ranks)
+    assert_array_equal(
+        tied_rank_corrections, _tied_rank_corrections(expected_ranks)
+    )
+
+
+def test_rank_with_ties_nan() -> None:
+    """Test NaN propagates to the whole time series."""
+    data = np.array([[1.0, np.nan, 2.0], [1.0, 3.0, 2.0]])
+    ranks, tied_rank_corrections = _rank_with_ties(data)
+    assert np.isnan(ranks[0]).all()
+    assert np.isnan(tied_rank_corrections[0])
+    assert_array_equal(ranks[1], [1, 3, 2])
+    assert tied_rank_corrections[1] == 0
+
+
+def _save(data: np.ndarray, path: Path) -> Path:
+    """Save data as NIfTI."""
+    nib.save(nib.Nifti1Image(data, np.eye(4)), path)
+    return path
+
+
+def test_JuniferReHo_nan(tmp_path: Path) -> None:
+    """Test NaN time series do not give valid ReHo values.
+
+    Parameters
+    ----------
+    tmp_path : pathlib.Path
+        The path to the test directory.
+
+    """
+    WorkDirManager().workdir = tmp_path
+    data = np.random.default_rng(0).normal(size=(7, 7, 7, 20))
+    data[3, 3, 3, 5] = np.nan
+    bold_path = _save(data.astype(np.float32), tmp_path / "bold_nan.nii")
+    mask_path = _save(np.ones((7, 7, 7), dtype=np.uint8), tmp_path / "m.nii")
+
+    # With a mask including the NaN voxel, every neighbourhood with it is NaN
+    reho = JuniferReHo().compute(bold_path, mask_path=mask_path)[0]
+    reho = reho.get_fdata()
+    assert np.isnan(reho[2:5, 2:5, 2:5]).all()
+    reho[2:5, 2:5, 2:5] = 0
+    assert np.isfinite(reho).all()
+
+    # Without mask, the NaN voxel is excluded as AFNI's 3dReHo does
+    reho = JuniferReHo().compute(bold_path)[0].get_fdata()
+    assert np.isfinite(reho).all()
+    assert reho[3, 3, 3] == 0
+
+
+def test_JuniferReHo_mask(tmp_path: Path) -> None:
+    """Test ReHo is restricted to the mask.
+
+    Parameters
+    ----------
+    tmp_path : pathlib.Path
+        The path to the test directory.
+
+    """
+    WorkDirManager().workdir = tmp_path
+    data = np.random.default_rng(0).normal(size=(7, 7, 7, 20))
+    bold_path = _save(data.astype(np.float32), tmp_path / "bold.nii")
+    mask = np.ones((7, 7, 7), dtype=np.uint8)
+    mask[:3] = 0
+    mask_path = _save(mask, tmp_path / "mask.nii")
+
+    masked = JuniferReHo().compute(bold_path, mask_path=mask_path)[0]
+    masked = masked.get_fdata()
+    unmasked = JuniferReHo().compute(bold_path)[0].get_fdata()
+    # Outside the mask is 0
+    assert (masked[:3] == 0).all()
+    # Next to the mask boundary, neighbours outside the mask are excluded
+    assert not np.allclose(masked[3, 1:-1, 1:-1], unmasked[3, 1:-1, 1:-1])
+    # Far from the mask boundary, nothing changes
+    assert_array_equal(masked[4:-1, 1:-1, 1:-1], unmasked[4:-1, 1:-1, 1:-1])
+
+
+@pytest.mark.external
+@pytest.mark.skipif(
+    _check_afni() is False, reason="requires AFNI to be in PATH"
+)
+@pytest.mark.parametrize("nneigh", [7, 19, 27])
+@pytest.mark.parametrize("use_mask", [False, True])
+def test_JuniferReHo_vs_AFNI(
+    tmp_path: Path, nneigh: int, use_mask: bool
+) -> None:
+    """Test junifer and AFNI give the same ReHo map.
+
+    The data covers the edges of the volume, fully tied neighbourhoods (the
+    denominator of KCC is 0), voxels with all-zero time series and ties.
+
+    Parameters
+    ----------
+    tmp_path : pathlib.Path
+        The path to the test directory.
+    nneigh : int
+        The number of voxels in the neighbourhood.
+    use_mask : bool
+        Whether to use a mask.
+
+    """
+    WorkDirManager().workdir = tmp_path
+    data = np.round(
+        np.random.default_rng(0).normal(size=(9, 8, 7, 25)) * 3
+    ).astype(np.float32)
+    # Constant time series: fully tied neighbourhoods
+    data[:4, :4, :4] = 5
+    # All-zero time series: outside AFNI's implicit mask
+    data[6:, 5:, 4:] = 0
+    bold_path = _save(data, tmp_path / "bold.nii")
+    mask_path = None
+    if use_mask:
+        mask = np.ones(data.shape[:3], dtype=np.uint8)
+        mask[:, :, 0] = 0
+        mask[4, 4, 3] = 0
+        mask_path = _save(mask, tmp_path / "mask.nii")
+
+    junifer_reho = JuniferReHo().compute(
+        bold_path, nneigh=nneigh, mask_path=mask_path
+    )[0]
+    afni_reho = AFNIReHo().compute(
+        bold_path, nneigh=nneigh, mask_path=mask_path
+    )[0]
+    assert_allclose(
+        junifer_reho.get_fdata(),
+        np.squeeze(afni_reho.get_fdata()),
+        atol=1e-6,
+    )

junifer/markers/reho/tests/test_reho_maps.py

@@ -7,20 +7,23 @@ import logging
 from pathlib import Path
 
 import pytest
-import scipy as sp
+from numpy.testing import assert_allclose
 
-from junifer.datagrabber import PatternDataladDataGrabber
+from junifer.datagrabber import DataType
 from junifer.datareader import DefaultDataReader
-from junifer.markers import ReHoMaps
+from junifer.markers import ReHoImpl, ReHoMaps
 from junifer.pipeline import WorkDirManager
 from junifer.pipeline.utils import _check_afni
 from junifer.storage import HDF5FeatureStorage
+from junifer.testing.datagrabbers import ADHDTestingDataGrabber
+
+
+pytestmark = pytest.mark.external
 
 
 def test_ReHoMaps(
     caplog: pytest.LogCaptureFixture,
     tmp_path: Path,
-    maps_datagrabber: PatternDataladDataGrabber,
 ) -> None:
     """Test ReHoMaps.
 
@@ -30,26 +33,24 @@ def test_ReHoMaps(
         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")]
+        with ADHDTestingDataGrabber() as dg:
+            element = dg["sub-01"]
             element_data = DefaultDataReader().fit_transform(element)
 
             # Initialize marker
             marker = ReHoMaps(
                 maps="Smith_rsn_10",
-                using="junifer",
+                using=ReHoImpl.junifer,
             )
             # Check correct output
             assert "vector" == marker.storage_type(
-                input_type="BOLD", output_feature="reho"
+                input_type=DataType.BOLD, output_feature="reho"
             )
 
             # Fit transform marker on data
@@ -75,7 +76,7 @@ def test_ReHoMaps(
             # Reset log capture
             caplog.clear()
             # Initialize storage
-            storage = HDF5FeatureStorage(tmp_path / "reho_maps.hdf5")
+            storage = HDF5FeatureStorage(uri=tmp_path / "reho_maps.hdf5")
             # Fit transform marker on data with storage
             marker.fit_transform(
                 input=element_data,
@@ -93,43 +94,44 @@ def test_ReHoMaps(
 @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:
+@pytest.mark.parametrize("masks", [None, "compute_brain_mask"])
+def test_ReHoMaps_comparison(tmp_path: Path, masks: str | None) -> None:
     """Test ReHoMaps implementation comparison.
 
     Parameters
     ----------
     tmp_path : pathlib.Path
         The path to the test directory.
-    maps_datagrabber : PatternDataladDataGrabber
-        The testing PatternDataladDataGrabber, as fixture.
+    masks : str or None
+        The masks to use.
 
     """
     # 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")]
+    with ADHDTestingDataGrabber() as dg:
+        element = dg["sub-01"]
         element_data = DefaultDataReader().fit_transform(element)
 
         # Initialize marker
-        junifer_marker = ReHoMaps(maps="Smith_rsn_10", using="junifer")
+        junifer_marker = ReHoMaps(
+            maps="Smith_rsn_10", using=ReHoImpl.junifer, masks=masks
+        )
         # 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")
+        afni_marker = ReHoMaps(
+            maps="Smith_rsn_10", using=ReHoImpl.afni, masks=masks
+        )
         # 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(),
+        # Both implementations should give the same results
+        assert_allclose(
+            junifer_output_bold["data"], afni_output_bold["data"], atol=1e-6
         )
-        assert r >= 0.2  # this is very bad, but they differ...