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

junifer/markers/ets_rss.py

@@ -6,16 +6,19 @@
 #          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
-from typing import Any, ClassVar, Optional, Union
+from typing import Annotated, Any, ClassVar
 
 import numpy as np
+from pydantic import BeforeValidator
 
 from ..api.decorators import register_marker
+from ..datagrabber import DataType
+from ..storage import StorageType
 from ..typing import Dependencies, MarkerInOutMappings
-from ..utils import logger
-from .base import BaseMarker
+from ..utils import ensure_list, ensure_list_or_none
+from .base import BaseMarker, logger
 from .parcel_aggregation import ParcelAggregation
-from .utils import _ets
+from .utils import _ets, _has_data
 
 
 __all__ = ["RSSETSMarker"]
@@ -31,47 +34,42 @@ class RSSETSMarker(BaseMarker):
         The name(s) of the parcellation(s) to use.
         See :func:`.list_data` for options.
     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, will use the class name (default
-        None).
+    name : str or None, optional
+        The name of the marker.
+        If None, will use the class name (default None).
 
     """
 
     _DEPENDENCIES: ClassVar[Dependencies] = {"nilearn"}
 
     _MARKER_INOUT_MAPPINGS: ClassVar[MarkerInOutMappings] = {
-        "BOLD": {
-            "rss_ets": "timeseries",
+        DataType.BOLD: {
+            "rss_ets": StorageType.Timeseries,
         },
     }
 
-    def __init__(
-        self,
-        parcellation: Union[str, list[str]],
-        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:
-        self.parcellation = parcellation
-        self.agg_method = agg_method
-        self.agg_method_params = agg_method_params
-        self.masks = masks
-        super().__init__(name=name)
+    parcellation: Annotated[str | list[str], BeforeValidator(ensure_list)]
+    agg_method: str = "mean"
+    agg_method_params: dict | None = None
+    masks: Annotated[
+        dict | str | list[dict | str] | None,
+        BeforeValidator(ensure_list_or_none),
+    ] = None
 
     def compute(
         self,
         input: dict[str, Any],
-        extra_input: Optional[dict] = None,
+        extra_input: dict | None = None,
     ) -> dict:
         """Compute.
 
@@ -110,12 +108,18 @@ class RSSETSMarker(BaseMarker):
             parcellation=self.parcellation,
             method=self.agg_method,
             method_params=self.agg_method_params,
+            on=DataType.BOLD,
             masks=self.masks,
         ).compute(input=input, extra_input=extra_input)
         # Compute edgewise timeseries
         edge_ts, _ = _ets(aggregation["aggregation"]["data"])
