junifer 0.0.5__py3-none-any.whl → 0.0.5.dev24__py3-none-any.whl

junifer/preprocess/confounds/fmriprep_confound_remover.py

@@ -27,9 +27,6 @@ from ...utils import logger, raise_error
 from ..base import BasePreprocessor
 
 
-__all__ = ["fMRIPrepConfoundRemover"]
-
-
 FMRIPREP_BASICS = {
     "motion": [
         "trans_x",
@@ -206,7 +203,9 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
                 "include it in the future",
                 klass=ValueError,
             )
-        super().__init__(on="BOLD", required_data_types=["BOLD"])
+        super().__init__(
+            on="BOLD", required_data_types=["BOLD", "BOLD_confounds"]
+        )
 
     def get_valid_inputs(self) -> List[str]:
         """Get valid data types for input.
@@ -362,7 +361,7 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
         Parameters
         ----------
         input : dict
-            Dictionary containing the ``BOLD.confounds`` value from the
+            Dictionary containing the ``BOLD_confounds`` value from the
             Junifer Data object.
 
         Returns
@@ -371,6 +370,7 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
             Dataframe containing the relevant confounds.
 
         """
+
         confounds_format = input["format"]
         if confounds_format == "adhoc":
             self._map_adhoc_to_fmriprep(input)
@@ -416,42 +416,50 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
     def _validate_data(
         self,
         input: Dict[str, Any],
+        extra_input: Optional[Dict[str, Any]] = None,
     ) -> None:
         """Validate input data.
 
         Parameters
         ----------
         input : dict
-            Dictionary containing the ``BOLD`` data from the
+            Dictionary containing the ``BOLD`` value from the
             Junifer Data object.
+        extra_input : dict, optional
+            Dictionary containing the rest of the Junifer Data object. Must
+            include the ``BOLD_confounds`` key.
 
         Raises
         ------
         ValueError
-            If ``"confounds"`` is not found in ``input`` or
-            if ``"data"`` key is not found in ``"input.confounds"`` or
-            if ``"input.confounds.data"`` is not pandas.DataFrame or
+            If ``extra_input`` is None or
+            if ``"BOLD_confounds"`` is not found in ``extra_input`` or
+            if ``"data"`` key is not found in ``"BOLD_confounds"`` or
+            if ``"data"`` is not pandas.DataFrame or
             if image time series and confounds have different lengths or
-            if ``format = "adhoc"`` and ``"mappings"`` key is not found or
-            ``"fmriprep"`` key is not found in ``"mappings"`` or
-            ``"fmriprep"`` has incorrect fMRIPrep mappings or required
-            fMRIPrep mappings are not found or
-            if invalid confounds format is found.
+            if ``"format"`` is not found in ``"BOLD_confounds"`` or
+            if ``format = "adhoc"`` and ``"mappings"`` key or ``"fmriprep"``
+            key or correct fMRIPrep mappings or required fMRIPrep mappings are
+            not found or if invalid confounds format is found.
 
         """
         # BOLD must be 4D niimg
         check_niimg_4d(input["data"])
-        # Check for confound data
-        if "confounds" not in input:
-            raise_error("`BOLD.confounds` data type not provided")
-        if "data" not in input["confounds"]:
-            raise_error("`BOLD.confounds.data` not provided")
-        # Confounds must be a pandas.DataFrame;
-        # if extension is unknown, will not be read, which will give None
-        if not isinstance(input["confounds"]["data"], pd.DataFrame):
-            raise_error("`BOLD.confounds.data` must be a `pandas.DataFrame`")
-
-        confound_df = input["confounds"]["data"]
+        # Check for extra inputs
+        if extra_input is None:
+            raise_error(
+                "No extra input provided, requires `BOLD_confounds` data type "
+                "in particular"
+            )
+        if "BOLD_confounds" not in extra_input:
+            raise_error("`BOLD_confounds` data type not provided")
+        if "data" not in extra_input["BOLD_confounds"]:
+            raise_error("`BOLD_confounds.data` not provided")
+        # Confounds must be a pandas.DataFrame
+        if not isinstance(extra_input["BOLD_confounds"]["data"], pd.DataFrame):
+            raise_error("`BOLD_confounds.data` must be a `pandas.DataFrame`")
+
+        confound_df = extra_input["BOLD_confounds"]["data"]
         bold_img = input["data"]
         if bold_img.get_fdata().shape[3] != len(confound_df):
             raise_error(
@@ -461,19 +469,23 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
             )
 
         # Check format
-        t_format = input["confounds"]["format"]
+        if "format" not in extra_input["BOLD_confounds"]:
+            raise_error("`BOLD_confounds.format` not provided")
+        t_format = extra_input["BOLD_confounds"]["format"]
         if t_format == "adhoc":
-            if "mappings" not in input["confounds"]:
+            if "mappings" not in extra_input["BOLD_confounds"]:
                 raise_error(
-                    "`BOLD.confounds.mappings` need to be set when "
-                    "`BOLD.confounds.format == 'adhoc'`"
+                    "`BOLD_confounds.mappings` need to be set when "
+                    "`BOLD_confounds.format == 'adhoc'`"
                 )
-            if "fmriprep" not in input["confounds"]["mappings"]:
+            if "fmriprep" not in extra_input["BOLD_confounds"]["mappings"]:
                 raise_error(
-                    "`BOLD.confounds.mappings.fmriprep` need to be set when "
-                    "`BOLD.confounds.format == 'adhoc'`"
+                    "`BOLD_confounds.mappings.fmriprep` need to be set when "
+                    "`BOLD_confounds.format == 'adhoc'`"
                 )
-            fmriprep_mappings = input["confounds"]["mappings"]["fmriprep"]
+            fmriprep_mappings = extra_input["BOLD_confounds"]["mappings"][
+                "fmriprep"
+            ]
             wrong_names = [
                 x
                 for x in fmriprep_mappings.values()
@@ -513,22 +525,22 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
         input : dict
             A single input from the Junifer Data object to preprocess.
         extra_input : dict, optional
-            The other fields in the Junifer Data object.
+            The other fields in the Junifer Data object. Must include the
+            ``BOLD_confounds`` key.
 
         Returns
         -------
         dict
-            The computed result as dictionary. If `self.masks` is not None,
-            then the target data computed mask is updated for further steps.
-        None
-            Extra "helper" data types as dictionary to add to the Junifer Data
-            object.
+            The computed result as dictionary.
+        dict or None
+            If `self.masks` is not None, then the target data computed mask is
+            returned else None.
 
         """
         # Validate data
-        self._validate_data(input)
+        self._validate_data(input, extra_input)
         # Pick confounds
-        confounds_df = self._pick_confounds(input["confounds"])  # type: ignore
+        confounds_df = self._pick_confounds(extra_input["BOLD_confounds"])  # type: ignore
         # Get BOLD data
         bold_img = input["data"]
         # Set t_r
@@ -541,6 +553,7 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
             )
         # Set mask data
         mask_img = None
+        bold_mask_dict = None
         if self.masks is not None:
             logger.debug(f"Masking with {self.masks}")
             mask_img = get_mask(
@@ -548,15 +561,15 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
             )
             # Return the BOLD mask and link it to the BOLD data type dict;
             # this allows to use "inherit" down the pipeline
-            logger.debug("Setting `BOLD.mask`")
-            input.update(
-                {
-                    "mask": {
+            if extra_input is not None:
+                logger.debug("Setting `BOLD.mask_item`")
+                input["mask_item"] = "BOLD_mask"
+                bold_mask_dict = {
+                    "BOLD_mask": {
                         "data": mask_img,
                         "space": input["space"],
                     }
                 }
-            )
         # Clean image
         logger.info("Cleaning image using nilearn")
         logger.debug(f"\tdetrend: {self.detrend}")
@@ -574,4 +587,4 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
             mask_img=mask_img,
         )
 
-        return input, None
+        return input, bold_mask_dict

junifer/preprocess/confounds/tests/test_fmriprep_confound_remover.py

@@ -20,7 +20,6 @@ from junifer.testing import get_testing_data
 from junifer.testing.datagrabbers import (
     OasisVBMTestingDataGrabber,
     PartlyCloudyTestingDataGrabber,
-    SPMAuditoryTestingDataGrabber,
 )
 
 
@@ -43,10 +42,35 @@ def test_fMRIPrepConfoundRemover_init() -> None:
 @pytest.mark.parametrize(
     "input_",
     [
+        ["T1w"],
         ["BOLD"],
         ["T1w", "BOLD"],
     ],
 )
+def test_fMRIPrepConfoundRemover_validate_input_errors(
+    input_: List[str],
+) -> None:
+    """Test errors for fMRIPrepConfoundRemover validate_input.
+
+    Parameters
+    ----------
+    input_ : list of str
+        The input data types.
+
+    """
+    confound_remover = fMRIPrepConfoundRemover()
+
+    with pytest.raises(ValueError, match="not have the required data"):
+        confound_remover.validate_input(input_)
+
+
+@pytest.mark.parametrize(
+    "input_",
+    [
+        ["BOLD", "BOLD_confounds"],
+        ["T1w", "BOLD", "BOLD_confounds"],
+    ],
+)
 def test_fMRIPrepConfoundRemover_validate_input(input_: List[str]) -> None:
     """Test fMRIPrepConfoundRemover validate_input.
 
@@ -278,13 +302,13 @@ def test_fMRIPRepConfoundRemover__pick_confounds_fmriprep() -> None:
     with PartlyCloudyTestingDataGrabber() as dg:
         input = dg["sub-01"]
         input = reader.fit_transform(input)
-        out1 = confound_remover._pick_confounds(input["BOLD"]["confounds"])
+        out1 = confound_remover._pick_confounds(input["BOLD_confounds"])
         assert set(out1.columns) == {*fmriprep_all_vars, "spike"}
 
     with PartlyCloudyTestingDataGrabber(reduce_confounds=False) as dg:
         input = dg["sub-01"]
         input = reader.fit_transform(input)
-        out2 = confound_remover._pick_confounds(input["BOLD"]["confounds"])
+        out2 = confound_remover._pick_confounds(input["BOLD_confounds"])
         assert set(out2.columns) == {*fmriprep_all_vars, "spike"}
 
     assert_frame_equal(out1, out2)
@@ -324,106 +348,123 @@ def test_fMRIPRepConfoundRemover__pick_confounds_fmriprep_compute() -> None:
 def test_fMRIPrepConfoundRemover__validate_data() -> None:
     """Test fMRIPrepConfoundRemover validate data."""
     confound_remover = fMRIPrepConfoundRemover(strategy={"wm_csf": "full"})
-    # Check correct data type
+
     with OasisVBMTestingDataGrabber() as dg:
         element_data = DefaultDataReader().fit_transform(dg["sub-01"])
         vbm = element_data["VBM_GM"]
         with pytest.raises(
             DimensionError, match="incompatible dimensionality"
         ):
-            confound_remover._validate_data(vbm)
-    # Check missing nested type in correct data type
-    with SPMAuditoryTestingDataGrabber() as dg:
+            confound_remover._validate_data(vbm, None)
+
+    with PartlyCloudyTestingDataGrabber(reduce_confounds=False) as dg:
         element_data = DefaultDataReader().fit_transform(dg["sub-01"])
         bold = element_data["BOLD"]
-        # Test confound type
+
+        with pytest.raises(ValueError, match="No extra input"):
+            confound_remover._validate_data(bold, None)
         with pytest.raises(
-            ValueError, match="`BOLD.confounds` data type not provided"
+            ValueError, match="`BOLD_confounds` data type not provided"
         ):
-            confound_remover._validate_data(bold)
-        # Test confound data
-        bold["confounds"] = {}
+            confound_remover._validate_data(bold, {})
         with pytest.raises(
-            ValueError, match="`BOLD.confounds.data` not provided"
+            ValueError, match="`BOLD_confounds.data` not provided"
         ):
-            confound_remover._validate_data(bold)
-        # Test confound data is valid type
-        bold["confounds"] = {"data": None}
-        with pytest.raises(ValueError, match="must be a `pandas.DataFrame`"):
-            confound_remover._validate_data(bold)
-        # Test confound data dimension mismatch with BOLD
-        bold["confounds"] = {"data": pd.DataFrame()}
+            confound_remover._validate_data(bold, {"BOLD_confounds": {}})
+
+        extra_input = {
+            "BOLD_confounds": {"data": "wrong"},
+        }
+        msg = "must be a `pandas.DataFrame`"
+        with pytest.raises(ValueError, match=msg):
+            confound_remover._validate_data(bold, extra_input)
+
+        extra_input = {"BOLD_confounds": {"data": pd.DataFrame()}}
         with pytest.raises(ValueError, match="Image time series and"):
-            confound_remover._validate_data(bold)
-    # Check nested type variations
-    with PartlyCloudyTestingDataGrabber(reduce_confounds=False) as dg:
-        element_data = DefaultDataReader().fit_transform(dg["sub-01"])
-        # Test format
-        modified_bold = {
-            "data": element_data["BOLD"]["data"],
-            "confounds": {
-                "data": element_data["BOLD"]["confounds"]["data"],
-                "format": "adhoc",
-            },
+            confound_remover._validate_data(bold, extra_input)
+
+        extra_input = {
+            "BOLD_confounds": {"data": element_data["BOLD_confounds"]["data"]}
         }
-        # Test incorrect format
-        modified_bold["confounds"].update({"format": "wrong"})
-        with pytest.raises(ValueError, match="Invalid confounds format"):
-            confound_remover._validate_data(modified_bold)
-        # Test missing mappings for adhoc
-        modified_bold["confounds"].update({"format": "adhoc"})
         with pytest.raises(
-            ValueError, match="`BOLD.confounds.mappings` need to be set"
+            ValueError, match="`BOLD_confounds.format` not provided"
         ):
-            confound_remover._validate_data(modified_bold)
-        # Test missing fmriprep mappings for adhoc
-        modified_bold["confounds"].update({"mappings": {}})
-        with pytest.raises(
-            ValueError,
-            match="`BOLD.confounds.mappings.fmriprep` need to be set",
-        ):
-            confound_remover._validate_data(modified_bold)
-        # Test incorrect fmriprep mappings for adhoc
-        modified_bold["confounds"].update(
-            {
+            confound_remover._validate_data(bold, extra_input)
+
+        extra_input = {
+            "BOLD_confounds": {
+                "data": element_data["BOLD_confounds"]["data"],
+                "format": "wrong",
+            }
+        }
+        with pytest.raises(ValueError, match="Invalid confounds format"):
+            confound_remover._validate_data(bold, extra_input)
+
+        extra_input = {
+            "BOLD_confounds": {
+                "data": element_data["BOLD_confounds"]["data"],
+                "format": "adhoc",
+            }
+        }
+        with pytest.raises(ValueError, match="need to be set"):
+            confound_remover._validate_data(bold, extra_input)
+
+        extra_input = {
+            "BOLD_confounds": {
+                "data": element_data["BOLD_confounds"]["data"],
+                "format": "adhoc",
+                "mappings": {},
+            }
+        }
+        with pytest.raises(ValueError, match="need to be set"):
+            confound_remover._validate_data(bold, extra_input)
+
+        extra_input = {
+            "BOLD_confounds": {
+                "data": element_data["BOLD_confounds"]["data"],
+                "format": "adhoc",
                 "mappings": {
                     "fmriprep": {
                         "rot_x": "wrong",
                         "rot_y": "rot_z",
                         "rot_z": "rot_y",
-                    },
-                }
+                    }
+                },
             }
-        )
+        }
         with pytest.raises(ValueError, match=r"names: \['wrong'\]"):
-            confound_remover._validate_data(modified_bold)
-        # Test missing fmriprep mappings for adhoc
-        modified_bold["confounds"].update(
-            {
+            confound_remover._validate_data(bold, extra_input)
+
+        extra_input = {
+            "BOLD_confounds": {
+                "data": element_data["BOLD_confounds"]["data"],
+                "format": "adhoc",
                 "mappings": {
                     "fmriprep": {
                         "wrong": "rot_x",
                         "rot_y": "rot_z",
                         "rot_z": "rot_y",
-                    },
-                }
+                    }
+                },
             }
-        )
+        }
         with pytest.raises(ValueError, match=r"Missing columns: \['wrong'\]"):
-            confound_remover._validate_data(modified_bold)
-        # Test correct adhoc format
-        modified_bold["confounds"].update(
-            {
+            confound_remover._validate_data(bold, extra_input)
+
+        extra_input = {
+            "BOLD_confounds": {
+                "data": element_data["BOLD_confounds"]["data"],
+                "format": "adhoc",
                 "mappings": {
                     "fmriprep": {
                         "rot_x": "rot_x",
                         "rot_y": "rot_z",
                         "rot_z": "rot_y",
-                    },
-                }
+                    }
+                },
             }
-        )
-        confound_remover._validate_data(modified_bold)
+        }
+        confound_remover._validate_data(bold, extra_input)
 
 
 def test_fMRIPrepConfoundRemover_preprocess() -> None:
