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

junifer/markers/falff/falff_base.py

@@ -1,16 +1,32 @@
-"""Provide abstract class for computing fALFF."""
+"""Provide base class for ALFF / fALFF."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
 #          Kaustubh R. Patil <k.patil@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
-from abc import abstractmethod
-from typing import ClassVar, Dict, List, Optional, Union
-
-from ...utils.logging import raise_error
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Type,
+    Union,
+)
+
+from ...utils.logging import logger, raise_error
 from ..base import BaseMarker
-from .falff_estimator import ALFFEstimator
+from ._afni_falff import AFNIALFF
+from ._junifer_falff import JuniferALFF
+
+
+if TYPE_CHECKING:
+    from nibabel import Nifti1Image
 
 
 class ALFFBase(BaseMarker):
@@ -24,33 +40,45 @@ class ALFFBase(BaseMarker):
         Highpass cutoff frequency.
     lowpass : positive float
         Lowpass cutoff frequency.
+    using : {"junifer", "afni"}
+        Implementation to use for computing ALFF:
+
+        * "junifer" : Use ``junifer``'s own ALFF implementation
+        * "afni" : Use AFNI's ``3dRSFC``
+
     tr : positive float, optional
         The Repetition Time of the BOLD data. If None, will extract
-        the TR from NIFTI header (default None).
-    use_afni : bool, optional
-        Whether to use AFNI for computing. If None, will use AFNI only
-        if available (default None).
+        the TR from NIfTI header (default None).
     name : str, optional
         The name of the marker. If None, it 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.
+    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.
+
+    Raises
+    ------
+    ValueError
+        If ``highpass`` is not positive or zero or
+        if ``lowpass`` is not positive or
+        if ``highpass`` is higher than ``lowpass`` or
+        if ``using`` is invalid.
 
     """
 
-    _EXT_DEPENDENCIES: ClassVar[
-        List[Dict[str, Union[str, bool, List[str]]]]
-    ] = [
+    _CONDITIONAL_DEPENDENCIES: ClassVar[List[Dict[str, Union[str, Type]]]] = [
+        {
+            "using": "afni",
+            "depends_on": AFNIALFF,
+        },
         {
-            "name": "afni",
-            "optional": True,
-            "commands": ["3dRSFC", "3dAFNItoNIFTI"],
+            "using": "junifer",
+            "depends_on": JuniferALFF,
         },
     ]
 
@@ -59,8 +87,8 @@ class ALFFBase(BaseMarker):
         fractional: bool,
         highpass: float,
         lowpass: float,
+        using: str,
         tr: Optional[float] = None,
-        use_afni: Optional[bool] = None,
         name: Optional[str] = None,
     ) -> None:
         if highpass < 0:
@@ -71,8 +99,14 @@ class ALFFBase(BaseMarker):
             raise_error("Highpass must be lower than lowpass")
         self.highpass = highpass
         self.lowpass = lowpass
+        # Validate `using` parameter
+        valid_using = [dep["using"] for dep in self._CONDITIONAL_DEPENDENCIES]
+        if using not in valid_using:
+            raise_error(
+                f"Invalid value for `using`, should be one of: {valid_using}"
+            )
+        self.using = using
         self.tr = tr
-        self.use_afni = use_afni
         self.fractional = fractional
 
         # Create a name based on the class name if none is provided
@@ -108,79 +142,52 @@ class ALFFBase(BaseMarker):
         """
         return "vector"
 
-    def compute(
+    def _compute(
         self,
-        input: Dict[str, Dict],
-        extra_input: Optional[Dict] = None,
-    ) -> Dict:
-        """Compute.
+        input_data: Dict[str, Any],
+    ) -> Tuple["Nifti1Image", Path]:
+        """Compute ALFF and fALFF.
 
         Parameters
         ----------
-        input : dict
-            A single input from the pipeline data object in which to compute
-            the marker.
+        input_data : dict
+            The input to 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).
+            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:
-
-            * ``data`` : the actual computed values as a numpy.ndarray
-            * ``col_names`` : the column labels for the computed values as list
+        Niimg-like object
+            The ALFF / fALFF as NIfTI.
+        pathlib.Path
+            The path to the ALFF / fALFF as NIfTI.
 
         """
