autoemulate.core.plotting

display_figure(fig)

Display a matplotlib figure.

Display a matplotlib figure appropriately based on the environment (Jupyter notebook or terminal).

Parameters:

fig (Figure) – The object to display.

Returns:

The input figure object.

Return type:

Figure

plot_xy(x, y, y_pred, y_variance=None, ax=None, title='xy', input_index=None, output_index=None, r2_score=None)

Plot observed and predicted values vs. features.

Parameters:

• x (NumpyLike) – An array of inputs.

• y (NumpyLike) – An array of outputs.

• y_pred (NumpyLike) – An array of predictions.

• y_variance (NumpyLike | None) – An optional array of predictive variances.

• ax (Axes | None) – An optional matplotlib Axes object to plot on.

• title (str) – An optional title for the plot.

• input_index (int | None) – An optional index of the input dimension to plot.

• output_index (int | None) – An optional index of the output dimension to plot.

• r2_score (float | None) – An option r2 score to include in the plot legend.

calculate_subplot_layout(n_plots, n_cols=3)

Calculate optimal number of rows and columns for subplots.

Parameters:

• n_plots (int) – Number of plots to display.

• n_cols (int) – Maximum number of columns allowed. Defaults to 3.

Returns:

(n_rows, n_cols) for the subplot layout.

Return type:

tuple

mean_and_var_surface(model, parameters_range, variables, output_idx=0, quantile=0.5, n_points=30)

Create predicted mean and variance on a specified grid for variable subset.

Create a grid of points varying specified parameters over a specified range, while fixing other parameters at a given quantile along their simulation range.

Parameters:

• model (Emulator) – A trained emulator.

• parameters_range (dict[str, tuple[float, float]]) – A dictionary specifying the ranges for all input parameters. Keys are parameter names and values are tuples of (min, max). The dictionary should be ordered equivalently to the order of parameters used to train the model.

• variables (list[str]) – A list of parameter names to vary.

• output_idx (int,) – The index of the output to return.

• quantile (float) – The quantile at which to fix other parameters. Defaults to 0.5 (median).

• n_points (int) – Number of grid points per variable. Defaults to 30. Higher values increase resolution but also computation time.

Returns:

• mean (TensorLike) – The predicted mean on the grid.

• var (TensorLike) – The predicted variance on the grid.

• grid (list[TensorLike]) – The grid of parameter values used for predictions.

create_and_plot_slice(model, parameters_range, param_pair, output_idx=0, vmin=None, vmax=None, quantile=0.5, n_points=50)

Create a 2D slice for any pair of parameters.

Parameters:

• model (Emulator) – A trained emulator.

• parameters_range (dict[str, tuple[float, float]]) – A dictionary specifying the ranges for all input parameters. Keys are parameter names and values are tuples of (min, max). The dictionary should be ordered equivalently to the order of parameters used to train the model.

• param_pair (tuple[int, int]) – A list of two parameter indices.

• output_idx (int) – The output index to plot the surface of.

• vmin (float | None) – Minimum value for the mean plot color scale.

• vmax (float | None) – Maximum value for the mean plot color scale.

• quantile (float) – The quantile at which to fix other parameters. Defaults to 0.5 (median).

• n_points (int) – Number of grid points per parameter. Defaults to 50.

Returns:

• mean (TensorLike) – The predicted mean on the grid.

• var (TensorLike) – The predicted variance on the grid.

• grid (list[TensorLike]) – The grid points for the two varying parameters.

coverage_from_distributions(y_pred, y_true, levels=None, n_samples=2000, joint=False)

Compute empirical coverage for a set of nominal confidence levels.

Parameters:

• y_pred (DistributionLike) – The emulator predicted distribution.

• y_true (TensorLike) – The true values.

• levels (array-like, optional) – Nominal coverage levels (between 0 and 1). If None, a default grid is used. Defaults to None.

• n_samples (int) – Number of Monte-Carlo samples to draw from the predictive distribution to compute empirical intervals if analytical quantiles are not available.

• joint (bool) – If True and the predictive outputs are multivariate, compute joint coverage (i.e., the true vector must lie inside the interval for all dimensions). If False (default), compute marginal coverage per output dimension and return the mean across data points.

Returns:

• levels (np.ndarray) – Nominal coverage levels.

• empirical (np.ndarray) – Empirical coverages. Shape is (len(levels), output_dim) when joint=False and output_dim>1, or (len(levels),) when joint=True or output_dim==1.

plot_calibration_from_distributions(y_pred, y_true, levels=None, n_samples=2000, joint=False, title=None, legend=True, figsize=None)

Plot calibration curve(s) given predictive distributions and true values.

This draws empirical coverage (y-axis) against nominal coverage (x-axis).

When points lie above or below the diagonal, this indicates that uncertainty is respectively being overestimated or underestimated.

Parameters:

• y_pred (DistributionLike) – The emulator predicted distribution.

• y_true (TensorLike) – The true values.

• levels (array-like, optional) – Nominal coverage levels (between 0 and 1). If None, a default grid is used.

• n_samples (int) – Number of Monte-Carlo samples to draw from the predictive distribution to compute empirical intervals.

• joint (bool) – If True and the predictive outputs are multivariate, compute joint coverage (i.e., the true vector must lie inside the interval for all dimensions). If False (default), compute marginal coverage per output dimension and return the mean across data points.

• title (str | None) – An optional title for the plot. Defaults to None (no title).

• legend (bool) – Whether to display a legend. Defaults to True.

• figsize (tuple[int, int] | None) – The size of the figure to create. If None, a default size is used.