arviz.plot_energy#

arviz.plot_energy(data, kind=None, bfmi=True, figsize=None, legend=True, fill_alpha=(1, 0.75), fill_color=('C0', 'C5'), bw='experimental', textsize=None, fill_kwargs=None, plot_kwargs=None, ax=None, backend=None, backend_kwargs=None, show=None)[source]#

Plot energy transition distribution and marginal energy distribution in HMC algorithms.

This may help to diagnose poor exploration by gradient-based algorithms like HMC or NUTS. The energy function in HMC can identify posteriors with heavy tailed distributions, that in practice are challenging for sampling.

This plot is in the style of the one used in [1].

Parameters:
dataobj

xarray.Dataset, or any object that can be converted (must represent sample_stats and have an energy variable).

kindstr, optional

Type of plot to display (“kde”, “hist”).

bfmibool, default True

If True add to the plot the value of the estimated Bayesian fraction of missing information.

figsize(float, float), optional

Figure size. If None it will be defined automatically.

legendbool, default True

Flag for plotting legend.

fill_alphatuple, default (1, 0.75)

Alpha blending value for the shaded area under the curve, between 0 (no shade) and 1 (opaque).

fill_colortuple of valid matplotlib color, default (‘C0’, ‘C5’)

Color for Marginal energy distribution and Energy transition distribution.

bwfloat or str, optional

If numeric, indicates the bandwidth and must be positive. If str, indicates the method to estimate the bandwidth and must be one of “scott”, “silverman”, “isj” or “experimental”. Defaults to “experimental”. Only works if kind='kde'.

textsizefloat, optional

Text size scaling factor for labels, titles and lines. If None it will be autoscaled based on figsize.

fill_kwargsdicts, optional

Additional keywords passed to arviz.plot_kde() (to control the shade).

plot_kwargsdicts, optional

Additional keywords passed to arviz.plot_kde() or matplotlib.pyplot.hist() (if type='hist').

axaxes, optional

matplotlib.axes.Axes or bokeh.plotting.Figure.

backend{“matplotlib”, “bokeh”}, default “matplotlib”

Select plotting backend.

backend_kwargsdict, optional

These are kwargs specific to the backend being used, passed to matplotlib.pyplot.subplots() or bokeh.plotting.figure. For additional documentation check the plotting method of the backend.

showbool, optional

Call backend show function.

Returns:
axesmatplotlib axes or bokeh figures

See also

bfmi

Calculate the estimated Bayesian fraction of missing information (BFMI).

References

[1]

Betancourt (2016). Diagnosing Suboptimal Cotangent Disintegrations in

Hamiltonian Monte Carlo https://arxiv.org/abs/1604.00695

Examples

Plot a default energy plot

>>> import arviz as az
>>> data = az.load_arviz_data('centered_eight')
>>> az.plot_energy(data)
../../_images/arviz-plot_energy-1.png

Represent energy plot via histograms

>>> az.plot_energy(data, kind='hist')
../../_images/arviz-plot_energy-2.png