-        if self.use_afni is None:
-            raise_error(
-                "Parameter `use_afni` must be set to True or False in order "
-                "to compute this marker. It is currently set to None (default "
-                "behaviour). This is intended to be for auto-detection. In "
-                "order for that to happen, please call the `validate` method "
-                "before calling the `compute` method."
-            )
-
-        estimator = ALFFEstimator()
-
-        alff, falff = estimator.fit_transform(
-            use_afni=self.use_afni,
-            input_data=input,
+        logger.debug("Calculating ALFF and fALFF")
+
+        # Conditional estimator
+        if self.using == "afni":
+            estimator = AFNIALFF()
+        elif self.using == "junifer":
+            estimator = JuniferALFF()
+        # Compute ALFF + fALFF
+        alff, falff, alff_path, falff_path = estimator.compute(  # type: ignore
+            data=input_data["data"],
             highpass=self.highpass,
             lowpass=self.lowpass,
             tr=self.tr,
         )
-        post_data = falff if self.fractional else alff
-
-        post_input = dict(input.items())
-        post_input["data"] = post_data
-        post_input["path"] = None
-
-        out = self._postprocess(post_input, extra_input=extra_input)
-
-        return out
-
-    @abstractmethod
-    def _postprocess(
-        self, input: Dict, extra_input: Optional[Dict] = None
-    ) -> Dict:
-        """Postprocess the output of the estimator.
 
-        Parameters
-        ----------
-        input : dict
-            The output of the estimator. It must have the following
-        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).
-        """
-        raise_error(
-            "_postprocess must be implemented", klass=NotImplementedError
-        )
+        # If the input data space is native already, the original path should
+        # be propagated down as it might be required for transforming
+        # parcellation / coordinates to native space, else the
+        # path should be passed for use later if required.
+        # TODO(synchon): will be taken care in #292
+        if input_data["space"] == "native" and self.fractional:
+            return falff, input_data["path"]
+        elif input_data["space"] == "native" and not self.fractional:
+            return alff, input_data["path"]
+        elif input_data["space"] != "native" and self.fractional:
+            return falff, falff_path
+        else:
+            return alff, alff_path

junifer/markers/falff/falff_parcels.py

@@ -1,20 +1,22 @@
-"""Provide class for computing fALFF on parcels."""
+"""Provide class for ALFF / fALFF on parcels."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
 #          Kaustubh R. Patil <k.patil@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
-from typing import Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Union
 
 from ...api.decorators import register_marker
-from .. import ParcelAggregation
+from ...utils import logger
+from ..parcel_aggregation import ParcelAggregation
 from .falff_base import ALFFBase
 
 
 @register_marker
 class ALFFParcels(ALFFBase):
-    """Class for computing fALFF/ALFF on parcels.
+    """Class for ALFF / fALFF on parcels.
 
     Parameters
     ----------
@@ -23,6 +25,12 @@ class ALFFParcels(ALFFBase):
         :func:`.list_parcellations`.
     fractional : bool
         Whether to compute fractional ALFF.
+    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).
@@ -30,20 +38,17 @@ class ALFFParcels(ALFFBase):
         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).
-    use_afni : bool, optional
-        Whether to use AFNI for computing. If None, will use AFNI only
-        if available (default None).
+        the TR from NIfTI header (default None).
+    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 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).
-    method : str, optional
-        The method to perform aggregation using. Check valid options in
-        :func:`.get_aggfunc_by_name` (default "mean").
-    method_params : dict, optional
-        Parameters to pass to the aggregation function. Check valid options in
-        :func:`.get_aggfunc_by_name`.
     name : str, optional
         The name of the marker. If None, will use the class name (default
         None).
@@ -51,77 +56,88 @@ class ALFFParcels(ALFFBase):
     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.
+    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,
         parcellation: Union[str, List[str]],
         fractional: bool,
+        using: str,
         highpass: float = 0.01,
         lowpass: float = 0.1,
         tr: Optional[float] = None,
-        use_afni: Optional[bool] = None,
+        agg_method: str = "mean",
+        agg_method_params: Optional[Dict] = None,
         masks: Union[str, Dict, List[Union[Dict, str]], None] = None,
-        method: str = "mean",
-        method_params: Optional[Dict] = None,
         name: Optional[str] = None,
     ) -> None:
-        self.parcellation = parcellation
-        self.masks = masks
-        self.method = method
-        self.method_params = method_params
+        # Superclass init first to validate `using` parameter
         super().__init__(
             fractional=fractional,
             highpass=highpass,
             lowpass=lowpass,
+            using=using,
             tr=tr,
             name=name,
-            use_afni=use_afni,
         )
+        self.parcellation = parcellation
+        self.agg_method = agg_method
+        self.agg_method_params = agg_method_params
+        self.masks = masks
 
-    def _postprocess(
-        self, input: Dict, extra_input: Optional[Dict] = None
-    ) -> Dict:
-        """Compute ALFF and fALFF.
+    def compute(
+        self,
+        input: Dict[str, Any],
+        extra_input: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Compute.
 
         Parameters
         ----------
         input : dict
-            A single input from the pipeline data object in which to compute
-            the marker.
+            The BOLD data as dictionary.
         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).
+            The other fields in the pipeline data object (default None).
 
         Returns
         -------
         dict
-            The computed ALFF as dictionary. The dictionary has the following
+            The computed result as dictionary. The dictionary has the following
             keys:
 
             * ``data`` : the actual computed values as a numpy.ndarray
             * ``col_names`` : the column labels for the computed values as list
 
         """
-        pa = ParcelAggregation(
+        logger.info("Calculating ALFF / fALFF for parcels")
+
+        # Compute ALFF / fALFF
+        output_data, output_file_path = self._compute(input_data=input)
+
+        # Initialize parcel aggregation
+        parcel_aggregation = ParcelAggregation(
             parcellation=self.parcellation,
-            method=self.method,
-            method_params=self.method_params,
+            method=self.agg_method,
+            method_params=self.agg_method_params,
             masks=self.masks,
-            on="fALFF",
+            on="BOLD",
+        )
+        # Perform aggregation on ALFF / fALFF
+        parcel_aggregation_input = dict(input.items())
+        parcel_aggregation_input["data"] = output_data
+        parcel_aggregation_input["path"] = output_file_path
+        output = parcel_aggregation.compute(
+            input=parcel_aggregation_input,
+            extra_input=extra_input,
         )
 
-        # get the 2D timeseries after parcel aggregation
-        out = pa.compute(input, extra_input=extra_input)
-
-        return out
+        return output

junifer/markers/falff/falff_spheres.py

@@ -1,26 +1,36 @@
-"""Provide class for computing fALFF on spheres."""
+"""Provide class for ALFF / fALFF on spheres."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Amir Omidvarnia <a.omidvarnia@fz-juelich.de>
 #          Kaustubh R. Patil <k.patil@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
-from typing import Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Union
 
 from ...api.decorators import register_marker
-from .. import SphereAggregation
+from ...utils import logger
+from ..sphere_aggregation import SphereAggregation
 from .falff_base import ALFFBase
 
 
 @register_marker
 class ALFFSpheres(ALFFBase):
-    """Class for computing fALFF/ALFF on spheres.
+    """Class for computing ALFF / fALFF on spheres.
 
     Parameters
     ----------
     coords : str
         The name of the coordinates list to use. See
         :func:`.list_coordinates` for options.
+    fractional : bool
+        Whether to compute fractional ALFF.
+    using : {"junifer", "afni"}
+        Implementation to use for computing ALFF:
+
+        * "junifer" : Use ``junifer``'s own ALFF implementation
+        * "afni" : Use AFNI's ``3dRSFC``
+
     radius : float, optional
         The radius of the sphere in mm. If None, the signal will be extracted
         from a single voxel. See :class:`nilearn.maskers.NiftiSpheresMasker`
@@ -28,8 +38,6 @@ class ALFFSpheres(ALFFBase):
     allow_overlap : bool, optional
         Whether to allow overlapping spheres. If False, an error is raised if
         the spheres overlap (default is False).
-    fractional : bool
-        Whether to compute fractional ALFF.
     highpass : positive float, optional
         The highpass cutoff frequency for the bandpass filter. If 0,
         it will not apply a highpass filter (default 0.01).
@@ -37,20 +45,17 @@ class ALFFSpheres(ALFFBase):
         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).
