Visualization¶

Plotting functions.

plots ¶

Pure plotting functions for ALchemist visualizations.

All functions are framework-agnostic and return matplotlib Figure/Axes objects. They accept optional axes for embedding in existing figures.

create_parity_plot ¶

create_parity_plot(y_true: ndarray, y_pred: ndarray, y_std: Optional[ndarray] = None, sigma_multiplier: float = 1.96, show_error_bars: bool = True, show_metrics: bool = True, figsize: Tuple[float, float] = (8, 6), dpi: int = 100, title: Optional[str] = None, ax: Optional[Axes] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None, objective_label: Optional[str] = None) -> Tuple[Figure, Axes]

Create parity plot of actual vs predicted values.

Pure plotting function with no session or model dependencies.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Actual experimental values	required
`y_pred`	`ndarray`	Model predicted values	required
`y_std`	`Optional[ndarray]`	Prediction uncertainties (optional)	`None`
`sigma_multiplier`	`float`	Error bar size multiplier (1.96 = 95% CI)	`1.96`
`show_error_bars`	`bool`	Display uncertainty error bars	`True`
`show_metrics`	`bool`	Include RMSE/MAE/R² in title	`True`
`figsize`	`Tuple[float, float]`	Figure size (width, height) in inches	`(8, 6)`
`dpi`	`int`	Resolution in dots per inch	`100`
`title`	`Optional[str]`	Custom title (auto-generated if None and show_metrics=True)	`None`
`ax`	`Optional[Axes]`	Existing axes to plot on (creates new if None)	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`
`objective_label`	`Optional[str]`	Optional objective display name; when provided, axis labels become 'Actual ' / 'Predicted '.	`None`

Returns:

Type	Description
`Tuple[Figure, Axes]`	Tuple of (Figure, Axes) objects

Example

fig, ax = create_parity_plot(y_true, y_pred, y_std) fig.savefig('parity.png', dpi=300, bbox_inches='tight')

create_contour_plot ¶

create_contour_plot(x_grid: ndarray, y_grid: ndarray, predictions_grid: ndarray, x_var: str, y_var: str, exp_x: Optional[ndarray] = None, exp_y: Optional[ndarray] = None, suggest_x: Optional[ndarray] = None, suggest_y: Optional[ndarray] = None, cmap: str = 'viridis', use_log_scale: bool = False, figsize: Tuple[float, float] = (8, 6), dpi: int = 100, title: str = 'Contour Plot of Model Predictions', ax: Optional[Axes] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Axes, Any]

Create 2D contour plot of model predictions.

Parameters:

Name	Type	Description	Default
`x_grid`	`ndarray`	X-axis meshgrid values (2D array)	required
`y_grid`	`ndarray`	Y-axis meshgrid values (2D array)	required
`predictions_grid`	`ndarray`	Model predictions on grid (2D array)	required
`x_var`	`str`	X variable name for axis label	required
`y_var`	`str`	Y variable name for axis label	required
`exp_x`	`Optional[ndarray]`	Experimental X values to overlay (optional)	`None`
`exp_y`	`Optional[ndarray]`	Experimental Y values to overlay (optional)	`None`
`suggest_x`	`Optional[ndarray]`	Suggested X values to overlay (optional)	`None`
`suggest_y`	`Optional[ndarray]`	Suggested Y values to overlay (optional)	`None`
`cmap`	`str`	Matplotlib colormap name	`'viridis'`
`use_log_scale`	`bool`	Use logarithmic color scale for values spanning orders of magnitude	`False`
`figsize`	`Tuple[float, float]`	Figure size (width, height) in inches	`(8, 6)`
`dpi`	`int`	Resolution	`100`
`title`	`str`	Plot title	`'Contour Plot of Model Predictions'`
`ax`	`Optional[Axes]`	Existing axes (creates new if None)	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Axes, Any]`	Tuple of (Figure, Axes, Colorbar) - includes colorbar reference for management

Example

X, Y = np.meshgrid(x_range, y_range) Z = model_predictions.reshape(X.shape) fig, ax, cbar = create_contour_plot(X, Y, Z, 'temperature', 'pressure')

create_slice_plot ¶

