PatlakPlot#

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

Bases: GraphicalAnalysisPlot

This class handles generation of Patlak plots for PET analysis.

The PatlakPlot class is designed to process PET data and display it in the form of Patlak plots. The class handles data processing including computation of valid indices and calculation of plot-specific parameters, setting of plot labels and legends, as well as the actual plotting of data.

The processing steps involve computations such as handling of non-zero indices in the plasma time-activity curve (pTAC), calculation of x and y coordinates for the Patlak plot, and generation of plot labeling information.

The class also provides a capability to add labels, legends and title to the figure to present the data in a meaningful way.

Note

The class inherits from the GraphicalAnalysisPlot abstract base class.

Example

In the proceeding examples, pTAC represent the plasma TAC (or input TAC) and tTAC represents the tissue TAC.

For the quickest way to generate the Patlak Plot, we just instantiate the class and run the generate_figure() method. This will generate 2 plots in a row. The first one having a linear-linear scale, and the second one having a log-log scale.

from petpal.graphical_plots import PatlakPlot
patlak_plot = PatlakPlot(tTAC=tTAC, pTAC=pTAC, t_thresh_in_mins=45.0)
patlak_plot.generate_figure()
plt.show() # Or use plt.savefig() to save the figure.

If the default styling needs to be changed, we can pass keyword arguments to each of the plotting methods:

from petpal.graphical_plots import PatlakPlot
patlak_plot = PatlakPlot(tTAC=tTAC, pTAC=pTAC, t_thresh_in_mins=45.0)
patlak_plot.generate_figure(line_kwargs=dict(lw=2, alpha=0.95, color='red', label=patlak_plot.generate_label_from_fit_params()),
                            shading_kwargs=dict(color='palegreen', alpha=0.2),
                            data_kwargs=dict(alpha=0.85, color='k', marker='.'))

See also

LoganPlot
AltLoganPlot

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.

calculate_valid_indicies_and_x_and_y() → None#

Calculates the valid indices along with \(x\) and \(y\) for Patlak plot analysis.

This method performs the computation for the non-zero indices in the provided plasma time-activity curve (pTAC). It further calculates the values of \(x\) and \(y\) used in Patlak analysis based on these non-zero indices. This is done to avoid singularities caused by zero denominators. The Patlak \(x\) and \(y\) values are:

\[\begin{split}y&= \frac{R(t)}{C_\mathrm{P}(t)}\\ x&= \frac{\int_{0}^{t}C_\mathrm{P}(s)\mathrm{d}s}{C_\mathrm{P}(t)},\end{split}\]

where \(C_\mathrm{P}\) is the input function and \(R(t)\) is PET activity in the particular region of interest.

The method updates the instance variables x, y, non_zero_idx, and t_thresh_idx.

Returns:: None

generate_label_from_fit_params() → str#

Creates a label string from the fit parameters for graphical presentation.

This method retrieves slope, intercept, and R-squared values from the instance’s fit parameters, and then formats these values into a string that is LaTeX compatible for later rendering inside a plot’s label. For example:

\[\begin{split}K_{1}&=0.1\\ V_{\mathrm{T}}&=0.2\\ R^{2}&=0.95\end{split}\]

Returns:: str – The created label. Each parameter is formatted as a separate line.

add_figure_axes_labels_and_legend()#

Adds labels and a legend to the axes of the figure.

This method sets the x_label and y_label for all axes on the figure. It also adds a legend to the figure, which is anchored to the upper left corner. Lastly, we also give a title to the figure: Patlak Plots.

The labels are set to:

\[\begin{split}\begin{align*} y&= \frac{R(t)}{C_\mathrm{P}(t)}\\ x&= \frac{\int_{0}^{t}C_\mathrm{P}(s)\mathrm{d}s}{C_\mathrm{P}(t)}, \end{align*}\end{split}\]

where \(C_\mathrm{P}\) is the input function and \(R(t)\) is PET activity in the particular region of interest.

See also

calculate_valid_indicies_and_x_and_y() for the calculation implementation.

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.

PatlakPlot#

This Page