-    use_afni : bool, optional
-        Whether to use AFNI for computing. If None, will use AFNI only
-        if available (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).
-    method : str, optional
+        the TR from NIfTI header (default None).
+    agg_method : str, optional
         The method to perform aggregation using. Check valid options in
         :func:`.get_aggfunc_by_name` (default "mean").
-    method_params : dict, optional
+    agg_method_params : dict, optional
         Parameters to pass to the aggregation function. Check valid options in
         :func:`.get_aggfunc_by_name`.
+    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).
@@ -58,83 +63,94 @@ class ALFFSpheres(ALFFBase):
     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
+    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,
         coords: str,
         fractional: bool,
+        using: str,
         radius: Optional[float] = None,
         allow_overlap: bool = False,
         highpass: float = 0.01,
         lowpass: float = 0.1,
         tr: Optional[float] = None,
-        use_afni: Optional[bool] = None,
+        agg_method: str = "mean",
+        agg_method_params: Optional[Dict] = None,
         masks: Union[str, Dict, List[Union[Dict, str]], None] = None,
-        method: str = "mean",
-        method_params: Optional[Dict] = None,
         name: Optional[str] = None,
     ) -> None:
-        self.coords = coords
-        self.radius = radius
-        self.allow_overlap = allow_overlap
-        self.masks = masks
-        self.method = method
-        self.method_params = method_params
+        # Superclass init first to validate `using` parameter
         super().__init__(
             fractional=fractional,
             highpass=highpass,
             lowpass=lowpass,
+            using=using,
             tr=tr,
             name=name,
-            use_afni=use_afni,
         )
