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

junifer/markers/parcel_aggregation.py

@@ -7,11 +7,11 @@
 from typing import Any, ClassVar, Dict, List, Optional, Set, Union
 
 import numpy as np
-from nilearn.image import math_img, resample_to_img
+from nilearn.image import math_img
 from nilearn.maskers import NiftiMasker
 
 from ..api.decorators import register_marker
-from ..data import get_mask, load_parcellation, merge_parcellations
+from ..data import get_mask, get_parcellation
 from ..stats import get_aggfunc_by_name
 from ..utils import logger, raise_error, warn_with_log
 from .base import BaseMarker
@@ -42,13 +42,20 @@ class ParcelAggregation(BaseMarker):
         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", "BOLD", "VBM_GM", "VBM_WM", "fALFF", "GCOR", "LCOR"} \
-         or list of the options, optional
+    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[Set[str]] = {"nilearn", "numpy"}
@@ -95,7 +102,17 @@ class ParcelAggregation(BaseMarker):
             The list of data types that can be used as input for this marker.
 
         """
-        return ["T1w", "BOLD", "VBM_GM", "VBM_WM", "fALFF", "GCOR", "LCOR"]
+        return [
+            "T1w",
+            "T2w",
+            "BOLD",
+            "VBM_GM",
+            "VBM_WM",
+            "VBM_CSF",
+            "fALFF",
+            "GCOR",
+            "LCOR",
+        ]
 
     def get_output_type(self, input_type: str) -> str:
         """Get output type.
@@ -110,14 +127,26 @@ class ParcelAggregation(BaseMarker):
         str
             The storage type output by the marker.
 
+        Raises
+        ------
+        ValueError
+            If the ``input_type`` is invalid.
+
         """
 
-        if input_type in ["VBM_GM", "VBM_WM", "fALFF", "GCOR", "LCOR"]:
+        if input_type in [
+            "VBM_GM",
+            "VBM_WM",
+            "VBM_CSF",
+            "fALFF",
+            "GCOR",
+            "LCOR",
+        ]:
             return "vector"
         elif input_type == "BOLD":
             return "timeseries"
         else:
-            raise ValueError(f"Unknown input kind for {input_type}")
+            raise_error(f"Unknown input kind for {input_type}")
 
     def compute(
         self, input: Dict[str, Any], extra_input: Optional[Dict] = None
@@ -145,62 +174,53 @@ class ParcelAggregation(BaseMarker):
             * ``data`` : the actual computed values as a numpy.ndarray
             * ``col_names`` : the column labels for the computed values as list
 
+        Warns
+        -----
+        RuntimeWarning
+            If time aggregation is required but only time point is available.
+
         """
         t_input_img = input["data"]
         logger.debug(f"Parcel aggregation using {self.method}")
+        # Get aggregation function
         agg_func = get_aggfunc_by_name(
             name=self.method, func_params=self.method_params
         )
-        # Get the min of the voxels sizes and use it as the resolution
-        resolution = np.min(t_input_img.header.get_zooms()[:3])
-
-        # Load the parcellations
-        all_parcelations = []
-        all_labels = []
-        for t_parc_name in self.parcellation:
-            t_parcellation, t_labels, _ = load_parcellation(
-                name=t_parc_name, resolution=resolution
-            )
-            # Resample all of them to the image
-            t_parcellation_img_res = resample_to_img(
-                t_parcellation, t_input_img, interpolation="nearest", copy=True
-            )
-            all_parcelations.append(t_parcellation_img_res)
-            all_labels.append(t_labels)
 
-        # Avoid merging if there is only one parcellation
-        if len(all_parcelations) == 1:
-            parcellation_img_res = all_parcelations[0]
-            labels = all_labels[0]
-        else:
-            # Merge the parcellations
-            parcellation_img_res, labels = merge_parcellations(
-                all_parcelations, self.parcellation, all_labels
-            )
+        # Get parcellation tailored to target image
+        parcellation_img, labels = get_parcellation(
+            parcellation=self.parcellation,
+            target_data=input,
+            extra_input=extra_input,
+        )
 
-        parcellation_bin = math_img("img != 0", img=parcellation_img_res)
+        # Get binarized parcellation image for masking
+        parcellation_bin = math_img("img != 0", img=parcellation_img)
 
+        # Load mask
         if self.masks is not None:
             logger.debug(f"Masking with {self.masks}")
