GraphicalAnalysisPlot =========================================================== .. py:class:: petpal.visualizations.graphical_plots.GraphicalAnalysisPlot(pTAC: numpy.ndarray, tTAC: numpy.ndarray, t_thresh_in_mins: float, figObj: matplotlib.pyplot.Figure = None) Bases: :py:obj:`abc.ABC` This is an abstract base class designed for creating customizable plots for graphical analysis. It takes Time-Activity Curves (TACs) as input and creates various plots (x vs. y, fit lines, fit area shading plots, and fit points) based on user input. This class also calculates fit parameters for the plotting data and determines relevant indices based on given thresholds. :ivar pTAC: The Input/Plasma TAC, an array containing time points and corresponding activity. :vartype pTAC: np.ndarray :ivar tTAC: The Tissue/Region TAC, an array with time points and corresponding activity. :vartype tTAC: np.ndarray :ivar t_thresh_in_mins: The threshold time, in minutes, to consider in the analysis. Points are fit after this threshold. :vartype t_thresh_in_mins: float :ivar fig: A matplotlib Figure object where the plots will be drawn. :vartype fig: plt.Figure :ivar ax_list: A list of matplotlib Axes associated with `fig` where the plots will be drawn. :vartype ax_list: list :ivar non_zero_idx: Indexes of non-zero values in appropriate TAC (calculated in specific implementations). :vartype non_zero_idx: np.ndarray :ivar t_thresh_idx: The index at which the time threshold is crossed in the TACs (calculated in specific implementations). :vartype t_thresh_idx: int :ivar x: The "x" values for plotting (calculated in specific implementations). :vartype x: np.ndarray :ivar y: The "y" values for plotting (calculated in specific implementations). :vartype y: np.ndarray :ivar fit_params: The parameters fit to the data using least squares. Contains 'slope', 'intercept', and 'r_squared' (calculated in specific implementations). :vartype fit_params: dict .. important:: This is an abstract class and should be inherited by a concrete class that implements the following methods: * :func:`calculate_valid_indicies_and_x_and_y` * :func:`generate_label_from_fit_params` * :func:`add_figure_axes_labels_and_legend` Initialize an instance of the GraphicalAnalysisPlot class. The instance is initialized with two Time-Activity Curves (TACs), a threshold time, and an optional matplotlib Figure. It calculates valid indices (where the denominator is non-zero for the particular analysis), 'x' and 'y' values for plotting based on the TACs and the threshold time, and also analyzes the TACs to generate the fits. :param pTAC: The input Time Activity Curve, an array containing time points and corresponding activity. :type pTAC: np.ndarray :param tTAC: The Tissue or Region Time Activity Curve, an array with time points and corresponding activity. :type tTAC: np.ndarray :param t_thresh_in_mins: The threshold time in minutes to consider when performing calculations for the plots. :type t_thresh_in_mins: float :param figObj: An optional matplotlib Figure object. If not provided, a new Figure object is created. :type figObj: plt.Figure, optional :raises matplotlib error: Error handling for the plot generation is managed by matplotlib. Any exceptions thrown during plotting are handled by the :mod:`matplotlib` internally. .. py:method:: generate_figure_and_axes(figObj: matplotlib.pyplot.Figure = None) :staticmethod: Generate a matplotlib Figure and Axes for plotting. A new Figure and Axes are created if no Figure object is provided. If a Figure object is provided, the method retrieves the existing axes from the Figure object. In either case, the method returns the Figure and a list of its Axes. :param figObj: An optional matplotlib Figure object. If not provided, a new Figure object is created with 2 subplots arranged in 1 row, a figure size of 8x4, line width of 3.0, and edge color 'k'. :type figObj: plt.Figure, optional :returns: *fig (plt.Figure)* -- The resulting matplotlib Figure object. ax_list (list): A list of Axes objects associated with 'fig'. :raises None: .. py:method:: add_data_plots(pl_kwargs: dict = None) Add data plots to the Axes in the instance's Axes list. This method plots the instance's :math:`x` and :math:`y` values (from the particular analysis) on each Axes in the instance's Axes list. The style of the plotted points can be customized by passing a dictionary of keyword arguments for `matplotlib.pyplot.plot`. :param pl_kwargs: A dictionary of keyword arguments to be passed to `matplotlib.pyplot.plot` for styling the points. If not provided, the points are plotted with ``linewidth=1``, ``alpha=0.9``, ``markersize=8``, ``markerstyle='.'``, ``zorder=1``, and ``color='black'``. :type pl_kwargs: dict, optional :raises ValueError: If pl_kwargs contains an argument not supported by ``matplotlib.pyplot.plot``. .. py:method:: add_shading_plots(pl_kwargs: dict = None) Add shaded regions to the Axes in the instance's Axes list. This method shades a vertical span on each Axes in the instance's Axes list, from the x-value at the threshold index to the last x-value. The style of the shaded region can be customized by passing a dictionary of keyword arguments for :func:`matplotlib.pyplot.axvspan`. :param pl_kwargs: A dictionary of keyword arguments to be passed to `matplotlib.pyplot.axvspan` for styling the shaded region. If not provided, the region is shaded with ``color='gray'``, ``alpha=0.2``, and ``zorder=0``. :type pl_kwargs: dict, optional :raises ValueError: If pl_kwargs contains an argument not supported by :func:`matplotlib.pyplot.axvspan`. .. py:method:: add_fit_points(pl_kwargs: dict = None) Add fit points to the Axes in the instance's Axes list. This method plots the instance's :math:`x` and :math:`y` values that were used in fitting, i.e., the points past the threshold index, on each Axes in the instance's Axes list. The style of the plotted points can be customized by passing a dictionary of keyword arguments for :func:`matplotlib.pyplot.plot`. :param pl_kwargs: A dictionary of keyword arguments to be passed to :func:`matplotlib.pyplot.plot` for styling the points. If not provided, the points are plotted as blue circles with ``alpha=0.9``, ``markersize=5``, and ``zorder=2``. :type pl_kwargs: dict, optional :raises ValueError: If pl_kwargs contains an argument not supported by :func:`matplotlib.pyplot.plot`. .. py:method:: add_fit_lines(pl_kwargs: dict = None) Add line of best fit to the Axes in the instance's Axes list. This method plots the line of best fit based on the instance's fit parameters (slope and intercept) on each Axes in the instance's Axes list. The style of the line can be customized by passing a dictionary of keyword arguments for :func:`matplotlib.pyplot.plot`. :param pl_kwargs: A dictionary of keyword arguments to be passed to :func:`matplotlib.pyplot.plot` for styling of the line. If not provided, the line is plotted as an orange solid line with line ``linewidth=2.5``, ``zorder=3``, and labelled using the :meth:`generate_label_from_fit_params` method. :type pl_kwargs: dict, optional :raises ValueError: If pl_kwargs contains an argument not supported by :func:`matplotlib.pyplot.plot`. .. py:method:: add_plots(plot_data: bool = True, plot_fit_points: bool = True, plot_fit_lines: bool = True, fit_shading: bool = True, data_kwargs: dict = None, points_kwargs: dict = None, line_kwargs: dict = None, shading_kwargs: dict = None) Generate and add various types of plots to the Axes in the instance's Axes list. Depending on the boolean values of ``plot_data``, ``plot_fit_points``, ``plot_fit_lines``, and ``fit_shading``, this method determines which types of plots to generate and include. This includes the data points plot, fitting points, line of best fit, and shading between the line of best fit and the x-axis. :param plot_data: Determines if the analysis :math:`x` and :math:`y` points should be plotted. :type plot_data: bool, optional :param Defaults to True.: :param plot_fit_points: Determines if the fit points should be plotted. Defaults to True. :type plot_fit_points: bool, optional :param plot_fit_lines: Determines if the line of best fit should be plotted. Defaults to True. :type plot_fit_lines: bool, optional :param fit_shading: Determines if shading should be applied to the plots. Defaults to True. :type fit_shading: bool, optional :param data_kwargs: Keyword arguments for styling the data plot. :type data_kwargs: dict, optional :param points_kwargs: Keyword arguments for styling the fit points plot. :type points_kwargs: dict, optional :param line_kwargs: Keyword arguments for styling the line of best fit. :type line_kwargs: dict, optional :param shading_kwargs: Keyword arguments for styling the shading. :type shading_kwargs: dict, optional :raises ValueError: If any of the keyword argument dictionaries contain unsupported arguments. .. seealso:: * :meth:`add_data_plots`: Method used to plot the :math:`x` and :math:`y` data. * :meth:`add_fit_points`: Method used to plot the fit points. * :meth:`add_fit_lines`: Method used to plot the line of best fit. * :meth:`add_shading_plots`: Method used to add shading to the plots. .. py:method:: generate_figure(plot_data: bool = True, plot_fit_points: bool = True, plot_fit_lines: bool = True, fit_shading: bool = True, data_kwargs: dict = None, points_kwargs: dict = None, line_kwargs: dict = None, shading_kwargs: dict = None) Generates the complete figure for graphical analysis. This function is the preferred way for a user to interact with this class. It sets up and adds the desired plots to the figure, adds the labels and legend, and sets the title and scale for the plots. By default, we generate a figure where each panel has the analysis :math:`x` and :math:`y` data, the points used for the fitting, a shading over the region for the fit, and the fit line. :param plot_data: Determines if the :math:`x` and :math:`y` data points should be plotted. :type plot_data: bool, optional :param Defaults to True.: :param plot_fit_points: Determines if the fit points should be plotted. Defaults to True. :type plot_fit_points: bool, optional :param plot_fit_lines: Determines if the line of best fit should be plotted. Defaults to True. :type plot_fit_lines: bool, optional :param fit_shading: Determines if shading should be applied to the plots. Defaults to True. :type fit_shading: bool, optional :param data_kwargs: Keyword arguments for styling the data plot. :type data_kwargs: dict, optional :param points_kwargs: Keyword arguments for styling the fit points plot. :type points_kwargs: dict, optional :param line_kwargs: Keyword arguments for styling the line of best fit. :type line_kwargs: dict, optional :param shading_kwargs: Keyword arguments for styling the shading. :type shading_kwargs: dict, optional .. seealso:: * :func:`add_plots`: Composite function that adds different types of plots. * :func:`add_figure_axes_labels_and_legend`: Adds labels and a legend to the figure. (To be implemented in a specific class) .. py:method:: calculate_fit_params() Calculates the parameters (slope, intercept, r_squared) for line fitting. This function fits a line to the :math:`x` and :math:`y` values that are generated, beyond the provided threshold. The fit line is computed using Least Square fitting with R-squared method. .. seealso:: * :func:`calculate_valid_indicies_and_x_and_y`: Method used to generate the x and y values. * :func:`petpal.graphical_analysis.fit_line_to_data_using_lls_with_rsquared`: Method used to fit a line to data points using Least Square fitting with R-squared value. .. py:method:: calculate_valid_indicies_and_x_and_y() -> None :abstractmethod: Abstract method for calculating the :math:`x` and :math:`y` values given a particular analysis in a concrete class, valid indices where the denominator is 0, and the index corresponding to the provided threshold. This is a two-fold method: 1. Calculates valid x and y values derived from the analysis where each concrete class represents a different method. Valid points are those where the denominator (which varies by analysis type) is non-zero. 2. Saves the indices of the non-zero valid values and the indices that correspond to the given t_thresh_in_mins. .. important:: This abstract method must be implemented in each subclass representing a different analysis method. .. note:: The implementation of this function in subclasses MUST calculate and assign values to ``x``, ``y``, ``t_thresh_idx``, and ``non_zero_idx`` attributes. :raises NotImplementedError: This method needs to be implemented in a subclass. Example Implementation: :meth:`PatlakPlot.calculate_valid_indicies_and_x_and_y`: This class provides an example implementation of this method in a concrete subclass. .. py:method:: generate_label_from_fit_params() -> str :abstractmethod: Abstract method to generate a label string from fitting parameters. This function reads the fitting parameters 'slope', 'intercept', and 'r_squared' from the class attribute 'fit_params', and formats them into a string that can be used as a label on plots or reports. .. important:: This abstract method must be implemented in each subclass representing a different analysis method. :raises NotImplementedError: This method needs to be implemented in a subclass. Example Implementation: :meth:`PatlakPlot.generate_label_from_fit_params`: This method provides an example implementation of this abstract method in a concrete subclass. Similarly, :meth:`LoganPlot.generate_label_from_fit_params`. .. py:method:: add_figure_axes_labels_and_legend() :abstractmethod: Abstract method for adding analysis specific titles, axes labels and a legend to the figure. .. important:: This abstract method must be implemented in each subclass representing a different analysis method. :raises NotImplementedError: This method must be implemented in each subclass. Example Implementation: For an example of implementing this method, see :meth:`PatlakPlot.add_figure_axes_labels_and_legend`, or :meth:`LoganPlot.add_figure_axes_labels_and_legend`.