+        self.coords = coords
+        self.radius = radius
+        self.allow_overlap = allow_overlap
+        self.agg_method = agg_method
+        self.agg_method_params = agg_method_params
+        self.masks = masks
 
-    def _postprocess(
-        self, input: Dict, extra_input: Optional[Dict] = None
-    ) -> Dict:
-        """Compute ALFF and fALFF.
+    def compute(
+        self,
+        input: Dict[str, Any],
+        extra_input: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Compute.
 
         Parameters
         ----------
         input : dict
-            A single input from the pipeline data object in which to compute
-            the marker.
+            The BOLD data as dictionary.
         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).
+            The other fields in the pipeline data object (default None).
 
         Returns
         -------
         dict
-            The computed ALFF as dictionary. The dictionary has the following
+            The computed result as dictionary. The dictionary has the following
             keys:
 
             * ``data`` : the actual computed values as a numpy.ndarray
             * ``col_names`` : the column labels for the computed values as list
 
         """
-        pa = SphereAggregation(
+        logger.info("Calculating ALFF / fALFF for spheres")
+
+        # Compute ALFF / fALFF
+        output_data, output_file_path = self._compute(input_data=input)
+
+        # Initialize sphere aggregation
+        sphere_aggregation = SphereAggregation(
             coords=self.coords,
             radius=self.radius,
             allow_overlap=self.allow_overlap,
-            method=self.method,
-            method_params=self.method_params,
+            method=self.agg_method,
+            method_params=self.agg_method_params,
             masks=self.masks,
-            on="fALFF",
+            on="BOLD",
+        )
+        # Perform aggregation on ALFF / fALFF
+        sphere_aggregation_input = dict(input.items())
+        sphere_aggregation_input["data"] = output_data
+        sphere_aggregation_input["path"] = output_file_path
+        output = sphere_aggregation.compute(
+            input=sphere_aggregation_input,
+            extra_input=extra_input,
         )
 
-        # get the 2D timeseries after sphere aggregation
-        out = pa.compute(input, extra_input=extra_input)
-
-        return out
+        return output