+            # Get tailored mask
             mask_img = get_mask(
                 masks=self.masks, target_data=input, extra_input=extra_input
             )
-
+            # Get "logical and" version of parcellation and mask
             parcellation_bin = math_img(
                 "np.logical_and(img, mask)",
                 img=parcellation_bin,
                 mask=mask_img,
             )
 
+        # Initialize masker
         logger.debug("Masking")
         masker = NiftiMasker(
             parcellation_bin, target_affine=t_input_img.affine
-        )  # type: ignore
-
+        )
         # Mask the input data and the parcellation
         data = masker.fit_transform(t_input_img)
-        parcellation_values = masker.transform(parcellation_img_res)
-        parcellation_values = np.squeeze(parcellation_values).astype(int)
+        parcellation_values = np.squeeze(
+            masker.transform(parcellation_img)
+        ).astype(int)
 
         # Get the values for each parcel and apply agg function
         logger.debug("Computing ROI means")
@@ -214,6 +234,7 @@ class ParcelAggregation(BaseMarker):
 
         out_values = np.array(out_values).T
 
+        # Apply time dimension aggregation if required
         if self.time_method is not None:
             if out_values.shape[0] > 1:
                 logger.debug("Aggregating time dimension")
@@ -226,5 +247,6 @@ class ParcelAggregation(BaseMarker):
                     "No time dimension to aggregate as only one time point is "
                     "available."
                 )
+        # Format the output
         out = {"data": out_values, "col_names": labels}
         return out

junifer/markers/reho/_afni_reho.py