create_slice_plot(x_values: ndarray, predictions: ndarray, x_var: str, std: Optional[ndarray] = None, sigma_bands: Optional[List[float]] = None, exp_x: Optional[ndarray] = None, exp_y: Optional[ndarray] = None, figsize: Tuple[float, float] = (8, 6), dpi: int = 100, title: Optional[str] = None, ax: Optional[Axes] = None, prediction_label: str = 'Prediction', line_color: Optional[str] = None, line_width: Optional[float] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Axes]

Create 1D slice plot with uncertainty bands.

Shows model predictions along one variable while other variables are held fixed. Optionally displays uncertainty bands at multiple sigma levels.

Parameters:

Name	Type	Description	Default
`x_values`	`ndarray`	X-axis values (1D array)	required
`predictions`	`ndarray`	Mean predictions (1D array)	required
`x_var`	`str`	Variable name for X-axis label	required
`std`	`Optional[ndarray]`	Standard deviations (1D array, optional)	`None`
`sigma_bands`	`Optional[List[float]]`	List of sigma values for uncertainty bands (e.g., [1.0, 2.0])	`None`
`exp_x`	`Optional[ndarray]`	Experimental X values to overlay (optional)	`None`
`exp_y`	`Optional[ndarray]`	Experimental Y values to overlay (optional)	`None`
`figsize`	`Tuple[float, float]`	Figure size (width, height) in inches	`(8, 6)`
`dpi`	`int`	Resolution	`100`
`title`	`Optional[str]`	Custom title (optional)	`None`
`ax`	`Optional[Axes]`	Existing axes (creates new if None)	`None`
`prediction_label`	`str`	Label for the prediction line in legend (default: 'Prediction')	`'Prediction'`
`line_color`	`Optional[str]`	Color for the prediction line (default: dark blue)	`None`
`line_width`	`Optional[float]`	Width of the prediction line (default: 2.6)	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Axes]`	Tuple of (Figure, Axes)

Example

x = np.linspace(20, 100, 100) y_pred, y_std = model.predict(X_grid, return_std=True) fig, ax = create_slice_plot(x, y_pred, 'temperature', ... std=y_std, sigma_bands=[1.0, 2.0])

create_voxel_plot ¶

create_voxel_plot(x_grid: ndarray, y_grid: ndarray, z_grid: ndarray, predictions_grid: ndarray, x_var: str, y_var: str, z_var: str, exp_x: Optional[ndarray] = None, exp_y: Optional[ndarray] = None, exp_z: Optional[ndarray] = None, suggest_x: Optional[ndarray] = None, suggest_y: Optional[ndarray] = None, suggest_z: Optional[ndarray] = None, cmap: str = 'viridis', alpha: float = 0.5, use_log_scale: bool = False, figsize: Tuple[float, float] = (10, 8), dpi: int = 100, title: str = '3D Voxel Plot of Model Predictions', ax: Optional[Any] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Any]

Create 3D voxel plot of model predictions over a variable space.

Visualizes the model's predicted response surface by varying three variables while holding others constant. Uses volumetric rendering to show the 3D prediction landscape.

Parameters:

Name	Type	Description	Default
`x_grid`	`ndarray`	X-axis meshgrid values (3D array)	required
`y_grid`	`ndarray`	Y-axis meshgrid values (3D array)	required
`z_grid`	`ndarray`	Z-axis meshgrid values (3D array)	required
`predictions_grid`	`ndarray`	Model predictions on grid (3D array)	required
`x_var`	`str`	X variable name for axis label	required
`y_var`	`str`	Y variable name for axis label	required
`z_var`	`str`	Z variable name for axis label	required
`exp_x`	`Optional[ndarray]`	Experimental X values to overlay (optional)	`None`
`exp_y`	`Optional[ndarray]`	Experimental Y values to overlay (optional)	`None`
`exp_z`	`Optional[ndarray]`	Experimental Z values to overlay (optional)	`None`
`suggest_x`	`Optional[ndarray]`	Suggested X values to overlay (optional)	`None`
`suggest_y`	`Optional[ndarray]`	Suggested Y values to overlay (optional)	`None`
`suggest_z`	`Optional[ndarray]`	Suggested Z values to overlay (optional)	`None`
`cmap`	`str`	Matplotlib colormap name	`'viridis'`
`alpha`	`float`	Transparency level (0=transparent, 1=opaque)	`0.5`
`use_log_scale`	`bool`	Use logarithmic color scale	`False`
`figsize`	`Tuple[float, float]`	Figure size (width, height) in inches	`(10, 8)`
`dpi`	`int`	Resolution	`100`
`title`	`str`	Plot title	`'3D Voxel Plot of Model Predictions'`
`ax`	`Optional[Any]`	Existing 3D axes (creates new if None)	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Any]`	Tuple of (Figure, Axes3D) objects

