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

junifer/preprocess/confounds/fmriprep_confound_remover.py

@@ -6,7 +6,6 @@
 # License: AGPL
 
 from typing import (
-    TYPE_CHECKING,
     Any,
     ClassVar,
     Dict,
@@ -19,8 +18,8 @@ from typing import (
 
 import numpy as np
 import pandas as pd
+from nilearn import image as nimg
 from nilearn._utils.niimg_conversions import check_niimg_4d
-from nilearn.image import clean_img
 
 from ...api.decorators import register_preprocessor
 from ...data import get_mask
@@ -28,10 +27,6 @@ from ...utils import logger, raise_error
 from ..base import BasePreprocessor
 
 
-if TYPE_CHECKING:
-    from nibabel import MGHImage, Nifti1Image, Nifti2Image
-
-
 FMRIPREP_BASICS = {
     "motion": [
         "trans_x",
@@ -164,7 +159,7 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
         t_r: Optional[float] = None,
         masks: Union[str, Dict, List[Union[Dict, str]], None] = None,
     ) -> None:
-        """Initialise the class."""
+        """Initialize the class."""
         if strategy is None:
             strategy = {
                 "motion": "full",
@@ -208,69 +203,38 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
                 "include it in the future",
                 klass=ValueError,
             )
-        super().__init__()
-
-    def validate_input(self, input: List[str]) -> List[str]:
-        """Validate the input to the pipeline step.
+        super().__init__(
+            on="BOLD", required_data_types=["BOLD", "BOLD_confounds"]
+        )
 
-        Parameters
-        ----------
-        input : list of str
-            The input to the pipeline step. The list must contain the
-            available Junifer Data object keys.
+    def get_valid_inputs(self) -> List[str]:
+        """Get valid data types for input.
 
         Returns
         -------
         list of str
-            The actual elements of the input that will be processed by this
-            pipeline step.
-
-        Raises
-        ------
-        ValueError
-            If the input does not have the required data.
+            The list of data types that can be used as input for this
+            preprocessor.
 
         """
-        _required_inputs = ["BOLD", "BOLD_confounds"]
-        if any(x not in input for x in _required_inputs):
-            raise_error(
-                msg="Input does not have the required data. \n"
-                f"Input: {input} \n"
-                f"Required (all off): {_required_inputs} \n",
-                klass=ValueError,
-            )
-
-        return [x for x in self._on if x in input]
+        return ["BOLD"]
 
-    def get_output_type(self, input: List[str]) -> List[str]:
-        """Get the kind of the pipeline step.
+    def get_output_type(self, input_type: str) -> str:
+        """Get output type.
 
         Parameters
         ----------
-        input : list of str
-            The input to the pipeline step. The list must contain the
-            available Junifer Data object keys.
+        input_type : str
+            The 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.
 
         """
         # Does not add any new keys
-        return input
-
-    def get_valid_inputs(self) -> List[str]:
-        """Get the valid inputs for the pipeline step.
-
-        Returns
-        -------
-        list of str
-            The valid inputs for the pipeline step.
-
-        """
-        return ["BOLD"]
+        return input_type
 
     def _map_adhoc_to_fmriprep(self, input: Dict[str, Any]) -> None:
         """Map the adhoc format to the fmpriprep format spec.
@@ -333,6 +297,11 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
         spike_name : str
             Name of the confound to use for spike detection
 
+        Raises
+        ------
+        ValueError
+            If invalid confounds file is found.
+
         """
         confounds_df = input["data"]
         available_vars = confounds_df.columns
@@ -347,7 +316,7 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
 
             if any(x not in available_vars for x in t_basics):
                 missing = [x for x in t_basics if x not in available_vars]
-                raise ValueError(
+                raise_error(
                     "Invalid confounds file. Missing basic confounds: "
                     f"{missing}. "
                     "Check if this file is really an fmriprep confounds file. "
@@ -377,7 +346,7 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
         spike_name = "framewise_displacement"
         if self.spike is not None:
             if spike_name not in available_vars:
-                raise ValueError(
+                raise_error(
                     "Invalid confounds file. Missing framewise_displacement "
                     "(spike) confound. "
                     "Check if this file is really an fmriprep confounds file. "
@@ -460,22 +429,35 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
             Dictionary containing the rest of the Junifer Data object. Must
             include the ``BOLD_confounds`` key.
 
-        """
+        Raises
+        ------
+        ValueError
+            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"`` 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
+        """
+        # BOLD must be 4D niimg
         check_niimg_4d(input["data"])
-
+        # Check for extra inputs
         if extra_input is None:
-            raise_error("No extra input provided", ValueError)
+            raise_error(
+                "No extra input provided, requires `BOLD_confounds` data type "
+                "in particular"
+            )
         if "BOLD_confounds" not in extra_input:
-            raise_error("No BOLD_confounds provided", ValueError)
+            raise_error("`BOLD_confounds` data type not provided")
         if "data" not in extra_input["BOLD_confounds"]:
-            raise_error("No BOLD_confounds data provided", ValueError)
-        # Confounds must be a dataframe
+            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(
-                "Confounds data must be a pandas dataframe", ValueError
-            )
+            raise_error("`BOLD_confounds.data` must be a `pandas.DataFrame`")
 
         confound_df = extra_input["BOLD_confounds"]["data"]
         bold_img = input["data"]
@@ -486,26 +468,20 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
                 f"\tConfounds: {len(confound_df)}"
             )
 
+        # Check format
         if "format" not in extra_input["BOLD_confounds"]:
-            raise_error(
-                "Confounds format must be specified in "
-                '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 extra_input["BOLD_confounds"]:
                 raise_error(
-                    "When using adhoc format, you must specify "
-                    "the variables names mappings in "
-                    'input["BOLD_confounds"]["mappings"]'
+                    "`BOLD_confounds.mappings` need to be set when "
+                    "`BOLD_confounds.format == 'adhoc'`"
                 )
             if "fmriprep" not in extra_input["BOLD_confounds"]["mappings"]:
                 raise_error(
-                    "When using adhoc format, you must specify "
-                    "the variables names mappings to fmriprep format in "
-                    'input["BOLD_confounds"]["mappings"]["fmriprep"]'
+                    "`BOLD_confounds.mappings.fmriprep` need to be set when "
+                    "`BOLD_confounds.format == 'adhoc'`"
                 )
             fmriprep_mappings = extra_input["BOLD_confounds"]["mappings"][
                 "fmriprep"
@@ -517,7 +493,7 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
             ]
             if len(wrong_names) > 0:
                 raise_error(
-                    "The following mapping values are not valid fmriprep "
+                    "The following mapping values are not valid fMRIPrep "
                     f"names: {wrong_names}"
                 )
             # Check that all the required columns are present
@@ -528,106 +504,87 @@ class fMRIPrepConfoundRemover(BasePreprocessor):
             ]
 
             if len(missing) > 0:
-                raise ValueError(
+                raise_error(
                     "Invalid confounds file. Missing columns: "
                     f"{missing}. "
                     "Check if this file matches the adhoc specification for "
                     "this dataset."
                 )
         elif t_format != "fmriprep":
-            raise ValueError(f"Invalid confounds format {t_format}")
+            raise_error(f"Invalid confounds format {t_format}")
 
-    def _remove_confounds(
+    def preprocess(
         self,
         input: Dict[str, Any],
         extra_input: Optional[Dict[str, Any]] = None,
-    ) -> Union["Nifti1Image", "Nifti2Image", "MGHImage", List]:
-        """Remove confounds from the BOLD image.
+    ) -> Tuple[Dict[str, Any], Optional[Dict[str, Dict[str, Any]]]]:
+        """Preprocess.
 
         Parameters
         ----------
         input : dict
-            Dictionary containing the ``BOLD`` value from the
-            Junifer Data object.
+            A single input from the Junifer Data object to preprocess.
         extra_input : dict, optional
-            Dictionary containing the rest of the Junifer Data object. Must
-            include the ``BOLD_confounds`` key.
+            The other fields in the Junifer Data object. Must include the
+            ``BOLD_confounds`` key.
 
         Returns
         -------
-        Niimg-like object
-            Input image with confounds removed.
+        dict
+            The computed result as dictionary.
+        dict or None
+            If `self.masks` is not None, then the target data computed mask is
+            returned else None.
 
         """
-        assert extra_input is not None  # Not the case, data is validated
-        confounds_df = self._pick_confounds(extra_input["BOLD_confounds"])
-        confounds_array = confounds_df.values
-
+        # Validate data
+        self._validate_data(input, extra_input)
+        # Pick confounds
+        confounds_df = self._pick_confounds(extra_input["BOLD_confounds"])  # type: ignore
+        # Get BOLD data
         bold_img = input["data"]
+        # Set t_r
         t_r = self.t_r
         if t_r is None:
-            logger.info("No `t_r` specified, using t_r from nifti header")
-            zooms = bold_img.header.get_zooms()  # type: ignore
-            t_r = zooms[3]
+            logger.info("No `t_r` specified, using t_r from NIfTI header")
+            t_r = bold_img.header.get_zooms()[3]  # type: ignore
             logger.info(
-                f"Read t_r from nifti header: {t_r}",
+                f"Read t_r from NIfTI header: {t_r}",
             )
-
+        # 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(
                 masks=self.masks, target_data=input, extra_input=extra_input
             )
-            # Save the mask in the extra input and link it to the bold data
+            # Return the BOLD mask and link it to the BOLD data type dict;
             # this allows to use "inherit" down the pipeline
             if extra_input is not None:
-                logger.debug("Setting mask_item")
-                extra_input["BOLD_mask"] = {"data": mask_img}
+                logger.debug("Setting `BOLD.mask_item`")
                 input["mask_item"] = "BOLD_mask"
-
-        logger.info("Cleaning image")
+                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}")
         logger.debug(f"\tstandardize: {self.standardize}")
         logger.debug(f"\tlow_pass: {self.low_pass}")
         logger.debug(f"\thigh_pass: {self.high_pass}")
-        clean_bold = clean_img(
+        input["data"] = nimg.clean_img(
             imgs=bold_img,
             detrend=self.detrend,
             standardize=self.standardize,
-            confounds=confounds_array,
+            confounds=confounds_df.values,
             low_pass=self.low_pass,
             high_pass=self.high_pass,
             t_r=t_r,
             mask_img=mask_img,
         )
 
-        return clean_bold
-
-    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
-            ``BOLD_confounds`` key.
-
-        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``.
-
-        """
-        self._validate_data(input, extra_input)
-        input["data"] = self._remove_confounds(input, extra_input=extra_input)
-        return "BOLD", input
+        return input, bold_mask_dict