@@ -435,9 +476,7 @@ def test_fMRIPrepConfoundRemover_preprocess() -> None:
         element_data = DefaultDataReader().fit_transform(dg["sub-01"])
         orig_bold = element_data["BOLD"]["data"].get_fdata().copy()
         pre_input = element_data["BOLD"]
-        pre_extra_input = {
-            "BOLD": {"confounds": element_data["BOLD"]["confounds"]}
-        }
+        pre_extra_input = {"BOLD_confounds": element_data["BOLD_confounds"]}
         output, _ = confound_remover.preprocess(pre_input, pre_extra_input)
         trans_bold = output["data"].get_fdata()
         # Transformation is in place
@@ -491,7 +530,7 @@ def test_fMRIPrepConfoundRemover_fit_transform() -> None:
         assert t_meta["t_r"] is None
         assert t_meta["masks"] is None
 
-        assert "mask" not in output["BOLD"]
+        assert "BOLD_mask" not in output
 
         assert "dependencies" in output["BOLD"]["meta"]
         dependencies = output["BOLD"]["meta"]["dependencies"]
@@ -543,7 +582,9 @@ def test_fMRIPrepConfoundRemover_fit_transform_masks() -> None:
         assert "threshold" in t_meta["masks"]["compute_brain_mask"]
         assert t_meta["masks"]["compute_brain_mask"]["threshold"] == 0.2
 