Example

Create 3D grid¶

x = np.linspace(0, 10, 20) y = np.linspace(0, 10, 20) z = np.linspace(0, 10, 20) X, Y, Z = np.meshgrid(x, y, z) predictions = model.predict(grid) fig, ax = create_voxel_plot(X, Y, Z, predictions, 'temp', 'pressure', 'flow')

Note

Requires 3D arrays for x_grid, y_grid, z_grid, predictions_grid
Use alpha to control transparency (lower values show interior structure)
Computationally expensive for high-resolution grids

create_metrics_plot ¶

create_metrics_plot(training_sizes: ndarray, metric_values: ndarray, metric_name: str, figsize: Tuple[float, float] = (8, 6), dpi: int = 100, ax: Optional[Axes] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Axes]

Create learning curve plot showing metric vs training size.

Displays how model performance improves as more experimental data is added.

Parameters:

Name	Type	Description	Default
`training_sizes`	`ndarray`	X-axis values (number of observations)	required
`metric_values`	`ndarray`	Y-axis values (metric at each training size)	required
`metric_name`	`str`	Metric name ('rmse', 'mae', 'r2', 'mape')	required
`figsize`	`Tuple[float, float]`	Figure size (width, height) in inches	`(8, 6)`
`dpi`	`int`	Resolution	`100`
`ax`	`Optional[Axes]`	Existing axes (creates new if None)	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Axes]`	Tuple of (Figure, Axes)

Example

sizes = np.array([5, 6, 7, 8, 9, 10]) rmse = np.array([0.15, 0.12, 0.10, 0.08, 0.07, 0.06]) fig, ax = create_metrics_plot(sizes, rmse, 'rmse')

create_qq_plot ¶

create_qq_plot(z_scores: ndarray, figsize: Tuple[float, float] = (8, 6), dpi: int = 100, show_confidence_bands: bool = True, title: str = 'Q-Q Plot: Standardized Residuals', ax: Optional[Axes] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Axes]

Create Q-Q plot of standardized residuals.

Compares the distribution of standardized residuals to a standard normal distribution. Points following the diagonal line indicate well-calibrated uncertainty estimates.

Parameters:

Name	Type	Description	Default
`z_scores`	`ndarray`	Standardized residuals (z-scores)	required
`figsize`	`Tuple[float, float]`	Figure size (width, height) in inches	`(8, 6)`
`dpi`	`int`	Resolution	`100`
`show_confidence_bands`	`bool`	Add approximate 95% CI bands for small samples	`True`
`title`	`str`	Plot title	`'Q-Q Plot: Standardized Residuals'`
`ax`	`Optional[Axes]`	Existing axes (creates new if None)	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Axes]`	Tuple of (Figure, Axes)

Example

z = (y_true - y_pred) / y_std fig, ax = create_qq_plot(z)

create_calibration_plot ¶

create_calibration_plot(nominal_probs: ndarray, empirical_coverage: ndarray, figsize: Tuple[float, float] = (8, 6), dpi: int = 100, title: str = 'Calibration Curve', ax: Optional[Axes] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Axes]

Create calibration curve (reliability diagram).

Shows whether predicted confidence intervals have the correct coverage. Points on the diagonal line indicate well-calibrated uncertainty. Points above the line indicate underconfident predictions (intervals too wide). Points below the line indicate overconfident predictions (intervals too narrow).

Parameters:

