GraphicalAnalysisParametricImage ========================================================================== .. py:class:: petpal.kinetic_modeling.parametric_images.GraphicalAnalysisParametricImage(input_tac_path: str, input_image_path: str, output_directory: str, output_filename_prefix: str) Class for generating parametric images of 4D-PET images using graphical analyses. It provides methods to run graphical analysis, calculate properties of the resulting images, and save the results using file paths. :ivar input_tac_path: Absolute path to the input Time-Activity Curve (TAC) file. :vartype input_tac_path: str :ivar input_image_path: Absolute path to the 4D PET image file. :vartype input_image_path: str :ivar output_directory: Absolute path to the output directory. :vartype output_directory: str :ivar output_filename_prefix: Prefix of the output file names. :vartype output_filename_prefix: str :ivar analysis_props: Dictionary of properties of the graphical analysis. :vartype analysis_props: dict :ivar slope_image: The slope image resulting from the graphical analysis, initialized to None. :vartype slope_image: np.ndarray :ivar intercept_image: The intercept image resulting from the graphical analysis, initialized to None. :vartype intercept_image: np.ndarray Initializes the GraphicalAnalysisParametricImage with the specified parameters. This method initializes necessary attributes for the GraphicalAnalysisParametricImage object with the provided arguments. It sets the absolute file paths for the input TAC, 4D PET image, and output directory, and initializes the analysis properties. Further, it initializes variables for the slope and intercept images. :param input_tac_path: Path to the input Time-Activity Curve (TAC) file. :type input_tac_path: str :param input_image_path: Path to the 4D PET image file. :type input_image_path: str :param output_directory: Path to the destination directory where output files will be saved. :type output_directory: str :param output_filename_prefix: Prefix to use for the names of the output files. :type output_filename_prefix: str :returns: None .. py:method:: init_analysis_props() Initializes the analysis properties dictionary. The analysis properties dictionary contains properties derived from the analysis. It begins with certain known values, such as file paths, but most values are initialized to None and filled in later as the analysis is performed. Properties include: * ``FilePathPTAC`` (str): The path to the input Time-Activity Curve (TAC) file. * ``FilePathTTAC`` (str): The path to the 4D PET image file. * ``MethodName`` (str): The name of the graphical analysis method used, to be filled in later. * ``ImageDimensions`` (tuple): The dimensions of the images resulting from the analysis, to be filled in later. * ``StartFrameTime`` (float): The start time of the frame used in the analysis, filled in after the analysis. * ``EndFrameTime`` (float): The end time of the frame used in the analysis, filled in after the analysis. * ``ThresholdTime`` (float): The time threshold used in the analysis, filled in after the analysis. * ``RunKwargs`` (dict): Keyword arguments passed on to the analysis function. * ``NumberOfPointsFit`` (int): The number of points fitted in the analysis, filled in after the analysis. * ``SlopeMaximum`` (float): The maximum slope found in the analysis, filled in after the analysis. * ``SlopeMinimum`` (float): The minimum slope found in the analysis, filled in after the analysis. * ``SlopeMean`` (float): The mean of the slopes found in the analysis, filled in after the analysis. * ``SlopeVariance`` (float): The variance of the slopes found in the analysis, filled in after the analysis. * ``InterceptMaximum`` (float): The maximum intercept found in the analysis, filled in after the analysis. * ``InterceptMinimum`` (float): The minimum intercept found in the analysis, filled in after the analysis. * ``InterceptMean`` (float): The mean of the intercepts found in the analysis, filled in after the analysis. * ``InterceptVariance`` (float): The variance of the intercepts found in the analysis, filled in after the analysis. :returns: *props (dict)* -- The initialized properties dictionary. .. py:method:: run_analysis(method_name: str, t_thresh_in_mins: float, **run_kwargs) Executes the complete analysis procedure. This method orchestrates the full analysis by orchestrating the calculation of parametric images, as well as compiling the properties related to the analysis. Both are determined based on the provided method name and the threshold time. :param method_name: The name of the methodology adopted for the process. :type method_name: str :param t_thresh_in_mins: The threshold time used through the analysis (in minutes). :type t_thresh_in_mins: float :param run_kwargs: Additional keyword arguments passed on to :func:`calculate_parametric_images` and :func:`calculate_analysis_properties`. .. seealso:: * :func:`calculate_parametric_images` * :func:`calculate_analysis_properties` :returns: None .. py:method:: save_analysis() Stores the results from an analysis routine. This method executes the storage of parametric images, as well as the properties related to the analysis. It assumes that the method 'run_analysis' is called before this method. :raises RuntimeError: If the method 'run_analysis' is not called before this method. .. seealso:: * :func:`save_parametric_images` * :func:`save_analysis_properties` :returns: None .. py:method:: calculate_analysis_properties(method_name: str, t_thresh_in_mins: float, **run_kwargs) Performs a set of calculations to collate various analysis properties. This method orchestrates the calculation of properties related to both the parametric images and the fitting process. It does this by calling :meth:`calculate_parametric_images_properties` and :meth:`calculate_fit_properties` respectively. :param method_name: The name of the method used for the fitting process. :type method_name: str :param t_thresh_in_mins: The threshold time (in minutes) used for the fitting process. :type t_thresh_in_mins: float :param run_kwargs: Additional keyword arguments passed on to :func:`calculate_fit_properties`. .. seealso:: * :meth:`calculate_parametric_images_properties` * :meth:`calculate_fit_properties` :returns: None. The results are stored within the instance's ``analysis_props`` variable. .. py:method:: calculate_fit_properties(method_name: str, t_thresh_in_mins: float, **run_kwargs) Calculates and stores the properties related to the fitting process. This method calculates several properties related to the fitting process, including the threshold time, the name of the method used, the start and end frame time, and the number of points used in the fit. These values are stored in the instance's `analysis_props` variable. :param method_name: The name of the methodology adopted for the fitting process. :type method_name: str :param t_thresh_in_mins: The threshold time (in minutes) used in the fitting process. :type t_thresh_in_mins: float :param run_kwargs: Additional keyword arguments used in the analysis. These are saved to the analysis properties as individual properties. .. note:: This method relies on the :func:`safe_load_tac` function to load time-activity curve (TAC) data from the file at ``self.input_tac_path``, and the :func:`petpal.graphical_analysis.get_index_from_threshold` function to get the index from the threshold time. .. seealso:: * :func:`safe_load_tac`: Function to safely load TAC data from a file. * :func:`petpal.graphical_analysis.get_index_from_threshold`: Function to get the index from the threshold time. :returns: None. The results are stored within the instance's ``analysis_props`` variable. .. py:method:: calculate_parametric_images_properties() Initiates the calculation of properties for parametric images. This method triggers the calculation of statistical properties for slope and intercept images. Additionally, it captures the shape of the slope image as the 'ImageDimensions' and stores it in `analysis_props`. .. note:: You should ensure the `slope_image` attribute has been correctly set before calling this method. This means that `run_analysis` has already been called. .. seealso:: calculate_slope_image_properties: Method to calculate various statistics for slope image. calculate_intercept_image_properties: Method to calculate various statistics for intercept image. :returns: None. The results are stored within the instance's `analysis_props` variable. .. py:method:: calculate_slope_image_properties() Calculates and stores statistical properties of the slope image. This method calculates the maximum, minimum, mean, and variance of the `slope_image` attribute, and stores these values in the `analysis_props` dictionary. The keys in `analysis_props` for these values are: `SlopeMaximum`, `SlopeMinimum`, `SlopeMean`, and `SlopeVariance`, respectively. .. note:: You should ensure the `slope_image` attribute has been correctly set before calling this method. No explicit return value. The results are stored within the instance's `analysis_props` variable. .. py:method:: calculate_intercept_image_properties() Calculates and stores statistical properties of the intercept image. This method calculates the maximum, minimum, mean, and variance of the `intercept_image` attribute, and stores these values in the `analysis_props` dictionary. The keys in `analysis_props` for these values are: `InterceptMaximum`, `InterceptMinimum`, `InterceptMean`, and `InterceptVariance`, respectively. .. note:: You should ensure the `intercept_image` attribute has been correctly set before calling this method. No explicit return value. The results are stored within the instance's `analysis_props` variable. .. py:method:: calculate_parametric_images(method_name: str, t_thresh_in_mins: float, **run_kwargs) Performs graphical analysis of PET parametric images and generates/updates the slope and intercept images. This method uses the given graphical analysis method and threshold to perform the analysis given the input Time Activity Curve (TAC) and 4D PET image, and updates the slope and intercept images accordingly. PET images are loaded from the specified path. Then, the parametric images are calculated using the specified graphical method and threshold time by explicitly analyzing each voxel in the 4D PET image. :param method_name: The name of the graphical analysis method to be used. :type method_name: str :param t_thresh_in_mins: The threshold time in minutes. :type t_thresh_in_mins: float :param run_kwargs: Additional keyword arguments passed on to :func:`generate_parametric_images_with_graphical_method`. :returns: None :raises Exception: An error occurred during the graphical analysis. This could be due to an :raises invalid method name or incorrect inputs to the method.: .. seealso:: * :func:`generate_parametric_images_with_graphical_method` * :func:`petpal.graphical_analysis.patlak_analysis` * :func:`petpal.graphical_analysis.logan_analysis` * :func:`petpal.graphical_analysis.alternative_logan_analysis` .. py:method:: __call__(method_name, t_thresh_in_mins, **run_kwargs) .. py:method:: save_parametric_images() Saves the slope and intercept images as NIfTI files in the specified output directory. This method generates and saves two NIfTI files: one for the slope image and one for the intercept image. It uses the output directory and filename prefix provided during instantiation of the class, along with the analysis method name, to generate a filename prefix for both images. The filenames follow the patterns `{output_filename_prefix}-parametric-{method}-slope.nii.gz` and `{output_filename_prefix}-parametric-{method}-intercept.nii.gz` respectively. The affine transformation matrix for the new NIfTI images is derived from the original 4D PET image. :param None: :returns: None :raises IOError: An error occurred accessing the output_directory or while writing to the NIfTI :raises file.: .. py:method:: save_analysis_properties() Saves the analysis properties to a JSON file in the output directory. This method involves saving a dictionary of analysis properties, which include file paths, analysis method, start and end frame times, threshold time, number of points fitted, and various properties like the maximum, minimum, mean, and variance of slopes and intercepts found in the analysis. These analysis properties are written to a JSON file in the output directory with the name following the pattern `{output_filename_prefix}-analysis-props.json`. :param None: :returns: None :raises IOError: An error occurred accessing the output_directory or while writing to the JSON :raises file.: .. seealso:: * :func:`save_analysis_properties`