arviz_plots.plot_ess

Contents

arviz_plots.plot_ess#

arviz_plots.plot_ess(dt, var_names=None, filter_vars=None, group='posterior', coords=None, sample_dims=None, kind='local', relative=False, rug=False, rug_kind='diverging', n_points=20, extra_methods=False, min_ess=400, plot_collection=None, backend=None, labeller=None, aes_by_visuals=None, visuals=None, stats=None, **pc_kwargs)[source]#

Plot effective sample size plots.

Roughly speaking, the effective sample size of a quantity of interest captures how many independent draws contain the same amount of information as the dependent sample obtained by the MCMC algorithm. The higher the ESS the better. See [1] for more details.

Parameters:
dtxarray.DataTree or dict of {strxarray.DataTree}

Input data. In case of dictionary input, the keys are taken to be model names. In such cases, a dimension “model” is generated and can be used to map to aesthetics.

var_namesstr or sequence of str, optional

One or more variables to be plotted. Prefix the variables by ~ when you want to exclude them from the plot.

filter_vars{None, “like”, “regex”}, default None

If None, interpret var_names as the real variables names. If “like”, interpret var_names as substrings of the real variables names. If “regex”, interpret var_names as regular expressions on the real variables names.

groupstr, default “posterior”

Group to be plotted.

coordsdict, optional
sample_dimsstr or sequence of hashable, optional

Dimensions to reduce unless mapped to an aesthetic. Defaults to rcParams["data.sample_dims"]

kind{“local”, “quantile”}, default “local”

Specify the kind of plot:

  • The kind="local" argument generates the ESS’ local efficiency for estimating small-interval probability of a desired posterior.

  • The kind="quantile" argument generates the ESS’ local efficiency for estimating quantiles of a desired posterior.

relativebool, default False

Show relative ess in plot ress = ess / N.

rugbool, default False

Add a rug plot for a specific subset of values.

rug_kindstr, default “diverging”

Variable in sample stats to use as rug mask. Must be a boolean variable.

n_pointsint, default 20

Number of points for which to plot their quantile/local ess or number of subsets in the evolution plot.

extra_methodsbool, default False

Plot mean and sd ESS as horizontal lines.

min_essint, default 400

Minimum number of ESS desired. If relative=True the line is plotted at min_ess / n_samples for local and quantile kinds

plot_collectionPlotCollection, optional
backend{“matplotlib”, “bokeh”}, optional
labellerlabeller, optional
aes_by_visualsmapping of {strsequence of str or False}, optional

Mapping of visuals to aesthetics that should use their mapping in plot_collection when plotted. Valid keys are the same as for visuals.

By default, no aesthetic mappings are defined. Only when multiple models are present a color and x shift is generated to distinguish the data coming from the different models.

When mean or sd keys are present in aes_by_visuals but mean_text or sd_text are not, the respective _text key will be added with the same values as mean or sd ones.

visualsmapping of {strmapping or bool}, optional

Valid keys are:

statsmapping, optional

Valid keys are:

  • ess -> passed to ess, method = ‘local’ or ‘quantile’ based on kind

  • mean -> passed to ess, method=’mean’

  • sd -> passed to ess, method=’sd’

**pc_kwargs

Passed to arviz_plots.PlotCollection.wrap

Returns:
PlotCollection

See also

Introduction to batteries-included plots

General introduction to batteries-included plotting functions, common use and logic overview

References

[1]

Vehtari et al. Rank-normalization, folding, and localization: An improved Rhat for assessing convergence of MCMC. Bayesian Analysis. 16(2) (2021) https://doi.org/10.1214/20-BA1221. arXiv preprint https://arxiv.org/abs/1903.08008

Examples

We can manually map the color to the variable, and have the mapping apply to the title too instead of only the ess markers:

>>> from arviz_plots import plot_ess, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> non_centered = load_arviz_data('non_centered_eight')
>>> pc = plot_ess(
>>>     non_centered,
>>>     coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>>     aes={"color": ["__variable__"]},
>>>     aes_by_visuals={"title": ["color"]},
>>> )
../../_images/arviz_plots-plot_ess-1.png

We can add extra methods to plot the mean and standard deviation as lines, and adjust the minimum ess baseline as well:

>>> pc = plot_ess(
>>>     non_centered,
>>>     coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>>     extra_methods=True,
>>>     min_ess=200,
>>> )
../../_images/arviz_plots-plot_ess-2.png

Rugs can also be added:

>>> pc = plot_ess(
>>>     non_centered,
>>>     coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>>     rug=True,
>>> )
../../_images/arviz_plots-plot_ess-3.png

Relative ESS can be plotted instead of absolute:

>>> pc = plot_ess(
>>>     non_centered,
>>>     coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>>     relative=True,
>>> )
../../_images/arviz_plots-plot_ess-4.png

We can also adjust the number of points:

>>> pc = plot_ess(
>>>     non_centered,
>>>     coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>>     n_points=10,
>>> )
../../_images/arviz_plots-plot_ess-5.png

faceted local ESS plot

ESS local

ESS local

faceted quantile ESS plot

ESS quantile

ESS quantile

Full ESS (Either local or quantile) comparison between different models

ESS comparison

ESS comparison
Contents