Name	Type	Description	Default
`nominal_probs`	`ndarray`	Expected coverage probabilities (X-axis)	required
`empirical_coverage`	`ndarray`	Observed coverage fractions (Y-axis)	required
`figsize`	`Tuple[float, float]`	Figure size (width, height) in inches	`(8, 6)`
`dpi`	`int`	Resolution	`100`
`title`	`str`	Plot title	`'Calibration Curve'`
`ax`	`Optional[Axes]`	Existing axes (creates new if None)	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Axes]`	Tuple of (Figure, Axes)

Example

nominal = np.array([0.68, 0.95, 0.99]) empirical = np.array([0.72, 0.94, 0.98]) fig, ax = create_calibration_plot(nominal, empirical)

create_regret_plot ¶

create_regret_plot(iterations: ndarray, observed_values: ndarray, show_cumulative: bool = False, goal: str = 'maximize', predicted_means: Optional[ndarray] = None, predicted_stds: Optional[ndarray] = None, sigma_bands: Optional[List[float]] = None, figsize: Tuple[float, float] = (8, 6), dpi: int = 100, title: Optional[str] = None, ax: Optional[Axes] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Axes]

Create regret curve (best observed value vs iteration).

Shows the cumulative best result achieved over the course of optimization. A flattening curve indicates convergence (no further improvements found).

This is also known as "simple regret" or "incumbent trajectory" in the Bayesian optimization literature.

Parameters:

Name	Type	Description	Default
`iterations`	`ndarray`	Iteration numbers (typically 0, 1, 2, ... or experiment indices)	required
`observed_values`	`ndarray`	Actual experimental outputs at each iteration	required
`goal`	`str`	'maximize' or 'minimize' - determines how "best" is computed	`'maximize'`
`predicted_means`	`Optional[ndarray]`	Optional array of max(posterior mean) at each iteration	`None`
`predicted_stds`	`Optional[ndarray]`	Optional array of std at max(posterior mean) at each iteration	`None`
`sigma_bands`	`Optional[List[float]]`	List of sigma values for uncertainty bands (e.g., [1.0, 2.0])	`None`
`figsize`	`Tuple[float, float]`	Figure size (width, height) in inches	`(8, 6)`
`dpi`	`int`	Resolution	`100`
`title`	`Optional[str]`	Custom title (auto-generated if None)	`None`
`ax`	`Optional[Axes]`	Existing axes (creates new if None)	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Axes]`	Tuple of (Figure, Axes)

Example

iterations = np.arange(len(outputs)) fig, ax = create_regret_plot(iterations, outputs, goal='maximize')

Notes

For maximization, plots cumulative maximum (best so far). For minimization, plots cumulative minimum (best so far). Curve should increase/decrease monotonically and flatten at convergence. If predicted_means/stds provided, also shows model's predicted best with uncertainty.

create_probability_of_improvement_plot ¶

create_probability_of_improvement_plot(iterations: ndarray, max_pi_values: ndarray, figsize: Tuple[float, float] = (8, 6), dpi: int = 100, title: Optional[str] = None, ax: Optional[Axes] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Axes]

Create probability of improvement convergence curve.

Shows the maximum probability of improvement (PI) available in the search space at each iteration. As optimization progresses and good regions are explored, max(PI) should decrease, indicating convergence.

This is computed retroactively by: 1. Training GP incrementally with observations 0:i 2. Computing PI across the search space 3. Taking the maximum PI value

Parameters:

Name	Type	Description	Default
`iterations`	`ndarray`	Iteration numbers where PI was evaluated	required
`max_pi_values`	`ndarray`	Maximum PI value in search space at each iteration	required
`figsize`	`Tuple[float, float]`	Figure size (width, height) in inches	`(8, 6)`
`dpi`	`int`	Resolution	`100`
`title`	`Optional[str]`	Custom title (auto-generated if None)	`None`
`ax`	`Optional[Axes]`	Existing axes (creates new if None)	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Axes]`	Tuple of (Figure, Axes)

Example

Computed retroactively from session¶

fig = session.plot_probability_of_improvement()

Notes

Values range from 0 to 1 (probabilities)
Decreasing trend indicates optimization converging
Values near 0 suggest little room for improvement
Useful for determining stopping criteria

create_uncertainty_contour_plot ¶

create_uncertainty_contour_plot(x_grid: ndarray, y_grid: ndarray, uncertainty_grid: ndarray, x_var: str, y_var: str, exp_x: Optional[ndarray] = None, exp_y: Optional[ndarray] = None, suggest_x: Optional[ndarray] = None, suggest_y: Optional[ndarray] = None, cmap: str = 'Reds', figsize: Tuple[float, float] = (8, 6), dpi: int = 100, title: str = 'Posterior Uncertainty (Standard Deviation)', ax: Optional[Axes] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Axes, Any]

Create 2D contour plot of posterior uncertainty (standard deviation).

Visualizes where the model is most uncertain about predictions, showing regions that may benefit from additional sampling. Higher values indicate greater uncertainty.

Parameters:

Name	Type	Description	Default
`x_grid`	`ndarray`	X-axis meshgrid values (2D array)	required
`y_grid`	`ndarray`	Y-axis meshgrid values (2D array)	required
`uncertainty_grid`	`ndarray`	Posterior standard deviations on grid (2D array)	required
`x_var`	`str`	X variable name for axis label	required
`y_var`	`str`	Y variable name for axis label	required
`exp_x`	`Optional[ndarray]`	Experimental X values to overlay (optional)	`None`
`exp_y`	`Optional[ndarray]`	Experimental Y values to overlay (optional)	`None`
`suggest_x`	`Optional[ndarray]`	Suggested X values to overlay (optional)	`None`
`suggest_y`	`Optional[ndarray]`	Suggested Y values to overlay (optional)	`None`
`cmap`	`str`	Matplotlib colormap name (default: 'Reds' - darker = more uncertain)	`'Reds'`
`figsize`	`Tuple[float, float]`	Figure size (width, height) in inches	`(8, 6)`
`dpi`	`int`	Resolution	`100`
`title`	`str`	Plot title	`'Posterior Uncertainty (Standard Deviation)'`
`ax`	`Optional[Axes]`	Existing axes (creates new if None)	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Axes, Any]`	Tuple of (Figure, Axes, Colorbar)

