From 6400c7bcaa53ad98f19d15b4e6efecc41c34960c Mon Sep 17 00:00:00 2001 From: econdami Date: Mon, 5 Aug 2024 18:23:53 +0200 Subject: [PATCH] add Deconv_from_aif brick (#80) --- .../bricks/tools/Deconv_from_aif.rst | 129 +++++++++++ .../documentation/bricks/tools/Make_AIF.rst | 2 +- .../bricks/tools/Make_CVR_reg_physio.rst | 2 +- docs/source/documentation/documentation.rst | 1 + mia_processes/bricks/tools/__init__.py | 1 + mia_processes/bricks/tools/tools.py | 216 +++++++++++++++++- 6 files changed, 348 insertions(+), 3 deletions(-) create mode 100644 docs/source/documentation/bricks/tools/Deconv_from_aif.rst diff --git a/docs/source/documentation/bricks/tools/Deconv_from_aif.rst b/docs/source/documentation/bricks/tools/Deconv_from_aif.rst new file mode 100644 index 000000000..50c2d81e9 --- /dev/null +++ b/docs/source/documentation/bricks/tools/Deconv_from_aif.rst @@ -0,0 +1,129 @@ +:orphan: + +.. toctree:: + ++-----------------------------+-------------------------------------------+----------------------------------------------------+ +|`Home <../../../index.html>`_|`Documentation <../../documentation.html>`_|`GitHub `_| ++-----------------------------+-------------------------------------------+----------------------------------------------------+ + +===================== +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' diff --git a/docs/source/documentation/bricks/tools/Make_AIF.rst b/docs/source/documentation/bricks/tools/Make_AIF.rst index 5126c8c88..f80f8344b 100644 --- a/docs/source/documentation/bricks/tools/Make_AIF.rst +++ b/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' diff --git a/docs/source/documentation/bricks/tools/Make_CVR_reg_physio.rst b/docs/source/documentation/bricks/tools/Make_CVR_reg_physio.rst index a6fff1890..2f48739ce 100644 --- a/docs/source/documentation/bricks/tools/Make_CVR_reg_physio.rst +++ b/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 diff --git a/docs/source/documentation/documentation.rst b/docs/source/documentation/documentation.rst index ecd06c292..2d6fe72e9 100644 --- a/docs/source/documentation/documentation.rst +++ b/docs/source/documentation/documentation.rst @@ -165,6 +165,7 @@ To use certain mia_processes bricks (atomic processes), `third-party softwares u - `Concat_to_list `_ - `Concat_to_list_of_list `_ + - `Deconv_from_aif `_ - `Delete_Data `_ - `Files_To_List `_ - `Filter_Files_List `_ diff --git a/mia_processes/bricks/tools/__init__.py b/mia_processes/bricks/tools/__init__.py index 82c011d77..64727e679 100644 --- a/mia_processes/bricks/tools/__init__.py +++ b/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, diff --git a/mia_processes/bricks/tools/tools.py b/mia_processes/bricks/tools/tools.py index 163a4329c..19907402e 100644 --- a/mia_processes/bricks/tools/tools.py +++ b/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 + `_ + + """ + + 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 [ + "", + traits.Undefined, + ] + and self.aif_file + not in [ + "", + traits.Undefined, + ] + and self.mask_file + not in [ + "", + 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()