PredictedVsActualPlot#

class chemotools.plotting.PredictedVsActualPlot(y_true: ndarray, y_pred: ndarray, *, target_index: int = 0, color_by: ndarray | None = None, label: str | None = None, color: str | None = None, colormap: str | None = None, marker: str = 'o', add_ideal_line: bool = True, color_mode: Literal['continuous', 'categorical'] | None = None, colorbar_label: str = 'Value')[source]

Bases: BasePlot, ColoringMixin

Scatter plot of predicted vs actual values to assess regression fit.

This class creates scatter plots comparing predicted values against actual (true) values with an ideal prediction line (y=x). Useful for visually assessing model accuracy and detecting systematic errors or bias.

Parameters:

  • y_true (np.ndarray) – True (actual) y values with shape (n_samples,) for univariate or (n_samples, n_targets) for multivariate regression.

  • y_pred (np.ndarray) – Predicted y values with same shape as y_true.

  • target_index (int, optional) – For multivariate predictions, which target to plot (default: 0). Ignored if y_true/y_pred are 1D.

  • color_by (np.ndarray, optional) –

    Values for coloring samples. Can be either:

    • Continuous (numeric): shows colorbar

    • Categorical (strings/classes): shows legend with discrete colors

  • label (str, optional) – Legend label for this dataset (default: None).

  • color (str, optional) – Color for all points when color_by is None (default: auto-assigned).

  • colormap (str, optional) –

    Colormap name. Colorblind-friendly defaults:

    • ”tab10” for categorical data

    • ”viridis” for continuous data

  • marker (str, optional) – Marker style for scatter points (default: “o”). Examples: “o”, “s”, “^”, “v”, “D”.

  • add_ideal_line (bool, optional) – Whether to add diagonal y=x line showing ideal predictions (default: True).

  • color_mode ({"continuous", "categorical"}, optional) – Explicitly specify coloring mode. If None (default), automatically detects based on dtype and unique values of color_by.

  • colorbar_label (str, optional) – Label for the colorbar when using continuous coloring. Default is “Value”. Only applies when color_by is continuous.

Raises:

ValueError – If y_true and y_pred have mismatched shapes.

Examples

Basic predicted vs actual plot:

>>> plot = PredictedVsActualPlot(y_true, y_pred)
>>> fig = plot.show(title="Model Performance")

With categorical coloring (e.g., by batch):

>>> batches = np.array(['A', 'B', 'A', 'B', ...])
>>> plot = PredictedVsActualPlot(y_true, y_pred, color_by=batches)
>>> fig = plot.show(title="Predictions by Batch")

Multiple models compared:

>>> fig, ax = plt.subplots()
>>> PredictedVsActualPlot(y_true, y_pred_model1, label="Model 1", color="blue").render(ax)
>>> PredictedVsActualPlot(y_true, y_pred_model2, label="Model 2", color="red").render(ax)
>>> ax.legend()
>>> plt.show()

Multivariate regression:

>>> fig, axes = plt.subplots(1, 3, figsize=(15, 5))
>>> for i in range(3):
...     PredictedVsActualPlot(y_true, y_pred, target_index=i).render(axes[i])
...     axes[i].set_title(f"Target {i+1}")
>>> plt.tight_layout()
>>> plt.show()

Attributes

color_by

is_categorical

colormap

colorbar_label

show(*, figsize: Tuple[float, float] | None = None, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] | None = None, **kwargs: Any) → Figure[source]

Create and return a complete figure with the predicted vs axtual plot.

This method handles figure creation and then delegates to render().

Parameters:

  • figsize (tuple[float, float], optional) – Figure size in inches (width, height).

  • title (str, optional) – Figure title.

  • xlabel (str, optional) – Custom x-axis label. If None, uses existing label or default.

  • ylabel (str, optional) – Custom y-axis label. If None, uses existing label or default.

  • xlim (tuple[float, float], optional) – X-axis limits as (xmin, xmax).

  • ylim (tuple[float, float], optional) – Y-axis limits as (ymin, ymax).

  • **kwargs (Any) – Additional keyword arguments passed to the render() method.

Returns:

The matplotlib Figure object containing the plot.

Return type:

Figure

render(ax: Axes | None = None, *, xlabel: str | None = None, ylabel: str | None = None, xlim: tuple[float, float] | None = None, ylim: tuple[float, float] | None = None, **kwargs: Any) → tuple[Figure, Axes][source]

Render the plot on existing or new axes.

Parameters:

  • ax (Axes, optional) – Matplotlib axes to render on. If None, creates new figure/axes.

  • xlabel (str, optional) – Custom x-axis label. If None, uses existing label or default.

  • ylabel (str, optional) – Custom y-axis label. If None, uses existing label or default.

  • xlim (tuple[float, float], optional) – X-axis limits (min, max).

  • ylim (tuple[float, float], optional) – Y-axis limits (min, max).

  • **kwargs (Any) – Additional keyword arguments passed to scatter plot.

Returns:

The Figure and Axes objects containing the plot.

Return type:

tuple[Figure, Axes]

This Page