Example

X, Y = np.meshgrid(x_range, y_range) _, std = model.predict(grid, return_std=True) uncertainty = std.reshape(X.shape) fig, ax, cbar = create_uncertainty_contour_plot(X, Y, uncertainty, 'temp', 'pressure')

Note

Useful for identifying under-explored regions
Typically used with 'Reds' or 'YlOrRd' colormaps
High uncertainty near data gaps is expected
Can guide where to sample next for exploration

create_uncertainty_voxel_plot ¶

create_uncertainty_voxel_plot(x_grid: ndarray, y_grid: ndarray, z_grid: ndarray, uncertainty_grid: ndarray, x_var: str, y_var: str, z_var: str, exp_x: Optional[ndarray] = None, exp_y: Optional[ndarray] = None, exp_z: Optional[ndarray] = None, suggest_x: Optional[ndarray] = None, suggest_y: Optional[ndarray] = None, suggest_z: Optional[ndarray] = None, cmap: str = 'Reds', alpha: float = 0.5, figsize: Tuple[float, float] = (10, 8), dpi: int = 100, title: str = '3D Posterior Uncertainty', ax: Optional[Any] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Any]

Create 3D voxel plot of posterior uncertainty over variable space.

Visualizes where the model is most uncertain in 3D, helping identify under-explored regions that may benefit from additional sampling.

Parameters:

