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

junifer/preprocess/ants/tests/test_ants_apply_transforms_warper.py

@@ -0,0 +1,56 @@
+"""Provide tests for AntsApplyTransformsWarper."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+import socket
+
+import pytest
+
+from junifer.datagrabber import DMCC13Benchmark
+from junifer.datareader import DefaultDataReader
+from junifer.pipeline.utils import _check_ants
+from junifer.preprocess.ants.ants_apply_transforms_warper import (
+    _AntsApplyTransformsWarper,
+)
+
+
+def test_AntsApplyTransformsWarper_init() -> None:
+    """Test AntsApplyTransformsWarper init."""
+    ants_apply_transforms_warper = _AntsApplyTransformsWarper(
+        reference="T1w", on="BOLD"
+    )
+    assert ants_apply_transforms_warper.ref == "T1w"
+    assert ants_apply_transforms_warper.on == "BOLD"
+
+
+@pytest.mark.skipif(
+    _check_ants() is False, reason="requires ANTs to be in PATH"
+)
+@pytest.mark.skipif(
+    socket.gethostname() != "juseless",
+    reason="only for juseless",
+)
+def test_AntsApplyTransformsWarper_preprocess() -> None:
+    """Test AntsApplyTransformsWarper preprocess."""
+    with DMCC13Benchmark(
+        types=["BOLD", "T1w", "Warp"],
+        sessions=["ses-wave1bas"],
+        tasks=["Rest"],
+        phase_encodings=["AP"],
+        runs=["1"],
+        native_t1w=True,
+    ) as dg:
+        # Read data
+        element_data = DefaultDataReader().fit_transform(
+            dg[("sub-f9057kp", "ses-wave1bas", "Rest", "AP", "1")]
+        )
+        # Preprocess data
+        data_type, data = _AntsApplyTransformsWarper(
+            reference="T1w", on="BOLD"
+        ).preprocess(
+            input=element_data["BOLD"],
+            extra_input=element_data,
+        )
+        assert isinstance(data_type, str)
+        assert isinstance(data, dict)

junifer/preprocess/base.py

@@ -12,29 +12,50 @@ from ..utils import logger, raise_error
 
 
 class BasePreprocessor(ABC, PipelineStepMixin, UpdateMetaMixin):
-    """Provide abstract base class for all preprocessors.
+    """Abstract base class for all preprocessors.
+
+    For every interface that is required, one needs to provide a concrete
+    implementation of this abstract class.
 
     Parameters
     ----------
-    on : str or list of str, optional
-        The kind of data to apply the preprocessor to. If None,
-        will work on all available data (default None).
+    on : str or list of str or None, optional
+        The data type to apply the preprocessor on. If None,
+        will work on all available data types (default None).
+    required_data_types : str or list of str, optional
+        The data types needed for computation. If None,
+        will be equal to ``on`` (default None).
+
+    Raises
+    ------
+    ValueError
+        If required input data type(s) is(are) not found.
+
     """
 
     def __init__(
         self,
         on: Optional[Union[List[str], str]] = None,
+        required_data_types: Optional[Union[List[str], str]] = None,
     ) -> None:
+        """Initialize the class."""
+        # Use all data types if not provided
         if on is None:
             on = self.get_valid_inputs()
+        # Convert data types to list
         if not isinstance(on, list):
             on = [on]
-
+        # Check if required inputs are found
         if any(x not in self.get_valid_inputs() for x in on):
             name = self.__class__.__name__
             wrong_on = [x for x in on if x not in self.get_valid_inputs()]
-            raise ValueError(f"{name} cannot be computed on {wrong_on}")
+            raise_error(f"{name} cannot be computed on {wrong_on}")
         self._on = on
+        # Set required data types for validation
+        if required_data_types is None:
+            self._required_data_types = on
+        else:
+            self._required_data_types = required_data_types
 
     def validate_input(self, input: List[str]) -> List[str]:
         """Validate input.
@@ -55,30 +76,45 @@ class BasePreprocessor(ABC, PipelineStepMixin, UpdateMetaMixin):
         ------
         ValueError
             If the input does not have the required data.
+
         """
-        if not any(x in input for x in self._on):
+        if any(x not in input for x in self._required_data_types):
             raise_error(
                 "Input does not have the required data."
                 f"\t Input: {input}"
-                f"\t Required (any of): {self._on}"
+                f"\t Required (all of): {self._required_data_types}"
             )
         return [x for x in self._on if x in input]
 
     @abstractmethod
