add Deconv_from_aif brick (#80)

docs/source/documentation/bricks/tools/Deconv_from_aif.rst

@@ -0,0 +1,129 @@
+:orphan:
+
+.. toctree::
+
++-----------------------------+-------------------------------------------+----------------------------------------------------+
+|`Home <../../../index.html>`_|`Documentation <../../documentation.html>`_|`GitHub <https://github.com/populse/mia_processes>`_|
++-----------------------------+-------------------------------------------+----------------------------------------------------+
+
+=====================
+Deconv_from_aif brick
+=====================
+
+Deconvolution of the tissue response curve with AIF
+---------------------------------------------------
+
+- MRI perfusion imaging by deconvolution using an Arterial Input Function
+  (AIF) is a method used to evaluate blood flow and perfusion in tissues,
+  often in the brain, to diagnose and assess conditions like stroke, tumors,
+  or other vascular abnormalities. This method is part of a broader category
+  of dynamic susceptibility contrast (DSC) MRI techniques.
+
+- DSC-MRI involves the injection of a contrast agent (usually
+  gadolinium-based) and the rapid acquisition of MRI images as the contrast
+  passes through the blood vessels. This generates time-series data that
+  reflect how the contrast agent is distributed in the tissue over time.
+
+- AIF represents the concentration of contrast agent over time in a feeding
+  artery. It is used as a reference to determine the blood supply to
+  the tissue.
+
+- Deconvolution is used to separate the tissue response from the AIF, thereby
+  allowing the calculation of perfusion parameters like cerebral blood flow
+  (CBF), cerebral blood volume (CBV), mean transit time (MTT), time to peak
+  (TTP), time to maximum (Tmax) and bolus arrival time (T0).
+
+-----------------------------------------------
+
+**Inputs parameters:**
+
+*func_file*
+    T2* functional Magnetic Resonance Imaging (fMRI) experiment recorded
+    during gadolinium bolus. Ideally, the data will have been pre-processed
+    (realignment, segmentation, etc.). An existing, uncompressed file
+    (valid extensions: [.img, .nii, .hdr]).
+
+    ::
+
+      ex. '/home/username/data/raw_data/swrfunc.nii'
+
+*aif_file*
+    The AIF (a file in .json format) typically obtained previously with the
+    Make_AIF brick.
+
+    ::
+
+      ex. '/home/username/data/raw_data/swrfunc_aif.json'
+
+*mask_file*
+    The mask (at the resolution of `func_file`) used for the perfusion
+    deconvolution (valid extensions: .nii).
+
+    ::
+
+      ex. '/home/username/data/raw_data/mask_swc1_anat_003.nii'
+
+**Outputs parameters:**
+
+- *CBV_image*
+    Cerebral Blood Volume (a file with .nii format) is a parameter that
+    measures the total volume of blood present within a given volume of brain
+    tissue, in milliliters of blood per 100 grams of brain tissue (mL/100g).
+    CBV provides important information about the vascularity and perfusion
+    characteristics of brain tissue.
+    ::
+
+      ex. '/home/username/data/derived_data/swrfunc_CBV_deconv.nii'
+
+- *CBF_image*
+    Cerebral Blood Flow (a file with .nii format) is a parameter that measures
+    the rate at which blood is delivered to the brain tissue, in milliliters
+    of blood per 100 grams of brain tissue per minute (mL/100g/min). CBF
+    provides valuable information about the brain's blood supply and is used
+    to assess the adequacy of cerebral perfusion in various neurological
+    conditions.
+
+    ::
+
+      ex. '/home/username/data/derived_data/swrfunc_CBF_deconv.nii'
+
+- *MTT_image*
+    Mean Transit Time (a file with .nii format) represents the average time
+    (s) it takes for blood to pass through a given region of tissue. It is an
+    important indicator of the efficiency of blood flow and is used alongside
+    other perfusion metrics like CBF and CBV to assess the health of brain
+    tissue.
+
+    ::
+
+      ex. '/home/username/data/derived_data/swrfunc_MTT_deconv.nii'
+
+- *TTP_image*
+    Time to Peak (a file with .nii format) reflects the time (s) it takes for
+    the contrast agent to reach its maximum concentration in a given voxel
+    after its arrival. This metric provides insight into the dynamics of blood
+    flow and is particularly useful in evaluating conditions like stroke,
+    tumors, and other cerebrovascular disorders.
+    ::
+
+      ex. '/home/username/data/derived_data/swrfunc_TTP_deconv.nii'
+
+- *Tmax_image*
+    The Time to Maximum (a file with .nii format) represents the time delay
+    (s) between the arrival of contrast agent in the arterial input function
+    (AIF) and the peak of the residue function (the tissue response after
+    deconvolution).
+
+    ::
+
+      ex. '/home/username/data/derived_data/swrfunc_Tmax_deconv.nii'
+
+- *T0_image*
+    The Bolus Arrival Time (a file with .nii format) represents the time (s)
+    at which the contrast agent first arrives at a particular voxel in the
+    tissue. It essentially marks the onset of contrast passage through each
+    voxel.
+
+    ::
+
+      ex. '/home/username/data/derived_data/swrfunc_T0_deconv.nii'

docs/source/documentation/bricks/tools/Make_AIF.rst

@@ -60,4 +60,4 @@ Compute the Arterial Input Function (AIF) from dynamic MRI perfusion data
 
     ::
 
-      ex. '/home/username/data/raw_data/swrfunc_aif.json'
+      ex. '/home/username/data/derived_data/swrfunc_aif.json'

docs/source/documentation/bricks/tools/Make_CVR_reg_physio.rst

@@ -39,7 +39,7 @@ Standard regressor:
 
 **Inputs parameters:**
 
-*func_file*
+- *func_file*
     T2* functional Magnetic Resonance Imaging (fMRI) experiment recorded
     during the hypercapnic Challenge (only required to extract metadata from
     the functional image). An existing, uncompressed file

docs/source/documentation/documentation.rst

@@ -165,6 +165,7 @@ To use certain mia_processes bricks (atomic processes), `third-party softwares u
 
     - `Concat_to_list <bricks/tools/Concat_to_list.html>`_
     - `Concat_to_list_of_list <bricks/tools/Concat_to_list_of_list.html>`_
+    - `Deconv_from_aif <bricks/tools/Deconv_from_aif.html>`_
     - `Delete_Data <bricks/tools/Delete_data.html>`_
     - `Files_To_List <bricks/tools/Files_To_List.html>`_
     - `Filter_Files_List <bricks/tools/Filter_Files_List.html>`_

mia_processes/bricks/tools/__init__.py

@@ -16,6 +16,7 @@
 from .tools import (  # noqa: F401
     Concat_to_list,
     Concat_to_list_of_list,
+    Deconv_from_aif,
     Delete_data,
     Files_To_List,
     Filter_Files_List,

mia_processes/bricks/tools/tools.py

@@ -9,6 +9,7 @@
     :Class:
         - Concat_to_list
         - Concat_to_list_of_list
+        - Deconv_from_aif
         - Delete_data
         - Files_To_List
         - Filter_Files_List
@@ -271,6 +272,219 @@ def run_process_mia(self):
         return
 
 
+class Deconv_from_aif(ProcessMIA):
+    """
+    blabla
+
+    Please, see the complete documentation for the
+    `Deconv_from_aif in the mia_processes website
+    <https://populse.github.io/mia_processes/html/documentation/bricks/tools/Deconv_from_aif.html>`_
+
+    """
+
+    def __init__(self):
+        """Dedicated to the attributes initialisation / instantiation.
+
+        The input and output plugs are defined here. The special
+        'self.requirement' attribute (optional) is used to define the
+        third-party products necessary for the running of the brick.
+        """
+        # initialisation of the objects needed for the launch of the brick
+        super(Deconv_from_aif, self).__init__()
+
+        # Third party softwares required for the execution of the brick
+        self.requirement = []  # no need of third party software!
+
+        # Inputs description
+        func_file_desc = "The DSC MRI scan (a NIfTI file)"
+        aif_file_desc = (
+            "The file containing the calculated AIF (a " ".json file)"
+        )
+        mask_file_desc = (
+            "A mask at the resolution of func_file (a " "NIfTI file)"
+        )
+
+        # Outputs description
+        CBV_image_desc = (
+            "The volume of blood within a given volume of tissue "
+            "(mL/100g) parameter (a NIfTI file)"
+        )
+        CBF_image_desc = (
+            "The rate of blood flow per unit of tissue "
+            "(mL/100g/min) parameter (a NIfTI file))"
+        )
+        MTT_image_desc = (
+            "Mean Transit Time parameter is the average time "
+            "(s) it takes for blood to traverse through the "
+            "tissue (a NIfTI file)"
+        )
+        TTP_image_desc = (
+            "The Time to Peak parameter is the time interval "
+            "(s) between the arrival of the contrast agent at "
+            "a voxel and the point when the concentration of "
+            "the contrast agent reaches its maximum (a NIfTI "
+            "file)"
+        )
+        Tmax_image_desc = (
+            "The Time to Maximum parameter is the time (s) at "
+            "which the residue function reaches its maximum "
+            "value after the arrival of the contrast agent (a "
+            "NIfTI file)"
+        )
+        T0_image_desc = (
+            "The Bolus Arrival Time parameter is the time (s) at "
+            "which the contrast agent first arrives at a "
+            "particular voxel in the tissue (a NIfTI file)"
+        )
+
+        # Inputs traits
+        self.add_trait(
+            "func_file",
+            Either(
+                ImageFileSPM(),
+                Undefined,
+                copyfile=False,
+                output=False,
+                optional=False,
+                desc=func_file_desc,
+            ),
+        )
+        self.func_file = traits.Undefined
+
+        self.add_trait(
+            "aif_file",
+            Either(
+                File(),
+                Undefined,
+                copyfile=False,
+                output=False,
+                optional=False,
+                desc=aif_file_desc,
+            ),
+        )
+        self.aif_file = traits.Undefined
+
+        self.add_trait(
+            "mask_file",
+            Either(
+                ImageFileSPM(),
+                Undefined,
+                copyfile=False,
+                output=False,
+                optional=False,
+                desc=mask_file_desc,
+            ),
+        )
+        self.mask_file = traits.Undefined
+
+        # Outputs traits
+
+        # self.add_trait(
+        #     "CBV_image",
+        #     OutputMultiPath(
+        #         File(), output=True, optional=True, desc=CBV_image_desc
+        #     ),
+        # )
+        self.add_trait("CBV_image", File(output=True, desc=CBV_image_desc))
+        self.CBV_image = traits.Undefined
+
+        self.add_trait("CBF_image", File(output=True, desc=CBF_image_desc))
+        self.CBF_image = traits.Undefined
+
+        self.add_trait("MTT_image", File(output=True, desc=MTT_image_desc))
+        self.MTT_image = traits.Undefined
+
+        self.add_trait("TTP_image", File(output=True, desc=TTP_image_desc))
+        self.TTP_image = traits.Undefined
+
+        self.add_trait("Tmax_image", File(output=True, desc=Tmax_image_desc))
+        self.Tmax_image = traits.Undefined
+
+        self.add_trait("T0_image", File(output=True, desc=T0_image_desc))
+        self.T0_image = traits.Undefined
+
+        self.init_default_traits()
+
+    def list_outputs(self, is_plugged=None):
+        """Dedicated to the initialisation step of the brick.
+        The main objective of this method is to produce the outputs of the
+        bricks (self.outputs) and the associated tags (self.inheritance_dic),
+        if defined here. In order not to include an output in the database,
+        this output must be a value of the optional key 'notInDb' of the
+        self.outputs dictionary. To work properly this method must return
+        self.make_initResult() object.
+        :param is_plugged: the state, linked or not, of the plugs.
+        :returns: a dictionary with requirement, outputs and inheritance_dict.
+        """
+        # Using the inheritance to ProcessMIA class, list_outputs method
+        super(Deconv_from_aif, self).list_outputs()
+
+        # Outputs definition and tags inheritance (optional)
+        if self.outputs:
+            self.outputs = {}
+
+        if (
+            self.func_file
+            and self.aif_file
+            and self.mask_file
+            and self.func_file
+            not in [
+                "<undefined>",
+                traits.Undefined,
+            ]
+            and self.aif_file
+            not in [
+                "<undefined>",
+                traits.Undefined,
+            ]
+            and self.mask_file
+            not in [
+                "<undefined>",
+                traits.Undefined,
+            ]
+        ):
+
+            if self.output_directory:
+                _, file_name = os.path.split(self.func_file)
+                file_name_no_ext, _ = os.path.splitext(file_name)
+                self.outputs["CBV_image"] = os.path.join(
+                    self.output_directory, file_name_no_ext + "_CBV_deconv.nii"
+                )
+                self.outputs["CBF_image"] = os.path.join(
+                    self.output_directory, file_name_no_ext + "_CBF_deconv.nii"
+                )
+                self.outputs["MTT_image"] = os.path.join(
+                    self.output_directory, file_name_no_ext + "_MTT_deconv.nii"
+                )
+                self.outputs["TTP_image"] = os.path.join(
+                    self.output_directory, file_name_no_ext + "_TTP_deconv.nii"
+                )
+                self.outputs["Tmax_image"] = os.path.join(
+                    self.output_directory,
+                    file_name_no_ext + "_Tmax_deconv.nii",
+                )
+                self.outputs["T0_image"] = os.path.join(
+                    self.output_directory, file_name_no_ext + "_T0_deconv.nii"
+                )
+
+            else:
+                print(
+                    "Deconv_from_aif brick: No output directory found, "
+                    "initialization step cannot be performed...!\n"
+                )
+                return self.make_initResult()
+
+            self.tags_inheritance(self.func_file, self.outputs["aif_file"])
+
+        # Return the requirement, outputs and inheritance_dict
+        return self.make_initResult()
+
+    def run_process_mia(self):
+        """Dedicated to the process launch step of the brick."""
+        super(Deconv_from_aif, self).run_process_mia()
+        print("To do...")
+
+
 class Delete_data(ProcessMIA):
     """
     *Delete from database data*
@@ -2063,7 +2277,7 @@ def __init__(self):
 
         # Outputs traits
         self.add_trait("aif_file", File(output=True, desc=aif_file_desc))
-        self.cvr_reg = traits.Undefined
+        self.aif_file = traits.Undefined
 
         self.init_default_traits()