-        assert "mask" in output["BOLD"]
+        assert "BOLD_mask" in output
+        assert "mask_item" in output["BOLD"]
+        assert output["BOLD"]["mask_item"] == "BOLD_mask"
 
         assert "dependencies" in output["BOLD"]["meta"]
         dependencies = output["BOLD"]["meta"]["dependencies"]

junifer/preprocess/fsl/__init__.py

@@ -0,0 +1,4 @@
+"""Provide imports for fsl sub-package."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL

junifer/preprocess/fsl/apply_warper.py

@@ -0,0 +1,179 @@
+"""Provide class for warping via FSL FLIRT."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Union,
+)
+
+import nibabel as nib
+import numpy as np
+
+from ...pipeline import WorkDirManager
+from ...utils import logger, raise_error, run_ext_cmd
+
+
+if TYPE_CHECKING:
+    from nibabel import Nifti1Image
+
+
+class _ApplyWarper:
+    """Class for warping NIfTI images via FSL FLIRT.
+
+    Wraps FSL FLIRT ``applywarp``.
+
+    Parameters
+    ----------
+    reference : str
+        The data type to use as reference for warping.
+    on : str
+        The data type to use for warping.
+
+    Raises
+    ------
+    ValueError
+        If a list was passed for ``on``.
+
+    """
+
+    _EXT_DEPENDENCIES: ClassVar[List[Dict[str, Union[str, List[str]]]]] = [
+        {
+            "name": "fsl",
+            "commands": ["flirt", "applywarp"],
+        },
+    ]
+
+    def __init__(self, reference: str, on: str) -> None:
+        """Initialize the class."""
+        self.ref = reference
+        # Check only single data type is passed
+        if isinstance(on, list):
+            raise_error("Can only work on single data type, list was passed.")
+        self.on = on
+
+    def _run_applywarp(
+        self,
+        input_data: Dict,
+        ref_path: Path,
+        warp_path: Path,
+    ) -> Tuple["Nifti1Image", Path]:
+        """Run ``applywarp``.
+
+        Parameters
+        ----------
+        input_data : dict
+            The input data.
+        ref_path : pathlib.Path
+            The path to the reference file.
+        warp_path : pathlib.Path
+            The path to the warp file.
+
+        Returns
+        -------
+        Niimg-like object
+            The warped input image.
+        pathlib.Path
+            The path to the resampled reference image.
+
+        """
+        # Get the min of the voxel sizes from input and use it as the
+        # resolution
+        resolution = np.min(input_data["data"].header.get_zooms()[:3])
+
+        # Create element-specific tempdir for storing post-warping assets
+        tempdir = WorkDirManager().get_element_tempdir(prefix="applywarp")
+
+        # Create a tempfile for resampled reference output
+        flirt_out_path = tempdir / "reference_resampled.nii.gz"
+        # Set flirt command
+        flirt_cmd = [
+            "flirt",
+            "-interp spline",
+            f"-in {ref_path.resolve()}",
+            f"-ref {ref_path.resolve()}",
+            f"-applyisoxfm {resolution}",
+            f"-out {flirt_out_path.resolve()}",
+        ]
+        # Call flirt
+        run_ext_cmd(name="flirt", cmd=flirt_cmd)
+
+        # Create a tempfile for warped output
+        applywarp_out_path = tempdir / "input_warped.nii.gz"
+        # Set applywarp command
+        applywarp_cmd = [
+            "applywarp",
+            "--interp=spline",
+            f"-i {input_data['path'].resolve()}",
+            f"-r {flirt_out_path.resolve()}",  # use resampled reference
+            f"-w {warp_path.resolve()}",
+            f"-o {applywarp_out_path.resolve()}",
+        ]
+        # Call applywarp
+        run_ext_cmd(name="applywarp", cmd=applywarp_cmd)
+
+        # Load nifti
+        output_img = nib.load(applywarp_out_path)
+
+        return output_img, flirt_out_path  # type: ignore
+
+    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 in which to preprocess.
+        extra_input : dict, optional
+            The other fields in the Junifer Data object. Must include the
+            ``Warp`` and ``ref`` value's keys.
+
+        Returns
+        -------
+        str
+            The key to store the output in the Junifer Data object.
+        dict
+            The computed result as dictionary. This will be stored in the
+            Junifer Data object under the key ``data`` of the data type.
+
+        Raises
+        ------
+        ValueError
+            If ``extra_input`` is None.
+
+        """
+        logger.debug("Warping via FSL using ApplyWarper")
+        # Check for extra inputs
+        if extra_input is None:
+            raise_error(
+                f"No extra input provided, requires `Warp` and `{self.ref}` "
+                "data types in particular."
+            )
+        # Retrieve data type info to warp
+        to_warp_input = input
+        # Retrieve data type info to use as reference
+        ref_input = extra_input[self.ref]
+        # Retrieve Warp data
+        warp = extra_input["Warp"]
+        # Replace original data with warped data and add resampled reference
+        # path
+        input["data"], input["reference_path"] = self._run_applywarp(
+            input_data=to_warp_input,
+            ref_path=ref_input["path"],
+            warp_path=warp["path"],
+        )
+        # Use reference input's space as warped input's space
+        input["space"] = ref_input["space"]
+        return self.on, input