-    def get_output_type(self, input: List[str]) -> List[str]:
+    def get_valid_inputs(self) -> List[str]:
+        """Get valid data types for input.
+
+        Returns
+        -------
+        list of str
+            The list of data types that can be used as input for this
+            preprocessor.
+
+        """
+        raise_error(
+            msg="Concrete classes need to implement get_valid_inputs().",
+            klass=NotImplementedError,
+        )
+
+    @abstractmethod
+    def get_output_type(self, input_type: str) -> str:
         """Get output type.
 
         Parameters
         ----------
-        input : list of str
-            The input to the preprocessor. The list must contain the
-            available Junifer Data dictionary keys.
+        input_type : str
+            The data type input to the preprocessor.
 
         Returns
         -------
-        list of str
-            The updated list of available Junifer Data object keys after
-            the pipeline step.
+        str
+            The data type output by the preprocessor.
 
         """
         raise_error(
@@ -87,17 +123,35 @@ class BasePreprocessor(ABC, PipelineStepMixin, UpdateMetaMixin):
         )
 
     @abstractmethod
-    def get_valid_inputs(self) -> List[str]:
-        """Get valid data types for input.
+    def preprocess(
+        self,
+        input: Dict[str, Any],
+        extra_input: Optional[Dict[str, Any]] = None,
+    ) -> Tuple[Dict[str, Any], Optional[Dict[str, Dict[str, Any]]]]:
+        """Preprocess.
+
+        Parameters
+        ----------
+        input : dict
+            A single input from the Junifer Data object to preprocess.
+        extra_input : dict, optional
+            The other fields in the Junifer Data object. Useful for accessing
+            other data kind that needs to be used in the computation. For
+            example, the confound removers can make use of the
+            confounds if available (default None).
 
         Returns
         -------
-        list of str
-            The list of data types that can be used as input for this
-            preprocessor.
+        dict
+            The computed result as dictionary.
+        dict or None
+            Extra "helper" data types as dictionary to add to the Junifer Data
+            object. For example, computed BOLD mask can be passed via this.
+            If no new "helper" data types is created, None is to be passed.
+
         """
         raise_error(
-            msg="Concrete classes need to implement get_valid_inputs().",
+            msg="Concrete classes need to implement preprocess().",
             klass=NotImplementedError,
         )
 
@@ -118,63 +172,36 @@ class BasePreprocessor(ABC, PipelineStepMixin, UpdateMetaMixin):
             The processed output as a dictionary.
 
         """
-        out = input
+        # Copy input to not modify the original
+        out = input.copy()
+        # For each data type, run preprocessing
         for type_ in self._on:
+            # Check if data type is available
             if type_ in input.keys():
                 logger.info(f"Preprocessing {type_}")
+                # Get data dict for data type
                 t_input = input[type_]
-
                 # Pass the other data types as extra input, removing
                 # the current type
-                extra_input = input
+                extra_input = input.copy()
                 extra_input.pop(type_)
                 logger.debug(
-                    f"Extra input for preprocess: {extra_input.keys()}"
+                    f"Extra data type for preprocess: {extra_input.keys()}"
                 )
