junifer 0.0.4.dev829__py3-none-any.whl → 0.0.5__py3-none-any.whl

junifer/preprocess/confounds/tests/test_fmriprep_confound_remover.py

@@ -20,6 +20,7 @@ from junifer.testing import get_testing_data
 from junifer.testing.datagrabbers import (
     OasisVBMTestingDataGrabber,
     PartlyCloudyTestingDataGrabber,
+    SPMAuditoryTestingDataGrabber,
 )
 
 
@@ -42,35 +43,10 @@ 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.
 
@@ -302,13 +278,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)
@@ -348,123 +324,106 @@ 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, None)
-
-    with PartlyCloudyTestingDataGrabber(reduce_confounds=False) as dg:
+            confound_remover._validate_data(vbm)
+    # Check missing nested type in correct data type
+    with SPMAuditoryTestingDataGrabber() as dg:
         element_data = DefaultDataReader().fit_transform(dg["sub-01"])
         bold = element_data["BOLD"]
-
-        with pytest.raises(ValueError, match="No extra input"):
-            confound_remover._validate_data(bold, None)
+        # Test confound type
         with pytest.raises(
-            ValueError, match="`BOLD_confounds` data type not provided"
+            ValueError, match="`BOLD.confounds` data type not provided"
         ):
-            confound_remover._validate_data(bold, {})
+            confound_remover._validate_data(bold)
+        # Test confound data
+        bold["confounds"] = {}
         with pytest.raises(
-            ValueError, match="`BOLD_confounds.data` not provided"
+            ValueError, match="`BOLD.confounds.data` not provided"
         ):
-            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()}}
+            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()}
         with pytest.raises(ValueError, match="Image time series and"):
-            confound_remover._validate_data(bold, extra_input)
-
-        extra_input = {
-            "BOLD_confounds": {"data": element_data["BOLD_confounds"]["data"]}
+            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",
+            },
         }
+        # 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.format` not provided"
+            ValueError, match="`BOLD.confounds.mappings` need to be set"
         ):
