recovery

bayesflow.diagnostics.recovery(estimates: Mapping[str, ~numpy.ndarray] | ~numpy.ndarray, targets: Mapping[str, ~numpy.ndarray] | ~numpy.ndarray, variable_keys: Sequence[str] = None, variable_names: Sequence[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, figsize: Sequence[int] = None, label_fontsize: int = 16, title_fontsize: int = 18, metric_fontsize: int = 16, tick_fontsize: int = 12, color: str = '#132a70', num_col: int = None, num_row: int = None, xlabel: str = 'Ground truth', ylabel: str = 'Estimate', markersize: float = None, **kwargs) → Figure

Creates and plots publication-ready recovery plot with true estimate vs. point estimate + uncertainty. The point estimate can be controlled with the point_agg argument, and the uncertainty estimate can be controlled with the uncertainty_agg argument.

This plot yields similar information as the “posterior z-score”, but allows for generic point and uncertainty estimates:

https://betanalpha.github.io/assets/case_studies/principled_bayesian_workflow.html

Important: Posterior aggregates play no special role in Bayesian inference and should only be used heuristically. For instance, in the case of multi-modal posteriors, common point estimates, such as mean, (geometric) median, or maximum a posteriori (MAP) mean nothing.

Parameters:

estimatesnp.ndarray of shape (num_datasets, num_post_draws, num_params)

The posterior draws obtained from num_datasets

targetsnp.ndarray of shape (num_datasets, num_params)

The prior draws (true parameters) used for generating the num_datasets

variable_keyslist or None, optional, default: None

Select keys from the dictionaries provided in estimates and targets. By default, select all keys.

variable_nameslist or None, optional, default: None

The individual parameter names for nice plot titles. Inferred if None

test_quantitiesdict or None, optional, default: None

A dict that maps plot titles to functions that compute test quantities based on estimate/target draws.

The dict keys are automatically added to variable_keys and variable_names. Test quantity functions are expected to accept a dict of draws with shape (batch_size, ...) as the first (typically only) positional argument and return an NumPy array of shape (batch_size,). The functions do not have to deal with an additional sample dimension, as appropriate reshaping is done internally.

point_aggcallable, optional, default: median

Function to compute point estimates.

uncertainty_aggcallable, optional, default: credible_interval with coverage probability 95%

Function to compute a measure of uncertainty. Can either be the lower and upper uncertainty bounds provided with the shape (2, num_datasets, num_params) or a scalar measure of uncertainty (e.g., the median absolute deviation) with shape (num_datasets, num_params).

point_agg_kwargsOptional dictionary of further arguments passed to point_agg.

uncertainty_agg_kwargsOptional dictionary of further arguments passed to uncertainty_agg.

For example, to change the coverage probability of credible_interval to 50%, use uncertainty_agg_kwargs = dict(prob=0.5)

add_corrboolean, default: True

Should correlations between estimates and ground truth values be shown?

figsizetuple or None, optional, defaultNone

The figure size passed to the matplotlib constructor. Inferred if None.

label_fontsizeint, optional, default: 16

The font size of the y-label text.

title_fontsizeint, optional, default: 18

The font size of the title text.

metric_fontsizeint, optional, default: 16

The font size of the metrics shown as text.

tick_fontsizeint, optional, default: 12

The font size of the axis ticklabels.

colorstr, optional, default: ‘#8f2727’

The color for the true vs. estimated scatter points and error bars.

num_rowint, optional, default: None

The number of rows for the subplots. Dynamically determined if None.

num_colint, optional, default: None

The number of columns for the subplots. Dynamically determined if None.

xlabelstr, optional, default: “Ground truth”

The label shown on the x-axis.

ylabelstr, optional, default: “Estimate”

The label shown on the y-axis.

markersizefloat, optional, default: None

The marker size in points.

Returns:

fplt.Figure - the figure instance for optional saving

Raises:

ShapeError

If there is a deviation from the expected shapes of estimates and targets.