-                key, t_out = self.preprocess(
+                # Preprocess data
+                t_out, t_extra_input = self.preprocess(
                     input=t_input, extra_input=extra_input
                 )
-
-                # Add the output to the Junifer Data object
-                logger.debug(f"Adding {key} to output")
-                out[key] = t_out
-
-                # In case we are creating a new type, re-add the original input
-                if key != type_:
-                    logger.debug("Adding original input back to output")
-                    out[type_] = t_input
-
-                self.update_meta(out[key], "preprocess")
+                # Set output to the Junifer Data object
+                logger.debug(f"Adding {type_} to output")
+                out[type_] = t_out
+                # Check if helper data types are to be added
+                if t_extra_input is not None:
+                    logger.debug(
+                        f"Adding helper data types: {t_extra_input.keys()} "
+                        "to output"
+                    )
+                    out.update(t_extra_input)
+                # Update metadata for step
+                self.update_meta(out[type_], "preprocess")
         return out
-
-    @abstractmethod
-    def preprocess(
-        self,
-        input: Dict[str, Any],
-        extra_input: Optional[Dict[str, Any]] = None,
-    ) -> Tuple[str, Dict[str, Any]]:
-        """Preprocess.
-
-        Parameters
-        ----------
-        input : dict
-            A single input from the Junifer Data object to preprocess.
-        extra_input : dict, optional
-            The other fields in the Junifer Data object. Useful for accessing
-            other data kind that needs to be used in the computation. For
-            example, the confound removers can make use of the
-            confounds if available (default None).
-
-        Returns
-        -------
-        key : str
-            The key to store the output in the Junifer Data object.
-        object : dict
-            The computed result as dictionary. This will be stored in the
-            Junifer Data object under the key 'key'.
-
-        """
-        raise_error(
-            msg="Concrete classes need to implement preprocess().",
-            klass=NotImplementedError,
-        )

junifer/preprocess/bold_warper.py

@@ -0,0 +1,265 @@
+"""Provide class for warping BOLD to other template spaces."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from typing import (
+    Any,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Type,
+    Union,
+)
+
+import nibabel as nib
+from templateflow import api as tflow
+
+from ..api.decorators import register_preprocessor
+from ..data import get_template, get_xfm
+from ..pipeline import WorkDirManager
+from ..utils import logger, raise_error, run_ext_cmd
+from .ants.ants_apply_transforms_warper import _AntsApplyTransformsWarper
+from .base import BasePreprocessor
+from .fsl.apply_warper import _ApplyWarper
+
+
+@register_preprocessor
+class BOLDWarper(BasePreprocessor):
+    """Class for warping BOLD NIfTI images.
+
+    .. deprecated:: 0.0.3
+              `BOLDWarper` will be removed in v0.0.4, it is replaced by
+              `SpaceWarper` because the latter works also with T1w data.
+
+    Parameters
+    ----------
+    using : {"fsl", "ants"}
+        Implementation to use for warping:
+
+        * "fsl" : Use FSL's ``applywarp``
+        * "afni" : Use ANTs' ``antsApplyTransforms``
+
+    reference : str
+        The data type to use as reference for warping, can be either a data
+        type like "T1w" or a template space like "MNI152NLin2009cAsym".
+
+    Raises
+    ------
+    ValueError
+        If ``using`` is invalid or
+        if ``reference`` is invalid.
+
+    Notes
+    -----
+    If you are setting ``reference`` to a template space like
+    "MNI152NLin2009cAsym", make sure ANTs is available for the
+    transformation else it will fail during runtime. It is tricky to validate
+    this beforehand and difficult to enforce this as a requirement, hence the
+    heads-up.
+
+    """
+
+    _CONDITIONAL_DEPENDENCIES: ClassVar[List[Dict[str, Union[str, Type]]]] = [
+        {
+            "using": "fsl",
+            "depends_on": _ApplyWarper,
+        },
+        {
+            "using": "ants",
+            "depends_on": _AntsApplyTransformsWarper,
+        },
+    ]
+
+    def __init__(self, using: str, reference: str) -> None:
+        """Initialize the class."""
+        # 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.ref = reference
+        # Initialize superclass based on reference
+        if self.ref == "T1w":
+            super().__init__(
+                on="BOLD", required_data_types=["BOLD", self.ref, "Warp"]
+            )
+        elif self.ref in tflow.templates():
+            super().__init__(on="BOLD", required_data_types=["BOLD"])
+        else:
+            raise_error(f"Unknown reference: {self.ref}")
+
+    def get_valid_inputs(self) -> List[str]:
+        """Get valid data types for input.
+
+        Returns
+        -------
+        list of str
+            The list of data types that can be used as input for this
+            preprocessor.
+
+        """
+        return ["BOLD"]
+
+    def get_output_type(self, input_type: str) -> str:
+        """Get output type.
+
+        Parameters
+        ----------
+        input_type : str
+            The data type input to the preprocessor.
+
+        Returns
+        -------
+        str
+            The data type output by the preprocessor.
+
+        """
+        # Does not add any new keys
+        return input_type
+
+    def preprocess(
+        self,
+        input: Dict[str, Any],
+        extra_input: Optional[Dict[str, Any]] = None,
+    ) -> Tuple[Dict[str, Any], Optional[Dict[str, Dict[str, Any]]]]:
+        """Preprocess.
+
+        Parameters
+        ----------
+        input : dict
+            The BOLD input from the Junifer Data object.
+        extra_input : dict, optional
+            The other fields in the Junifer Data object. Must include the
+            ``Warp`` and ``ref`` value's keys if native space transformation is
+            needed.
+
+        Returns
+        -------
+        dict
+            The computed result as dictionary.
+        None
+            Extra "helper" data types as dictionary to add to the Junifer Data
+            object.
+
+        Raises
+        ------
+        ValueError
+            If ``extra_input`` is None when transforming to native space
+            i.e., using "T1w" as reference.
+        RuntimeError
+            If warp / transformation file extension is not ".mat" or ".h5"
+            when transforming to native space or
+            if the BOLD data is in the correct space and does not require
+            warping.
+
+        """
+        logger.info(f"Warping BOLD to {self.ref} space using BOLDWarper")
+        # Transform to native space
+        if self.ref == "T1w":
+            # Check for extra inputs
+            if extra_input is None:
+                raise_error(
+                    "No extra input provided, requires `Warp` and "
+                    f"`{self.ref}` data types in particular."
+                )
+            # Check for warp file type to use correct tool
+            warp_file_ext = extra_input["Warp"]["path"].suffix
+            if warp_file_ext == ".mat":
+                logger.debug("Using FSL with BOLDWarper")
+                # Initialize ApplyWarper for computation
+                apply_warper = _ApplyWarper(reference=self.ref, on="BOLD")
+                # Replace original BOLD data with warped BOLD data
+                _, input = apply_warper.preprocess(
+                    input=input,
+                    extra_input=extra_input,
+                )
+            elif warp_file_ext == ".h5":
+                logger.debug("Using ANTs with BOLDWarper")
+                # Initialize AntsApplyTransformsWarper for computation
+                ants_apply_transforms_warper = _AntsApplyTransformsWarper(
+                    reference=self.ref, on="BOLD"
+                )
+                # Replace original BOLD data with warped BOLD data
+                _, input = ants_apply_transforms_warper.preprocess(
+                    input=input,
+                    extra_input=extra_input,
+                )
+            else:
+                raise_error(
+                    msg=(
+                        "Unknown warp / transformation file extension: "
+                        f"{warp_file_ext}"
+                    ),
+                    klass=RuntimeError,
+                )
+        # Transform to template space
+        else:
+            # Check pre-requirements for space manipulation
+            if self.ref == input["space"]:
+                raise_error(
+                    (
+                        f"Skipped warping as the BOLD data is in {self.ref} "
+                        "space which would mean that you can remove the "
+                        "BOLDWarper from the preprocess step."
+                    ),
+                    klass=RuntimeError,
+                )
+            else:
+                # Get xfm file
+                xfm_file_path = get_xfm(src=input["space"], dst=self.ref)
+                # Get template space image
+                template_space_img = get_template(
+                    space=self.ref,
+                    target_data=input,
+                    extra_input=None,
+                )
+
+                # Create component-scoped tempdir
+                tempdir = WorkDirManager().get_tempdir(prefix="boldwarper")
+                # Create element-scoped tempdir so that warped BOLD is
+                # available later as nibabel stores file path reference for
+                # loading on computation
+                element_tempdir = WorkDirManager().get_element_tempdir(
+                    prefix="boldwarper"
+                )
+
+                # Save template
+                template_space_img_path = tempdir / f"{self.ref}_T1w.nii.gz"
+                nib.save(template_space_img, template_space_img_path)
+
+                # Create a tempfile for warped output
+                warped_bold_path = (
+                    element_tempdir
+                    / f"bold_warped_from_{input['space']}_to_{self.ref}.nii.gz"
+                )
+
+                logger.debug(
+                    f"Using ANTs to warp BOLD "
+                    f"from {input['space']} to {self.ref}"
+                )
+                # Set antsApplyTransforms command
+                apply_transforms_cmd = [
+                    "antsApplyTransforms",
+                    "-d 3",
+                    "-e 3",
+                    "-n LanczosWindowedSinc",
+                    f"-i {input['path'].resolve()}",
+                    f"-r {template_space_img_path.resolve()}",
+                    f"-t {xfm_file_path.resolve()}",
+                    f"-o {warped_bold_path.resolve()}",
+                ]
+                # Call antsApplyTransforms
+                run_ext_cmd(
+                    name="antsApplyTransforms", cmd=apply_transforms_cmd
+                )
+
+                # Modify target data
+                input["data"] = nib.load(warped_bold_path)
+                input["space"] = self.ref
+
+        return input, None