-            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",
+            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(
+            {
                 "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(bold, extra_input)
-
-        extra_input = {
-            "BOLD_confounds": {
-                "data": element_data["BOLD_confounds"]["data"],
-                "format": "adhoc",
+            confound_remover._validate_data(modified_bold)
+        # Test missing fmriprep mappings for adhoc
+        modified_bold["confounds"].update(
+            {
                 "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(bold, extra_input)
-
-        extra_input = {
-            "BOLD_confounds": {
-                "data": element_data["BOLD_confounds"]["data"],
-                "format": "adhoc",
+            confound_remover._validate_data(modified_bold)
+        # Test correct adhoc format
+        modified_bold["confounds"].update(
+            {
                 "mappings": {
                     "fmriprep": {
                         "rot_x": "rot_x",
                         "rot_y": "rot_z",
                         "rot_z": "rot_y",
-                    }
-                },
+                    },
+                }
             }
-        }
-        confound_remover._validate_data(bold, extra_input)
+        )
+        confound_remover._validate_data(modified_bold)
 
 
 def test_fMRIPrepConfoundRemover_preprocess() -> None:
@@ -476,7 +435,9 @@ 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
@@ -530,7 +491,7 @@ def test_fMRIPrepConfoundRemover_fit_transform() -> None:
         assert t_meta["t_r"] is None
         assert t_meta["masks"] is None
 
-        assert "BOLD_mask" not in output
+        assert "mask" not in output["BOLD"]
 
         assert "dependencies" in output["BOLD"]["meta"]
         dependencies = output["BOLD"]["meta"]["dependencies"]
@@ -582,9 +543,7 @@ 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 "BOLD_mask" in output
-        assert "mask_item" in output["BOLD"]
-        assert output["BOLD"]["mask_item"] == "BOLD_mask"
+        assert "mask" in output["BOLD"]
 
         assert "dependencies" in output["BOLD"]["meta"]
         dependencies = output["BOLD"]["meta"]["dependencies"]

junifer/preprocess/smoothing/__init__.py

@@ -0,0 +1,9 @@
+"""Provide imports for smoothing sub-package."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from .smoothing import Smoothing
+
+
+__all__ = ["Smoothing"]

junifer/preprocess/smoothing/_afni_smoothing.py

@@ -0,0 +1,119 @@
+"""Provide class for smoothing via AFNI."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    Dict,
+    List,
+    Set,
+    Union,
+)
+
+import nibabel as nib
+
+from ...pipeline import WorkDirManager
+from ...utils import logger, run_ext_cmd
+
+
+if TYPE_CHECKING:
+    from nibabel import Nifti1Image
+
+
+__all__ = ["AFNISmoothing"]
+
+
+class AFNISmoothing:
+    """Class for smoothing via AFNI.
+
+    This class uses AFNI's 3dBlurToFWHM.
+
+    """
+
+    _EXT_DEPENDENCIES: ClassVar[List[Dict[str, Union[str, List[str]]]]] = [
+        {
+            "name": "afni",
+            "commands": ["3dBlurToFWHM"],
+        },
+    ]
+
+    _DEPENDENCIES: ClassVar[Set[str]] = {"nibabel"}
+
+    def preprocess(
+        self,
+        data: "Nifti1Image",
+        fwhm: Union[int, float],
+    ) -> "Nifti1Image":
+        """Preprocess using AFNI.
+
+        Parameters
+        ----------
+        data : Niimg-like object
+            Image(s) to preprocess.
+        fwhm : int or float
+            Smooth until the value. AFNI estimates the smoothing and then
+            applies smoothing to reach ``fwhm``.
+
+        Returns
+        -------
+        Niimg-like object
+            The preprocessed image(s).
+
+        Notes
+        -----
+        For more information on ``3dBlurToFWHM``, check:
+        https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dBlurToFWHM.html
+
+        As the process also depends on the conversion of AFNI files to NIfTI
+        via AFNI's ``3dAFNItoNIFTI``, the help for that can be found at:
+        https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dAFNItoNIFTI.html
+
+        """
+        logger.info("Smoothing using AFNI")
+
+        # Create component-scoped tempdir
+        tempdir = WorkDirManager().get_tempdir(prefix="afni_smoothing")
+
+        # Save target data to a component-scoped tempfile
+        nifti_in_file_path = tempdir / "input.nii"  # needs to be .nii
+        nib.save(data, nifti_in_file_path)
+
+        # Set 3dBlurToFWHM command
+        blur_out_path_prefix = tempdir / "blur"
+        blur_cmd = [
+            "3dBlurToFWHM",
+            f"-input {nifti_in_file_path.resolve()}",
+            f"-prefix {blur_out_path_prefix.resolve()}",
+            "-automask",
+            f"-FWHM {fwhm}",
+        ]
+        # Call 3dBlurToFWHM
+        run_ext_cmd(name="3dBlurToFWHM", cmd=blur_cmd)
+
+        # Create element-scoped tempdir so that the blurred output is
+        # available later as nibabel stores file path reference for
+        # loading on computation
+        element_tempdir = WorkDirManager().get_element_tempdir(
+            prefix="afni_blur"
+        )
+        # Convert afni to nifti
+        blur_afni_to_nifti_out_path = (
+            element_tempdir / "output.nii"  # needs to be .nii
+        )
+        convert_cmd = [
+            "3dAFNItoNIFTI",
+            f"-prefix {blur_afni_to_nifti_out_path.resolve()}",
+            f"{blur_out_path_prefix}+orig.BRIK",
+        ]
+        # Call 3dAFNItoNIFTI
+        run_ext_cmd(name="3dAFNItoNIFTI", cmd=convert_cmd)
+
+        # Load nifti
+        output_data = nib.load(blur_afni_to_nifti_out_path)
+
+        # Delete tempdir
+        WorkDirManager().delete_tempdir(tempdir)
+
+        return output_data  # type: ignore

junifer/preprocess/smoothing/_fsl_smoothing.py

@@ -0,0 +1,116 @@
+"""Provide class for smoothing via FSL."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    Dict,
+    List,
+    Set,
+    Union,
+)
+
+import nibabel as nib
+
+from ...pipeline import WorkDirManager
+from ...utils import logger, run_ext_cmd
+
+
+if TYPE_CHECKING:
+    from nibabel import Nifti1Image
+
+
+__all__ = ["FSLSmoothing"]
+
+
+class FSLSmoothing:
+    """Class for smoothing via FSL.
+
+    This class uses FSL's susan.
+
+    """
+
+    _EXT_DEPENDENCIES: ClassVar[List[Dict[str, Union[str, List[str]]]]] = [
+        {
+            "name": "fsl",
+            "commands": ["susan"],
+        },
+    ]
+
+    _DEPENDENCIES: ClassVar[Set[str]] = {"nibabel"}
+
+    def preprocess(
+        self,
+        data: "Nifti1Image",
+        brightness_threshold: float,
+        fwhm: float,
+    ) -> "Nifti1Image":
+        """Preprocess using FSL.
+
+        Parameters
+        ----------
+        data : Niimg-like object
+            Image(s) to preprocess.
+        brightness_threshold : float
+            Threshold to discriminate between noise and the underlying image.
+            The value should be set greater than the noise level and less than
+            the contrast of the underlying image.
+        fwhm : float
+            Spatial extent of smoothing.
+
+        Returns
+        -------
+        Niimg-like object
+            The preprocessed image(s).
+
+        Notes
+        -----
+        For more information on ``SUSAN``, check [1]_
+
+        References
+        ----------
+        .. [1] Smith, S.M. and Brady, J.M. (1997).
+               SUSAN - a new approach to low level image processing.
+               International Journal of Computer Vision, Volume 23(1),
+               Pages 45-78.
+
+        """
+        logger.info("Smoothing using FSL")
+
+        # Create component-scoped tempdir
+        tempdir = WorkDirManager().get_tempdir(prefix="fsl_smoothing")
+
+        # Save target data to a component-scoped tempfile
+        nifti_in_file_path = tempdir / "input.nii.gz"
+        nib.save(data, nifti_in_file_path)
+
+        # Create element-scoped tempdir so that the output is
+        # available later as nibabel stores file path reference for
+        # loading on computation
+        element_tempdir = WorkDirManager().get_element_tempdir(
+            prefix="fsl_susan"
+        )
+        susan_out_path = element_tempdir / "output.nii.gz"
+        # Set susan command
+        susan_cmd = [
+            "susan",
+            f"{nifti_in_file_path.resolve()}",
+            f"{brightness_threshold}",
+            f"{fwhm}",
+            "3",  # dimension
+            "1",  # use median when no neighbourhood is found
+            "0",  # use input image to find USAN
+            f"{susan_out_path.resolve()}",
+        ]
+        # Call susan
+        run_ext_cmd(name="susan", cmd=susan_cmd)
+
+        # Load nifti
+        output_data = nib.load(susan_out_path)
+
+        # Delete tempdir
+        WorkDirManager().delete_tempdir(tempdir)
+
+        return output_data  # type: ignore

junifer/preprocess/smoothing/_nilearn_smoothing.py

@@ -0,0 +1,69 @@
+"""Provide class for smoothing via nilearn."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    Literal,
+    Set,
+    Union,
+)
+
+from nilearn import image as nimg
+from numpy.typing import ArrayLike
+
+from ...utils import logger
+
+
+if TYPE_CHECKING:
+    from nibabel import Nifti1Image
+
+
+__all__ = ["NilearnSmoothing"]
+
+
+class NilearnSmoothing:
+    """Class for smoothing via nilearn.
+
+    This class uses :func:`nilearn.image.smooth_img` to smooth image(s).
+
+    """
+
+    _DEPENDENCIES: ClassVar[Set[str]] = {"nilearn"}
+
+    def preprocess(
+        self,
+        data: "Nifti1Image",
+        fwhm: Union[int, float, ArrayLike, Literal["fast"], None],
+    ) -> "Nifti1Image":
+        """Preprocess using nilearn.
+
+        Parameters
+        ----------
+        data : Niimg-like object
+            Image(s) to preprocess.
+        fwhm : scalar, ``numpy.ndarray``, tuple or list of scalar, "fast" or \
+               None
+            Smoothing strength, as a full-width at half maximum, in
+            millimeters:
+
+            * If nonzero scalar, width is identical in all 3 directions.
+            * If ``numpy.ndarray``, tuple, or list, it must have 3 elements,
+              giving the FWHM along each axis. If any of the elements is 0 or
+              None, smoothing is not performed along that axis.
+            * If ``"fast"``, a fast smoothing will be performed with a filter
+              ``[0.2, 1, 0.2]`` in each direction and a normalisation to
+              preserve the local average value.
+            * If None, no filtering is performed (useful when just removal of
+              non-finite values is needed).
+
+        Returns
+        -------
+        Niimg-like object
+            The preprocessed image(s).
+
+        """
+        logger.info("Smoothing using nilearn")
+        return nimg.smooth_img(imgs=data, fwhm=fwhm)  # type: ignore