@@ -0,0 +1,192 @@
+"""Provide class for computing regional homogeneity (ReHo) using AFNI."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from functools import lru_cache
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Union,
+)
+
+import nibabel as nib
+
+from ...pipeline import WorkDirManager
+from ...pipeline.singleton import singleton
+from ...utils import logger, run_ext_cmd
+
+
+if TYPE_CHECKING:
+    from nibabel import Nifti1Image
+
+
+@singleton
+class AFNIReHo:
+    """Class for computing ReHo using AFNI.
+
+    This class uses AFNI's 3dReHo to compute ReHo. It's designed as a singleton
+    with caching for efficient computation.
+
+    """
+
+    _EXT_DEPENDENCIES: ClassVar[List[Dict[str, Union[str, List[str]]]]] = [
+        {
+            "name": "afni",
+            "commands": ["3dReHo", "3dAFNItoNIFTI"],
+        },
+    ]
+
+    def __del__(self) -> None:
+        """Terminate the class."""
+        # Clear the computation cache
+        logger.debug("Clearing cache for ReHo computation via AFNI")
+        self.compute.cache_clear()
+
+    @lru_cache(maxsize=None, typed=True)
+    def compute(
+        self,
+        data: "Nifti1Image",
+        nneigh: int = 27,
+        neigh_rad: Optional[float] = None,
+        neigh_x: Optional[float] = None,
+        neigh_y: Optional[float] = None,
+        neigh_z: Optional[float] = None,
+        box_rad: Optional[int] = None,
+        box_x: Optional[int] = None,
+        box_y: Optional[int] = None,
+        box_z: Optional[int] = None,
+    ) -> Tuple["Nifti1Image", Path]:
+        """Compute ReHo map.
+
+        Parameters
+        ----------
+        data : 4D Niimg-like object
+            Images to process.
+        nneigh : {7, 19, 27}, optional
+            Number of voxels in the neighbourhood, inclusive. Can be:
+
+            * 7 : for facewise neighbours only
+            * 19 : for face- and edge-wise nieghbours
+            * 27 : for face-, edge-, and node-wise neighbors
+
+            (default 27).
+        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).
+
+        Returns
+        -------
+        Niimg-like object
+            The ReHo map as NIfTI.
+        pathlib.Path
+            The path to the ReHo map as NIfTI.
+
+        Notes
+        -----
+        For more information on the publication, please check [1]_ , and for
+        3dReHo help check:
+        https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dReHo.html
+
+        Please note that that you cannot mix ``box_*`` and ``neigh_*``
+        arguments. The arguments are prioritized by their order in the function
+        signature.
+
+        As the process also depends on the conversion of AFNI files to NIFTI
+        via afni's 3dAFNItoNIFTI, the help for that can be found at:
+        https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dAFNItoNIFTI.html
+
+        References
+        ----------
+        .. [1] Taylor, P.A., & Saad, Z.S. (2013).
+               FATCAT: (An Efficient) Functional And Tractographic Connectivity
+               Analysis Toolbox.
+               Brain connectivity, Volume 3(5), Pages 523-35.
+               https://doi.org/10.1089/brain.2013.0154
+
+        """
+        logger.debug("Creating cache for ReHo computation via AFNI")
+
+        # Create component-scoped tempdir
+        tempdir = WorkDirManager().get_tempdir(prefix="afni_reho")
+
+        # Save target data to a component-scoped tempfile
+        nifti_in_file_path = tempdir / "input.nii"  # needs to be .nii
+        nib.save(data, nifti_in_file_path)
+
+        # Set 3dReHo command
+        reho_out_path_prefix = tempdir / "reho"
+        reho_cmd = [
+            "3dReHo",
+            f"-prefix {reho_out_path_prefix.resolve()}",
+            f"-inset {nifti_in_file_path.resolve()}",
+        ]
+        # Check ellipsoidal / cuboidal volume arguments
+        if neigh_rad:
+            reho_cmd.append(f"-neigh_RAD {neigh_rad}")
+        elif neigh_x and neigh_y and neigh_z:
+            reho_cmd.extend(
+                [
+                    f"-neigh_X {neigh_x}",
+                    f"-neigh_Y {neigh_y}",
+                    f"-neigh_Z {neigh_z}",
+                ]
+            )
+        elif box_rad:
+            reho_cmd.append(f"-box_RAD {box_rad}")
+        elif box_x and box_y and box_z:
+            reho_cmd.extend(
+                [f"-box_X {box_x}", f"-box_Y {box_y}", f"-box_Z {box_z}"]
+            )
+        else:
+            reho_cmd.append(f"-nneigh {nneigh}")
+        # Call 3dReHo
+        run_ext_cmd(name="3dReHo", cmd=reho_cmd)
+
+        # Create element-scoped tempdir so that the ReHo map is
+        # available later as nibabel stores file path reference for
+        # loading on computation
+        element_tempdir = WorkDirManager().get_element_tempdir(
+            prefix="afni_reho"
+        )
+        # Convert afni to nifti
+        reho_afni_to_nifti_out_path = (
+            element_tempdir / "output.nii"  # needs to be .nii
+        )
+        convert_cmd = [
+            "3dAFNItoNIFTI",
+            f"-prefix {reho_afni_to_nifti_out_path.resolve()}",
+            f"{reho_out_path_prefix}+tlrc.BRIK",
+        ]
+        # Call 3dAFNItoNIFTI
+        run_ext_cmd(name="3dAFNItoNIFTI", cmd=convert_cmd)
+
+        # Load nifti
+        output_data = nib.load(reho_afni_to_nifti_out_path)
+
+        # Delete tempdir
+        WorkDirManager().delete_tempdir(tempdir)
+
+        return output_data, reho_afni_to_nifti_out_path  # type: ignore

junifer/markers/reho/_junifer_reho.py

@@ -0,0 +1,281 @@
+"""Provide class for computing regional homogeneity (ReHo) using junifer."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from functools import lru_cache
+from itertools import product
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    Set,
+    Tuple,
+)
+
+import nibabel as nib
+import numpy as np
+import scipy as sp
+from nilearn import image as nimg
+from nilearn import masking as nmask
+
+from ...pipeline import WorkDirManager
+from ...pipeline.singleton import singleton
+from ...utils import logger, raise_error
+
+
+if TYPE_CHECKING:
+    from nibabel import Nifti1Image
+
+
+@singleton
+class JuniferReHo:
+    """Class for computing ReHo using junifer.
+
+    It's designed as a singleton with caching for efficient computation.
+
+    """
+
+    _DEPENDENCIES: ClassVar[Set[str]] = {"numpy", "nilearn", "scipy"}
+
+    def __del__(self) -> None:
+        """Terminate the class."""
+        # Clear the computation cache
+        logger.debug("Clearing cache for ReHo computation via junifer")
+        self.compute.cache_clear()
+
+    @lru_cache(maxsize=None, typed=True)
+    def compute(
+        self,
+        data: "Nifti1Image",
+        nneigh: int = 27,
+    ) -> Tuple["Nifti1Image", Path]:
+        """Compute ReHo map.
+
+        Parameters
+        ----------
+        data : 4D Niimg-like object
+            Images to process.
+        nneigh : {7, 19, 27, 125}, optional
+            Number of voxels in the neighbourhood, inclusive. Can be:
+
+            * 7 : for facewise neighbours only
+            * 19 : for face- and edge-wise nieghbours
+            * 27 : for face-, edge-, and node-wise neighbors
+            * 125 : for 5x5 cuboidal volume
+
+            (default 27).
+
+        Returns
+        -------
+        Niimg-like object
+            The ReHo map as NIfTI.
+        pathlib.Path
+            The path to the ReHo map as NIfTI.
+
+        Raises
+        ------
+        ValueError
+            If ``nneigh`` is invalid.
+
+        """
+        valid_nneigh = (7, 19, 27, 125)
+        if nneigh not in valid_nneigh:
+            raise_error(
+                f"Invalid value for `nneigh`, should be one of: {valid_nneigh}"
+            )
+
+        logger.debug("Creating cache for ReHo computation via junifer")
+
+        # Get scan data
+        niimg_data = data.get_fdata()
+        # Get scan dimensions
+        n_x, n_y, n_z, _ = niimg_data.shape
+
+        # Get rank of every voxel across time series
+        ranks_niimg_data = sp.stats.rankdata(niimg_data, axis=-1)
+
+        # Initialize 3D array to store tied rank correction for every voxel
+        tied_rank_corrections = np.zeros((n_x, n_y, n_z), dtype=np.float64)
+        # Calculate tied rank correction for every voxel
+        for i_x, i_y, i_z in product(range(n_x), range(n_y), range(n_z)):
+            # Calculate tied rank count for every voxel across time series
+            _, tie_count = np.unique(
+                ranks_niimg_data[i_x, i_y, i_z, :],
+                return_counts=True,
+            )
+            # Calculate and store tied rank correction for every voxel across
+            # timeseries
+            tied_rank_corrections[i_x, i_y, i_z] = np.sum(
+                tie_count**3 - tie_count
+            )
+
+        # Initialize 3D array to store reho map
+        reho_map = np.ones((n_x, n_y, n_z), dtype=np.float32)
+
+        # TODO(synchon): this will give incorrect results if
+        # template doesn't match, hence needs to be changed
+        # after #299 is merged
+        # Calculate whole brain mask
+        mni152_whole_brain_mask = nmask.compute_brain_mask(
+            target_img=data,
+            threshold=0.5,
+            mask_type="whole-brain",
+        )
+        # Convert 0 / 1 array to bool
+        logical_mni152_whole_brain_mask = (
+            mni152_whole_brain_mask.get_fdata().astype(bool)
+        )
+
+        # Create mask cluster and set start and end indices
+        if nneigh in (7, 19, 27):
+            mask_cluster = np.ones((3, 3, 3))
+
+            if nneigh == 7:
+                mask_cluster[0, 0, 0] = 0
+                mask_cluster[0, 1, 0] = 0
+                mask_cluster[0, 2, 0] = 0
+                mask_cluster[0, 0, 1] = 0
+                mask_cluster[0, 2, 1] = 0
+                mask_cluster[0, 0, 2] = 0
+                mask_cluster[0, 1, 2] = 0
+                mask_cluster[0, 2, 2] = 0
+                mask_cluster[1, 0, 0] = 0
+                mask_cluster[1, 2, 0] = 0
+                mask_cluster[1, 0, 2] = 0
+                mask_cluster[1, 2, 2] = 0
+                mask_cluster[2, 0, 0] = 0
+                mask_cluster[2, 1, 0] = 0
+                mask_cluster[2, 2, 0] = 0
+                mask_cluster[2, 0, 1] = 0
+                mask_cluster[2, 2, 1] = 0
+                mask_cluster[2, 0, 2] = 0
+                mask_cluster[2, 1, 2] = 0
+                mask_cluster[2, 2, 2] = 0
+
+            elif nneigh == 19:
+                mask_cluster[0, 0, 0] = 0
+                mask_cluster[0, 2, 0] = 0
+                mask_cluster[2, 0, 0] = 0
+                mask_cluster[2, 2, 0] = 0
+                mask_cluster[0, 0, 2] = 0
+                mask_cluster[0, 2, 2] = 0
+                mask_cluster[2, 0, 2] = 0
+                mask_cluster[2, 2, 2] = 0
+
+            start_idx = 1
+            end_idx = 2
+
+        elif nneigh == 125:
+            mask_cluster = np.ones((5, 5, 5))
+            start_idx = 2
+            end_idx = 3
+
+        # Convert 0 / 1 array to bool
+        logical_mask_cluster = mask_cluster.astype(bool)
+
+        for i, j, k in product(
+            range(start_idx, n_x - (end_idx - 1)),
+            range(start_idx, n_y - (end_idx - 1)),
+            range(start_idx, n_z - (end_idx - 1)),
+        ):
+            # Get mask only for neighbourhood
+            logical_neighbourhood_mni152_whole_brain_mask = (
+                logical_mni152_whole_brain_mask[
+                    i - start_idx : i + end_idx,
+                    j - start_idx : j + end_idx,
+                    k - start_idx : k + end_idx,
+                ]
+            )
+            # Perform logical AND to get neighbourhood mask;
+            # done to take care of brain boundaries
+            neighbourhood_mask = (
+                logical_mask_cluster
+                & logical_neighbourhood_mni152_whole_brain_mask
+            )
+            # Continue if voxel is restricted by mask
+            if neighbourhood_mask[1, 1, 1] == 0:
+                continue
+
+            # Get ranks for the neighbourhood
+            neighbourhood_ranks = ranks_niimg_data[
+                i - start_idx : i + end_idx,
+                j - start_idx : j + end_idx,
+                k - start_idx : k + end_idx,
+                :,
+            ]
+            # Get tied ranks corrections for the neighbourhood
+            neighbourhood_tied_ranks_corrections = tied_rank_corrections[
+                i - start_idx : i + end_idx,
+                j - start_idx : j + end_idx,
+                k - start_idx : k + end_idx,
+            ]
+            # Mask neighbourhood ranks
+            masked_neighbourhood_ranks = neighbourhood_ranks[
+                logical_mask_cluster, :
+            ]
+            # Mask tied ranks corrections for the neighbourhood
+            masked_tied_rank_corrections = (
+                neighbourhood_tied_ranks_corrections[logical_mask_cluster]
+            )
+            # Calculate KCC
+            reho_map[i, j, k] = _kendall_w_reho(
+                timeseries_ranks=masked_neighbourhood_ranks,
+                tied_rank_corrections=masked_tied_rank_corrections,
+            )
+
+        # Create new image like target image
+        output_data = nimg.new_img_like(
+            ref_niimg=data,
+            data=reho_map,
+            copy_header=False,
+        )
+
+        # Create element-scoped tempdir so that the ReHo map is
+        # available later as nibabel stores file path reference for
+        # loading on computation
+        element_tempdir = WorkDirManager().get_element_tempdir(
+            prefix="junifer_reho"
+        )
+        output_path = element_tempdir / "output.nii.gz"
+        # Save computed data to file
+        nib.save(output_data, output_path)
+
+        return output_data, output_path  # type: ignore
+
+
+def _kendall_w_reho(
+    timeseries_ranks: np.ndarray, tied_rank_corrections: np.ndarray
+) -> float:
+    """Calculate Kendall's coefficient of concordance (KCC) for ReHo map.
+
+    ..note:: This function should only be used to calculate KCC for a ReHo map.
+             For general use, check out ``junifer.stats.kendall_w``.
+
+    Parameters
+    ----------
+    timeseries_ranks : 2D numpy.ndarray
+        A matrix of ranks of a subset subject's brain voxels.
+    tied_rank_corrections : 3D numpy.ndarray
+        A 3D array consisting of the tied rank corrections for the ranks
+        of a subset subject's brain voxels.
+
+    Returns
+    -------
+    float
+        Kendall's W (KCC) of the given timeseries matrix.
+
+    """
+    m, n = timeseries_ranks.shape  # annotators X items
+
+    numerator = (12 * np.sum(np.square(np.sum(timeseries_ranks, axis=0)))) - (
+        3 * m**2 * n * (n + 1) ** 2
+    )
+    denominator = (m**2 * n * (n**2 - 1)) - (m * np.sum(tied_rank_corrections))
+
+    if denominator == 0:
+        kcc = 1.0
+    else:
+        kcc = numerator / denominator
+
+    return kcc