Name	Type	Description	Default
`x_grid`	`ndarray`	X-axis meshgrid values (3D array)	required
`y_grid`	`ndarray`	Y-axis meshgrid values (3D array)	required
`z_grid`	`ndarray`	Z-axis meshgrid values (3D array)	required
`uncertainty_grid`	`ndarray`	Posterior standard deviations on grid (3D array)	required
`x_var`	`str`	X variable name for axis label	required
`y_var`	`str`	Y variable name for axis label	required
`z_var`	`str`	Z variable name for axis label	required
`exp_x`	`Optional[ndarray]`	Experimental X values to overlay (optional)	`None`
`exp_y`	`Optional[ndarray]`	Experimental Y values to overlay (optional)	`None`
`exp_z`	`Optional[ndarray]`	Experimental Z values to overlay (optional)	`None`
`suggest_x`	`Optional[ndarray]`	Suggested X values to overlay (optional)	`None`
`suggest_y`	`Optional[ndarray]`	Suggested Y values to overlay (optional)	`None`
`suggest_z`	`Optional[ndarray]`	Suggested Z values to overlay (optional)	`None`
`cmap`	`str`	Matplotlib colormap name (default: 'Reds')	`'Reds'`
`alpha`	`float`	Transparency level (0=transparent, 1=opaque)	`0.5`
`figsize`	`Tuple[float, float]`	Figure size (width, height) in inches	`(10, 8)`
`dpi`	`int`	Resolution	`100`
`title`	`str`	Plot title	`'3D Posterior Uncertainty'`
`ax`	`Optional[Any]`	Existing 3D axes (creates new if None)	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Any]`	Tuple of (Figure, Axes3D) objects

Example

X, Y, Z = np.meshgrid(x, y, z, indexing='ij') _, std = model.predict(grid, return_std=True) uncertainty = std.reshape(X.shape) fig, ax = create_uncertainty_voxel_plot(X, Y, Z, uncertainty, 'temp', 'press', 'flow')

Note

Higher values = greater uncertainty
Useful for planning exploration strategies
Shows data-sparse regions in 3D
Computationally expensive (O(N³) evaluations)

create_acquisition_voxel_plot ¶

create_acquisition_voxel_plot(x_grid: ndarray, y_grid: ndarray, z_grid: ndarray, acquisition_grid: ndarray, x_var: str, y_var: str, z_var: str, exp_x: Optional[ndarray] = None, exp_y: Optional[ndarray] = None, exp_z: Optional[ndarray] = None, suggest_x: Optional[ndarray] = None, suggest_y: Optional[ndarray] = None, suggest_z: Optional[ndarray] = None, cmap: str = 'hot', alpha: float = 0.5, use_log_scale: bool = False, figsize: Tuple[float, float] = (10, 8), dpi: int = 100, title: str = '3D Acquisition Function', ax: Optional[Any] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Any]

Create 3D voxel plot of acquisition function over variable space.

Visualizes the acquisition function in 3D, showing "hot spots" where the optimization algorithm believes the next experiment should be conducted. Higher values indicate more promising regions.

Parameters:

Name	Type	Description	Default
`x_grid`	`ndarray`	X-axis meshgrid values (3D array)	required
`y_grid`	`ndarray`	Y-axis meshgrid values (3D array)	required
`z_grid`	`ndarray`	Z-axis meshgrid values (3D array)	required
`acquisition_grid`	`ndarray`	Acquisition function values on grid (3D array)	required
`x_var`	`str`	X variable name for axis label	required
`y_var`	`str`	Y variable name for axis label	required
`z_var`	`str`	Z variable name for axis label	required
`exp_x`	`Optional[ndarray]`	Experimental X values to overlay (optional)	`None`
`exp_y`	`Optional[ndarray]`	Experimental Y values to overlay (optional)	`None`
`exp_z`	`Optional[ndarray]`	Experimental Z values to overlay (optional)	`None`
`suggest_x`	`Optional[ndarray]`	Suggested X values to overlay (optional)	`None`
`suggest_y`	`Optional[ndarray]`	Suggested Y values to overlay (optional)	`None`
`suggest_z`	`Optional[ndarray]`	Suggested Z values to overlay (optional)	`None`
`cmap`	`str`	Matplotlib colormap name (default: 'hot')	`'hot'`
`alpha`	`float`	Transparency level (0=transparent, 1=opaque)	`0.5`
`use_log_scale`	`bool`	Use logarithmic color scale	`False`
`figsize`	`Tuple[float, float]`	Figure size (width, height) in inches	`(10, 8)`
`dpi`	`int`	Resolution	`100`
`title`	`str`	Plot title	`'3D Acquisition Function'`
`ax`	`Optional[Any]`	Existing 3D axes (creates new if None)	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Any]`	Tuple of (Figure, Axes3D) objects

Example

X, Y, Z = np.meshgrid(x, y, z, indexing='ij') acq_values = evaluate_acquisition(model, grid, acq_func='ei') acq_grid = acq_values.reshape(X.shape) fig, ax = create_acquisition_voxel_plot(X, Y, Z, acq_grid, 'temp', 'press', 'flow')

Note

Higher values = more promising for next experiment
Use with EI, PI, UCB, or other acquisition functions
Helps visualize exploration-exploitation tradeoff
Suggestions should align with high-value regions
Computationally expensive (O(N³) evaluations)

create_pareto_plot ¶

create_pareto_plot(Y: ndarray, pareto_mask: ndarray, objective_names: List[str], directions: Optional[List[str]] = None, ref_point: Optional[List[float]] = None, show_hypervolume: bool = True, suggested_points: Optional[ndarray] = None, constraint_boundaries: Optional[Dict[str, float]] = None, figsize=(8, 6), dpi=100, title=None, ax=None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Axes]

Create a Pareto frontier plot for 2-objective optimization.

Parameters:

