GraphicalAnalysisPlot

class petpal.visualizations.graphical_plots.GraphicalAnalysisPlot(pTAC: numpy.ndarray, tTAC: numpy.ndarray, t_thresh_in_mins: float, figObj: matplotlib.pyplot.Figure = None)

Bases: 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.

Variables:

• pTAC (np.ndarray) – The Input/Plasma TAC, an array containing time points and corresponding activity.

• tTAC (np.ndarray) – The Tissue/Region TAC, an array with time points and corresponding activity.

• t_thresh_in_mins (float) – The threshold time, in minutes, to consider in the analysis. Points are fit after this threshold.

• fig (plt.Figure) – A matplotlib Figure object where the plots will be drawn.

• ax_list (list) – A list of matplotlib Axes associated with fig where the plots will be drawn.

• non_zero_idx (np.ndarray) – Indexes of non-zero values in appropriate TAC (calculated in specific implementations).

• t_thresh_idx (int) – The index at which the time threshold is crossed in the TACs (calculated in specific implementations).

• x (np.ndarray) – The “x” values for plotting (calculated in specific implementations).

• y (np.ndarray) – The “y” values for plotting (calculated in specific implementations).

• fit_params (dict) – The parameters fit to the data using least squares. Contains ‘slope’, ‘intercept’, and ‘r_squared’ (calculated in specific implementations).

Important

This is an abstract class and should be inherited by a concrete class that implements the following methods:

• calculate_valid_indicies_and_x_and_y()

• generate_label_from_fit_params()

• 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.

Parameters:

• pTAC (np.ndarray) – The input Time Activity Curve, an array containing time points and corresponding activity.

• tTAC (np.ndarray) – The Tissue or Region Time Activity Curve, an array with time points and corresponding activity.

• t_thresh_in_mins (float) – The threshold time in minutes to consider when performing calculations for the plots.

• figObj (plt.Figure, optional) – An optional matplotlib Figure object. If not provided, a new Figure object is created.

Raises:

matplotlib error – Error handling for the plot generation is managed by matplotlib. Any exceptions thrown during plotting are handled by the matplotlib internally.

static generate_figure_and_axes(figObj: matplotlib.pyplot.Figure = None)

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.

Parameters:

figObj (plt.Figure, optional) – 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’.

Returns:

fig (plt.Figure) – The resulting matplotlib Figure object. ax_list (list): A list of Axes objects associated with ‘fig’.

Raises:

None –

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 \(x\) and \(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.

Parameters:

pl_kwargs (dict, optional) – 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'.

Raises:

ValueError – If pl_kwargs contains an argument not supported by matplotlib.pyplot.plot.

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 matplotlib.pyplot.axvspan().

Parameters:

pl_kwargs (dict, optional) – 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.

Raises:

ValueError – If pl_kwargs contains an argument not supported by matplotlib.pyplot.axvspan().

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 \(x\) and \(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 matplotlib.pyplot.plot().

Parameters:

pl_kwargs (dict, optional) – A dictionary of keyword arguments to be passed to 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.

Raises:

ValueError – If pl_kwargs contains an argument not supported by matplotlib.pyplot.plot().

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 matplotlib.pyplot.plot().

Parameters:

pl_kwargs (dict, optional) – A dictionary of keyword arguments to be passed to 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 generate_label_from_fit_params() method.

Raises:

ValueError – If pl_kwargs contains an argument not supported by matplotlib.pyplot.plot().

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.

Parameters:

• plot_data (bool, optional) – Determines if the analysis \(x\) and \(y\) points should be plotted.

• True. (Defaults to)

• plot_fit_points (bool, optional) – Determines if the fit points should be plotted. Defaults to True.

• plot_fit_lines (bool, optional) – Determines if the line of best fit should be plotted. Defaults to True.

• fit_shading (bool, optional) – Determines if shading should be applied to the plots. Defaults to True.

• data_kwargs (dict, optional) – Keyword arguments for styling the data plot.

• points_kwargs (dict, optional) – Keyword arguments for styling the fit points plot.

• line_kwargs (dict, optional) – Keyword arguments for styling the line of best fit.

• shading_kwargs (dict, optional) – Keyword arguments for styling the shading.

Raises:

ValueError – If any of the keyword argument dictionaries contain unsupported arguments.

See also

• add_data_plots(): Method used to plot the \(x\) and \(y\) data.

• add_fit_points(): Method used to plot the fit points.

• add_fit_lines(): Method used to plot the line of best fit.

• add_shading_plots(): Method used to add shading to the plots.

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 \(x\) and \(y\) data, the points used for the fitting, a shading over the region for the fit, and the fit line.

Parameters:

• plot_data (bool, optional) – Determines if the \(x\) and \(y\) data points should be plotted.

• True. (Defaults to)

• plot_fit_points (bool, optional) – Determines if the fit points should be plotted. Defaults to True.

• plot_fit_lines (bool, optional) – Determines if the line of best fit should be plotted. Defaults to True.

• fit_shading (bool, optional) – Determines if shading should be applied to the plots. Defaults to True.

• data_kwargs (dict, optional) – Keyword arguments for styling the data plot.

• points_kwargs (dict, optional) – Keyword arguments for styling the fit points plot.

• line_kwargs (dict, optional) – Keyword arguments for styling the line of best fit.

• shading_kwargs (dict, optional) – Keyword arguments for styling the shading.

See also

• add_plots(): Composite function that adds different types of plots.

• add_figure_axes_labels_and_legend(): Adds labels and a legend to the figure. (To be implemented in a specific class)

calculate_fit_params()

Calculates the parameters (slope, intercept, r_squared) for line fitting.

This function fits a line to the \(x\) and \(y\) values that are generated, beyond the provided threshold. The fit line is computed using Least Square fitting with R-squared method.

See also

• calculate_valid_indicies_and_x_and_y(): Method used to generate the x and y values.

• 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.

abstractmethod calculate_valid_indicies_and_x_and_y() → None

Abstract method for calculating the \(x\) and \(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:

PatlakPlot.calculate_valid_indicies_and_x_and_y(): This class provides an example implementation of this method in a concrete subclass.

abstractmethod generate_label_from_fit_params() → str

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:

PatlakPlot.generate_label_from_fit_params(): This method provides an example implementation of this abstract method in a concrete subclass. Similarly, LoganPlot.generate_label_from_fit_params().

abstractmethod add_figure_axes_labels_and_legend()

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 PatlakPlot.add_figure_axes_labels_and_legend(), or LoganPlot.add_figure_axes_labels_and_legend().