-        # Compute the RSS of edgewise timeseries
-        rss = np.sum(edge_ts**2, 1) ** 0.5
+        # Compute the RSS of edgewise timeseries, only using the edges with
+        # data (e.g. regions lost in resampling have none)
+        edge_ts = edge_ts[:, _has_data(edge_ts)]
+        if edge_ts.shape[1] > 0:
+            rss = np.sum(edge_ts**2, 1) ** 0.5
+        else:
+            rss = np.full(edge_ts.shape[0], np.nan)
 
         return {
             "rss_ets": {

junifer/markers/falff/__init__.pyi

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

junifer/markers/falff/_afni_falff.py

@@ -3,20 +3,21 @@
 # Authors: Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
+import atexit
 from functools import lru_cache
 from pathlib import Path
 from typing import (
     TYPE_CHECKING,
     ClassVar,
-    Optional,
 )
 
 import nibabel as nib
 
-from ...pipeline import WorkDirManager
+from ...pipeline import ExtDep, WorkDirManager
 from ...typing import ExternalDependencies
-from ...utils import logger, run_ext_cmd
+from ...utils import run_ext_cmd
 from ...utils.singleton import Singleton
+from ..base import logger
 
 
 if TYPE_CHECKING:
@@ -36,13 +37,15 @@ class AFNIALFF(metaclass=Singleton):
 
     _EXT_DEPENDENCIES: ClassVar[ExternalDependencies] = [
         {
-            "name": "afni",
+            "name": ExtDep.AFNI,
             "commands": ["3dRSFC", "3dAFNItoNIFTI"],
         },
     ]
 
-    def __del__(self) -> None:
-        """Terminate the class."""
+    def __init__(self) -> None:
+        atexit.register(self._del)
+
+    def _del(self) -> None:
         # Clear the computation cache
         logger.debug("Clearing cache for ALFF computation via AFNI")
         self.compute.cache_clear()
@@ -53,7 +56,8 @@ class AFNIALFF(metaclass=Singleton):
         input_path: Path,
         highpass: float,
         lowpass: float,
-        tr: Optional[float],
+        tr: float | None,
+        mask_path: Path | None = None,
     ) -> tuple["Nifti1Image", "Nifti1Image", Path, Path]:
         """Compute ALFF + fALFF map.
 
@@ -67,6 +71,10 @@ class AFNIALFF(metaclass=Singleton):
             Lowpass cutoff frequency.
         tr : positive float, optional
             The Repetition Time of the BOLD data.
+        mask_path : pathlib.Path, optional
+            Path to the mask to restrict the computation to. The voxels
+            outside the mask are set to 0. If None, all the voxels are used
+            (default None).
 
         Returns
         -------
@@ -87,18 +95,23 @@ class AFNIALFF(metaclass=Singleton):
             prefix="afni_lff"
         )
 
-        # Set 3dRSFC command
+        # Set 3dRSFC command; only the parameters are needed, not the
+        # bandpassed time series (-no_rs_out)
         lff_out_path_prefix = element_tempdir / "output"
         bp_cmd = [
             "3dRSFC",
             f"-prefix {lff_out_path_prefix.resolve()}",
             f"-input {input_path.resolve()}",
             f"-band {highpass} {lowpass}",
-            "-no_rsfa -nosat -nodetrend",
+            "-no_rsfa -nosat -nodetrend -no_rs_out",
         ]
         # Check tr
         if tr is not None:
             bp_cmd.append(f"-dt {tr}")
+        # Restrict the computation to the mask, which reduces the memory and
+        # time used by 3dRSFC
+        if mask_path is not None:
+            bp_cmd.append(f"-mask {mask_path.resolve()}")
         # Call 3dRSFC
         run_ext_cmd(name="3dRSFC", cmd=bp_cmd)
 

junifer/markers/falff/_junifer_falff.py

@@ -8,7 +8,6 @@ from pathlib import Path
 from typing import (
     TYPE_CHECKING,
     ClassVar,
-    Optional,
 )
 
 import nibabel as nib
@@ -18,8 +17,8 @@ from nilearn import image as nimg
 
 from ...pipeline import WorkDirManager
 from ...typing import Dependencies
-from ...utils import logger
 from ...utils.singleton import Singleton
+from ..base import logger
 
 
 if TYPE_CHECKING:
@@ -50,7 +49,8 @@ class JuniferALFF(metaclass=Singleton):
         input_path: Path,
         highpass: float,
         lowpass: float,
-        tr: Optional[float],
+        tr: float | None,
+        mask_path: Path | None = None,
     ) -> tuple["Nifti1Image", "Nifti1Image", Path, Path]:
         """Compute ALFF + fALFF map.
 
@@ -64,6 +64,10 @@ class JuniferALFF(metaclass=Singleton):
             Lowpass cutoff frequency.
         tr : positive float, optional
             The Repetition Time of the BOLD data.
+        mask_path : pathlib.Path, optional
+            Path to the mask to restrict the computation to. The voxels
+            outside the mask are set to 0. If None, all the voxels are used
+            (default None).
 
         Returns
         -------
@@ -79,47 +83,59 @@ class JuniferALFF(metaclass=Singleton):
         """
         logger.debug("Creating cache for ALFF computation via junifer")
 
-        # Get scan data
+        # Get scan data (no extra copy, don't keep nibabel's cached copy)
         niimg = nib.load(input_path)
-        niimg_data = niimg.get_fdata().copy()
+        niimg_data = niimg.get_fdata(caching="unchanged")
         if tr is None:
             tr = float(niimg.header["pixdim"][4])  # type: ignore
             logger.info(f"`tr` not provided, using `tr` from header: {tr}")
 
-        # Bandpass the data within the lowpass and highpass cutoff freqs
-        fft_data = sp.fft.fft(niimg_data, axis=-1)
-        fft_freqs = np.abs(sp.fft.fftfreq(niimg_data.shape[-1], tr))
-        # Frequency difference
-        fft_freqs_diff = fft_freqs[1] - fft_freqs[0]
-        # Nyquist frequency
-        nyquist = np.max(fft_freqs)
-        # FFT sample frequency count
-        n_fft = len(fft_freqs)
+        n_timepoints = niimg_data.shape[-1]
+        # One-sided spectrum of a real signal; weights reproduce the
+        # two-sided sums (each non-zero bin appears twice, Nyquist once)
+        fft_freqs = sp.fft.rfftfreq(n_timepoints, tr)
+        weights = np.full(fft_freqs.shape, 2.0)
+        weights[0] = 0.0  # exclude DC
+        if n_timepoints % 2 == 0:
+            weights[-1] = 1.0  # Nyquist bin appears only once
+        band_weights = np.where(
+            (fft_freqs > highpass) & (fft_freqs < lowpass), weights, 0.0
+        )
         logger.info(
-            f"FFT: nfft = {n_fft}, dFreq = {fft_freqs_diff}, "
-            f"nyquist = {nyquist}"
+            f"FFT: nfft = {n_timepoints}, "
+            f"dFreq = {fft_freqs[1] - fft_freqs[0]}, "
+            f"nyquist = {fft_freqs[-1]}"
         )
 
-        # Compute the denominator on the broadband signal
-        all_freq_mask = fft_freqs > 0
-        denominator = np.sum(np.abs(fft_data[..., all_freq_mask]), axis=-1)
-
-        # Compute the numerator on the bandpassed signal
-        freq_mask = np.logical_and(fft_freqs > highpass, fft_freqs < lowpass)
-
-        # Compute ALFF
-        numerator = np.sum(np.abs(fft_data[..., freq_mask]), axis=-1)
+        # Process voxels (only the ones in the mask, if any) in chunks to
+        # bound FFT memory
+        flat = niimg_data.reshape(-1, n_timepoints)
+        if mask_path is not None:
+            mask_data = np.squeeze(np.asarray(nib.load(mask_path).dataobj))
+            voxels = np.flatnonzero(mask_data.reshape(-1) != 0)
+        else:
+            voxels = np.arange(flat.shape[0])
+        numerator = np.zeros(flat.shape[0])
+        denominator = np.zeros(flat.shape[0])
+        chunk = 20_000
+        for start in range(0, len(voxels), chunk):
+            t_voxels = voxels[start : start + chunk]
+            amp = np.abs(sp.fft.rfft(flat[t_voxels], axis=-1))
+            denominator[t_voxels] = amp @ weights
+            numerator[t_voxels] = amp @ band_weights
+        spatial_shape = niimg_data.shape[:-1]
+        numerator = numerator.reshape(spatial_shape)
+        denominator = denominator.reshape(spatial_shape)
+        del niimg_data, flat
 
         # Compute fALFF, but avoid division by zero
         denom_mask = denominator <= 0.000001
-        denominator[denom_mask] = 1  # set to 1 to avoid division by zero
-        # Calculate fALFF
+        denominator[denom_mask] = 1
         falff = np.divide(numerator, denominator)
-        # Set the values where denominator is zero to zero
         falff[denom_mask] = 0
 
         # Calculate ALFF
-        alff = numerator / np.sqrt(niimg_data.shape[-1])
+        alff = numerator / np.sqrt(n_timepoints)
         alff_data = nimg.new_img_like(
             ref_niimg=niimg,
             data=alff,
@@ -133,8 +149,8 @@ class JuniferALFF(metaclass=Singleton):
         element_tempdir = WorkDirManager().get_element_tempdir(
             prefix="junifer_lff"
         )
-        output_alff_path = element_tempdir / "output_alff.nii.gz"
-        output_falff_path = element_tempdir / "output_falff.nii.gz"
+        output_alff_path = element_tempdir / "output_alff.nii"
+        output_falff_path = element_tempdir / "output_falff.nii"
         # Save computed data to file
         nib.save(alff_data, output_alff_path)
         nib.save(falff_data, output_falff_path)

junifer/markers/falff/falff_base.py

@@ -6,17 +6,24 @@
 #          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
+from enum import StrEnum
 from pathlib import Path
 from typing import (
     TYPE_CHECKING,
+    Annotated,
     Any,
     ClassVar,
-    Optional,
 )
 
+from pydantic import BeforeValidator, PositiveFloat
+
+from ...data import get_data
+from ...datagrabber import DataType
+from ...storage import StorageType
 from ...typing import ConditionalDependencies, MarkerInOutMappings
-from ...utils.logging import logger, raise_error
-from ..base import BaseMarker
+from ...utils import ensure_list_or_none
+from ..base import BaseMarker, logger
+from ..utils import _save_mask
 from ._afni_falff import AFNIALFF
 from ._junifer_falff import JuniferALFF
 
@@ -25,7 +32,19 @@ if TYPE_CHECKING:
     from nibabel.nifti1 import Nifti1Image
 
 
-__all__ = ["ALFFBase"]
+__all__ = ["ALFFBase", "ALFFImpl"]
+
+
+class ALFFImpl(StrEnum):
+    """Accepted ALFF implementations.
+
+    * ``junifer`` : ``junifer``'s ALFF
+    * ``afni`` : AFNI's ``3dRSFC``
+
+    """
+
+    junifer = "junifer"
+    afni = "afni"
 
 
 class ALFFBase(BaseMarker):
@@ -33,22 +52,30 @@ class ALFFBase(BaseMarker):
 
     Parameters
     ----------
-    highpass : positive float
-        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``
-
+    using : :enum:`.ALFFImpl`
+    highpass : positive float, optional
+        Highpass cutoff frequency (default 0.01).
+    lowpass : positive float, optional
+        Lowpass cutoff frequency (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).
-    name : str, optional
-        The name of the marker. If None, it will use the class name
-        (default None).
+        The repetition time of the BOLD data.
+        If None, will extract the TR from NIfTI header (default None).
+    agg_method : 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. The ALFF and fALFF
+        computation is restricted to the voxels in the mask, and the mask is
+        also applied 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 or None, optional
+        The name of the marker.
+        If None, it will use the class name (default None).
 
     Notes
     -----
@@ -58,63 +85,41 @@ class ALFFBase(BaseMarker):
     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.
-
     """
 
     _CONDITIONAL_DEPENDENCIES: ClassVar[ConditionalDependencies] = [
         {
-            "using": "afni",
-            "depends_on": AFNIALFF,
+            "using": ALFFImpl.afni,
+            "depends_on": [AFNIALFF],
         },
         {
-            "using": "junifer",
-            "depends_on": JuniferALFF,
+            "using": ALFFImpl.junifer,
+            "depends_on": [JuniferALFF],
         },
     ]
 
     _MARKER_INOUT_MAPPINGS: ClassVar[MarkerInOutMappings] = {
-        "BOLD": {
-            "alff": "vector",
-            "falff": "vector",
+        DataType.BOLD: {
+            "alff": StorageType.Vector,
+            "falff": StorageType.Vector,
         },
     }
 
-    def __init__(
-        self,
-        highpass: float,
-        lowpass: float,
-        using: str,
-        tr: Optional[float] = None,
-        name: Optional[str] = None,
-    ) -> None:
-        if highpass < 0:
-            raise_error("Highpass must be positive or 0")
-        if lowpass <= 0:
-            raise_error("Lowpass must be positive")
-        if highpass >= lowpass:
-            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
-        super().__init__(on="BOLD", name=name)
+    using: ALFFImpl
+    highpass: PositiveFloat = 0.01
+    lowpass: PositiveFloat = 0.1
+    tr: PositiveFloat | None = None
+    agg_method: str = "mean"
+    agg_method_params: dict | None = None
+    masks: Annotated[
+        dict | str | list[dict | str] | None,
+        BeforeValidator(ensure_list_or_none),
+    ] = None
 
     def _compute(
         self,
         input_data: dict[str, Any],
+        extra_input: dict[str, Any] | None = None,
     ) -> tuple["Nifti1Image", "Nifti1Image", Path, Path]:
         """Compute ALFF and fALFF.
 
@@ -123,7 +128,8 @@ class ALFFBase(BaseMarker):
         input_data : dict
             The input to the marker.
         extra_input : dict, optional
-            The other fields in the pipeline data object (default None).
+            The other fields in the pipeline data object. Used to compute
+            the mask in the space of ``input_data`` (default None).
 
         Returns
         -------
@@ -144,12 +150,26 @@ class ALFFBase(BaseMarker):
             estimator = AFNIALFF()
         elif self.using == "junifer":
             estimator = JuniferALFF()
+        # Get mask in the space of the input data
+        mask_path = None
+        if self.masks is not None:
+            logger.debug(f"Masking with {self.masks}")
+            mask_path = _save_mask(
+                get_data(
+                    kind="mask",
+                    names=self.masks,
+                    target_data=input_data,
+                    extra_input=extra_input,
+                ),
+                prefix="alff_mask",
+            )
         # Compute ALFF + fALFF
         alff, falff, alff_path, falff_path = estimator.compute(  # type: ignore
             input_path=input_data["path"],
             highpass=self.highpass,
             lowpass=self.lowpass,
             tr=self.tr,
+            mask_path=mask_path,
         )
 
         # If the input data space is native already, the original path should

junifer/markers/falff/falff_maps.py

@@ -3,10 +3,11 @@
 # Authors: Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
-from typing import Any, Optional, Union
+from typing import Any
 
 from ...api.decorators import register_marker
-from ...utils import logger
+from ...datagrabber import DataType
+from ..base import logger
 from ..maps_aggregation import MapsAggregation
 from .falff_base import ALFFBase
 
@@ -23,27 +24,21 @@ class ALFFMaps(ALFFBase):
     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``
-
+    using : :enum:`.ALFFImpl`
     highpass : positive float, optional
-        The highpass cutoff frequency for the bandpass filter. If 0,
-        it will not apply a highpass filter (default 0.01).
+        Highpass cutoff frequency (default 0.01).
     lowpass : positive float, optional
-        The lowpass cutoff frequency for the bandpass filter (default 0.1).
+        Lowpass cutoff frequency (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 repetition time of the BOLD data.
+        If None, will extract the TR from NIfTI header (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, will use the class name (default
-        None).
+    name : str or None, optional
+        The name of the marker.
+        If None, will use the class name (default None).
 
     Notes
     -----
@@ -59,31 +54,12 @@ class ALFFMaps(ALFFBase):
 
     """
 
-    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
+    maps: str
 
     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.
 
@@ -116,7 +92,7 @@ class ALFFMaps(ALFFBase):
 
         # Compute ALFF + fALFF
         alff_output, falff_output, alff_output_path, falff_output_path = (
-            self._compute(input_data=input)
+            self._compute(input_data=input, extra_input=extra_input)
         )
 
         # Perform aggregation on ALFF + fALFF
@@ -132,7 +108,7 @@ class ALFFMaps(ALFFBase):
                 **MapsAggregation(
                     maps=self.maps,
                     masks=self.masks,
-                    on="BOLD",
+                    on=DataType.BOLD,
                 ).compute(
                     input=aggregation_alff_input,
                     extra_input=extra_input,
@@ -142,7 +118,7 @@ class ALFFMaps(ALFFBase):
                 **MapsAggregation(
                     maps=self.maps,
                     masks=self.masks,
-                    on="BOLD",
+                    on=DataType.BOLD,
                 ).compute(
                     input=aggregation_falff_input,
                     extra_input=extra_input,