Name	Type	Description	Default
`Y`	`ndarray`	(n_samples, n_objectives) array of observed objective values	required
`pareto_mask`	`ndarray`	Boolean mask identifying Pareto-optimal points	required
`objective_names`	`List[str]`	Names for each objective axis	required
`directions`	`Optional[List[str]]`	'maximize' or 'minimize' per objective (default: all maximize)	`None`
`ref_point`	`Optional[List[float]]`	Reference point for hypervolume shading	`None`
`show_hypervolume`	`bool`	Whether to shade the dominated hypervolume region	`True`
`suggested_points`	`Optional[ndarray]`	(n, 2) array of newly suggested points to overlay	`None`
`constraint_boundaries`	`Optional[Dict[str, float]]`	{objective_name: value} for dashed constraint lines	`None`
`figsize`		Figure size	`(8, 6)`
`dpi`		Figure DPI	`100`
`title`		Optional title	`None`
`ax`		Optional existing Axes	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Axes]`	(Figure, Axes)

create_hypervolume_convergence_plot ¶

create_hypervolume_convergence_plot(iterations: ndarray, observed_hv: ndarray, show_cumulative: bool = False, predicted_hv: Optional[ndarray] = None, predicted_hv_std: Optional[ndarray] = None, sigma_bands: Optional[List[float]] = None, ref_point: Optional[List[float]] = None, figsize: Tuple[float, float] = (8, 6), dpi: int = 100, title: Optional[str] = None, ax: Optional[Axes] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Axes]

Create hypervolume convergence plot for multi-objective optimization.

Mirrors create_regret_plot() in style and behaviour but uses hypervolume as the progress metric.

Scatter points show the observed Pareto-front hypervolume at each iteration.
An optional cumulative-best line is shown when show_cumulative is True.
When predicted_hv (and optionally predicted_hv_std + sigma_bands) are provided, a model-predicted hypervolume line with uncertainty bands is overlaid — analogous to the "max posterior mean" line in the single-objective regret plot.

Parameters:

Name	Type	Description	Default
`iterations`	`ndarray`	1-based iteration indices.	required
`observed_hv`	`ndarray`	Hypervolume of the observed Pareto front at each iteration.	required
`show_cumulative`	`bool`	Show cumulative best HV line (default False).	`False`
`predicted_hv`	`Optional[ndarray]`	Model-predicted hypervolume at each iteration (optional).	`None`
`predicted_hv_std`	`Optional[ndarray]`	Std of predicted hypervolume (optional).	`None`
`sigma_bands`	`Optional[List[float]]`	Sigma multipliers for uncertainty bands (e.g. [1.0, 2.0]).	`None`
`ref_point`	`Optional[List[float]]`	Reference point used for hypervolume (annotated if given).	`None`
`figsize`	`Tuple[float, float]`	Figure size.	`(8, 6)`
`dpi`	`int`	Figure DPI.	`100`
`title`	`Optional[str]`	Custom title.	`None`
`ax`	`Optional[Axes]`	Pre-existing axes.	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Axes]`	(Figure, Axes)

create_surface_plot ¶

create_surface_plot(x_grid: ndarray, y_grid: ndarray, predictions_grid: ndarray, x_var: str, y_var: str, output_label: str = 'Predicted Output', exp_x: Optional[ndarray] = None, exp_y: Optional[ndarray] = None, exp_output: Optional[ndarray] = None, suggest_x: Optional[ndarray] = None, suggest_y: Optional[ndarray] = None, cmap: str = 'viridis', alpha: float = 0.9, figsize: Tuple[float, float] = (10, 8), dpi: int = 100, title: str = '3D Surface Plot of Model Predictions', ax: Optional[Any] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Any, Any]

Create 3D surface plot of model predictions.

Like the 2D contour plot, varies two variables (X, Y) while holding others fixed, but renders the predicted output on the Z axis as a 3D surface colored by the prediction values.

Parameters:

