pairs_recovery

bayesflow.diagnostics.plots.pairs_recovery(estimates: Mapping[str, ~numpy.ndarray] | ~numpy.ndarray, targets: Mapping[str, ~numpy.ndarray] | ~numpy.ndarray, variable_keys: Sequence[str] | str = None, variable_names: Sequence[str] | str = None, test_quantities: dict[str, ~collections.abc.Callable]=None, point_agg: Callable = <function median>, uncertainty_agg: Callable = <function credible_interval>, point_agg_kwargs: dict = None, uncertainty_agg_kwargs: dict = None, add_corr: bool = True, height: float = 2.5, color: str = '#132a70', alpha: float = 0.5, label_fontsize: int = 14, tick_fontsize: int = 12, metric_fontsize: int = 14, markersize: float = None) → Figure

Plot recovery and pairwise dependencies across simulated datasets.

Diagonal cells show ground truth (x) versus point estimate (y), with optional uncertainty intervals and an identity line. Upper cells show pairs of point estimates with uncertainty in both directions; lower cells show pairs of ground truths. In cell (i, j), the x variable is j and the y variable is i. Each point represents one dataset, including in the off-diagonal cells.

Parameters:

estimatesnp.ndarray or dict[str, np.ndarray]

Posterior draws of shape (num_datasets, num_draws, num_variables), or a dictionary of arrays with these leading dataset/draw axes.

targetsnp.ndarray or dict[str, np.ndarray]

Corresponding truths of shape (num_datasets, num_variables), or a dictionary matching the selected estimate keys.

variable_keyssequence of str or str, optional

Dictionary keys to select, in plotting order. Defaults to all keys in estimates.

variable_namessequence of str or str, optional

Display names for the selected scalar variables. Inferred if omitted.

test_quantitiesdict[str, Callable], optional

Named quantities to prepend. Requires dictionary inputs. Each callable accepts data= containing a dictionary of draws with a leading batch axis and returns one scalar per batch element. Posterior dataset and draw axes are flattened and restored by compute_test_quantities.

point_aggCallable, default np.median

Called with axis=1 to produce (num_datasets, num_variables) points.

uncertainty_aggCallable or None, default credible_interval

Called with axis=1. Returns nonnegative symmetric errors of shape (num_datasets, num_variables), or lower/upper bounds of shape (2, num_datasets, num_variables) enclosing the point estimates. Use None to omit error bars.

point_agg_kwargsdict, optional

Additional arguments for point_agg.

uncertainty_agg_kwargsdict, optional

Additional arguments for uncertainty_agg, e.g., dict(prob=0.5) for a 50% credible interval instead of the default 95% interval.

add_corrbool, default True

Annotate only diagonal cells with truth/estimate Pearson correlation.

heightfloat, default 2.5

Figure width and height per variable, in inches.

colorstr, default “#132a70”

Color of points and error bars.

alphafloat, default 0.5

Opacity of points and error bars.

label_fontsizeint, default 14

Font size of variable and source labels on every cell.

tick_fontsizeint, default 12

Font size of tick labels.

metric_fontsizeint, default 14

Font size of correlation annotations.

markersizefloat, optional

Marker size in points, as in recovery; squared for scatter areas.

Returns:

matplotlib.figure.Figure

Figure with num_variables squared axes in row-major order. Axes are independent because the source changes across each row and column. Diagonal cells have equal x/y limits including uncertainty bounds.

Raises:

ShapeError

If selected inputs are empty, have incompatible shapes, or aggregators return shapes other than those documented above.

TypeError

If test quantities are requested with array inputs.

ValueError

If variable names do not match the selected variables, errors are negative, or uncertainty bounds do not enclose the point estimates.

Notes

Pairwise estimates describe variation of posterior point summaries across datasets, not posterior dependence within a dataset. Posterior summaries are heuristic and can be misleading for multimodal distributions.