Name	Type	Description	Default
`x_grid`	`ndarray`	X-axis meshgrid values (2D array)	required
`y_grid`	`ndarray`	Y-axis meshgrid values (2D array)	required
`predictions_grid`	`ndarray`	Model predictions on grid (2D array, same shape as x_grid)	required
`x_var`	`str`	X variable name for axis label	required
`y_var`	`str`	Y variable name for axis label	required
`output_label`	`str`	Z-axis label (default: "Predicted Output")	`'Predicted Output'`
`exp_x`	`Optional[ndarray]`	Experimental X values to overlay (optional)	`None`
`exp_y`	`Optional[ndarray]`	Experimental Y values to overlay (optional)	`None`
`exp_output`	`Optional[ndarray]`	Experimental output values to overlay (optional)	`None`
`suggest_x`	`Optional[ndarray]`	Suggested X values to overlay (optional)	`None`
`suggest_y`	`Optional[ndarray]`	Suggested Y values to overlay (optional)	`None`
`cmap`	`str`	Matplotlib colormap name	`'viridis'`
`alpha`	`float`	Surface transparency (0=transparent, 1=opaque)	`0.9`
`figsize`	`Tuple[float, float]`	Figure size (width, height) in inches	`(10, 8)`
`dpi`	`int`	Resolution	`100`
`title`	`str`	Plot title	`'3D Surface Plot of Model Predictions'`
`ax`	`Optional[Any]`	Existing 3D axes (creates new if None)	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Any, Any]`	Tuple of (Figure, Axes3D, Colorbar)

Example

X, Y = np.meshgrid(x_range, y_range) Z = model_predictions.reshape(X.shape) fig, ax, cbar = create_surface_plot(X, Y, Z, 'temperature', 'pressure')

create_uncertainty_surface_plot ¶

create_uncertainty_surface_plot(x_grid: ndarray, y_grid: ndarray, uncertainty_grid: ndarray, x_var: str, y_var: str, exp_x: Optional[ndarray] = None, exp_y: Optional[ndarray] = None, suggest_x: Optional[ndarray] = None, suggest_y: Optional[ndarray] = None, cmap: str = 'Reds', alpha: float = 0.9, figsize: Tuple[float, float] = (10, 8), dpi: int = 100, title: str = '3D Uncertainty Surface (Standard Deviation)', ax: Optional[Any] = None, subplot_label: Optional[str] = None, formatters: Optional[Dict[str, Any]] = None) -> Tuple[Figure, Any, Any]

Create 3D surface plot of posterior uncertainty.

Like the 2D uncertainty contour plot, but renders the prediction standard deviation on the Z axis as a 3D surface.

Parameters:

Name	Type	Description	Default
`x_grid`	`ndarray`	X-axis meshgrid values (2D array)	required
`y_grid`	`ndarray`	Y-axis meshgrid values (2D array)	required
`uncertainty_grid`	`ndarray`	Posterior standard deviations on grid (2D array)	required
`x_var`	`str`	X variable name for axis label	required
`y_var`	`str`	Y variable name for axis label	required
`exp_x`	`Optional[ndarray]`	Experimental X values to overlay (optional)	`None`
`exp_y`	`Optional[ndarray]`	Experimental Y values to overlay (optional)	`None`
`suggest_x`	`Optional[ndarray]`	Suggested X values to overlay (optional)	`None`
`suggest_y`	`Optional[ndarray]`	Suggested Y values to overlay (optional)	`None`
`cmap`	`str`	Matplotlib colormap name (default: 'Reds')	`'Reds'`
`alpha`	`float`	Surface transparency (0=transparent, 1=opaque)	`0.9`
`figsize`	`Tuple[float, float]`	Figure size (width, height) in inches	`(10, 8)`
`dpi`	`int`	Resolution	`100`
`title`	`str`	Plot title	`'3D Uncertainty Surface (Standard Deviation)'`
`ax`	`Optional[Any]`	Existing 3D axes (creates new if None)	`None`
`subplot_label`	`Optional[str]`	Panel label text (e.g. "(a)"). Placed in the upper-left corner of the axes when provided.	`None`
`formatters`	`Optional[Dict[str, Any]]`	Optional dict controlling number formatting on individual axes. Accepted keys: `'x'`, `'y'`, `'cbar'` (colorbar only), `'z'` (3-D plots only). Each value may be a brace-style format string (e.g. `'{:.1%}'`), a printf-style string (e.g. `'%.2f'`), a callable `func(value, pos)`, or a `matplotlib.ticker.Formatter` instance. Defaults to `None` (no custom formatting).	`None`

Returns:

Type	Description
`Tuple[Figure, Any, Any]`	Tuple of (Figure, Axes3D, Colorbar)

Example

X, Y = np.meshgrid(x_range, y_range) _, std = model.predict(grid, return_std=True) unc = std.reshape(X.shape) fig, ax, cbar = create_uncertainty_surface_plot(X, Y, unc, 'temp', 'pressure')