Plots’ arguments guide

Arviz plot module is used for plotting data. It consists many functions that each serve different purposes. Most of these plotting functions have common arguments. These common arguments are explained in the following examples, which use one specific function to illustrate the usage but the behaviour described here will be the same for the other functions with the same argument.

This page can be downloaded as a Jupyter notebook.

import arviz as az
import numpy as np

centered_eight = az.load_arviz_data('centered_eight')
non_centered_eight = az.load_arviz_data('non_centered_eight')

x_data = np.random.normal(0, 1, 100)
y_data = np.random.normal(2 + x_data * 0.5, 0.5, (2, 50, 100))

az.style.use("arviz-doc")

Warning

Page in construction

var_names

Variables to be plotted. If None all variables are plotted. Prefix the variables by ~ when you want to exclude them from the plot. Let’s see the examples.

Plot all variables, which is the default behavior:

az.plot_posterior(centered_eight);

Plot one variable by setting var_names="var1":

az.plot_posterior(centered_eight, var_names='mu');

Plot subset variables by specifying variable name exactly:

az.plot_posterior(centered_eight, var_names=['mu', 'tau']);

Use var_names to indicate which variables to exclude with the ~ prefix:

az.plot_posterior(centered_eight, var_names=['~mu', '~theta']);

Variables do not need to be strings to be used. Anything that is hashable will work.

mu = ("mu", "var")
samples = np.random.normal(0, 1, 100)
data = az.dict_to_dataset({mu: samples})
az.plot_posterior(data);

filter_vars

If None (default), interpret var_names as the real variables names, as shown in the previous section. This argument is inspired in pandas.DataFrame.filter().

If “like”, interpret var_names as substrings of the real variables names. Each substring is checked against all present variable names and the list of matching variables to be plotted is generated.

az.plot_posterior(centered_eight, var_names='ta', filter_vars="like");

Both tau and theta have ta inside them, so only mu is excluded in this case. You can also use lists and you can also use the ~ prefix to indicate that all variables containing that substring should be excluded.

az.plot_posterior(centered_eight, var_names='~ta', filter_vars="like");

If “regex”, interpret var_names as regular expressions on the real variables names. The regular expression u$ matches the letter “u” at the end of the line (end of the variable name in this case). So it will match mu and tau variables:

az.plot_posterior(centered_eight, var_names="u$", filter_vars="regex");

Again, like with filter_vars="like", a list of regular expressions can also be provided as well as negative conditions with ~.

Note

When providing a list of regular expressions and substring matches, they are expanded independently.

coords

Dictionary mapping dimensions to selected coordinates to be plotted. Dimensions without a mapping specified will include the data corresponding to all coordinate values for that dimension. It defaults to including all coordinates for all dimensions.

Using coords argument to plot only a subset of data:

coords = {"school": ["Choate", "Phillips Exeter"]};
az.plot_posterior(centered_eight, var_names=["mu", "theta"], coords=coords);

combined

Flag for combining multiple chains into a single chain. When True, chains are combined into a single plot/line, when False each chain is plotted independently (either beside each other or each in their own subplot). While the behaviour of the parameter is the same in all plots, its default depends on the plotting function.

Plot each chain separately:

az.plot_forest(centered_eight, var_names=["mu", "tau"]);

Plot all chains collapsed into a single line:

az.plot_forest(centered_eight, var_names=["mu", "tau"], combined=True);

combine_dims

Set like argument containing dimensions to reduce for plots that represent probability distributions. When used, the dimensions on combine_dims are added to chain and draw dimensions and reduced to generate a single KDE/histogram/dot plot from >2D arrays.

combine_dims dims can be used to generate the KDE of the distribution of theta when combining all schools together.

az.plot_posterior(centered_eight, var_names=["mu", "theta"], combine_dims={"school"});

Warning

plot_pair also supports combine_dims argument, but it’s the users responsibility to ensure the variables to be plotted have compatible dimensions when reducing them pairwise.

Both theta and theta_t have the school dimension, so we can use combine_dims in plot_pair to generate their global 2d KDE.

az.plot_pair(
    non_centered_eight, var_names=["theta", "theta_t"], combine_dims={"school"}, kind="kde"
);

mu however does not, so trying to plot their combined distribution errors out:

az.plot_pair(non_centered_eight, var_names=["theta", "mu"], combine_dims={"school"});

Show code cell output Hide code cell output

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[17], line 1
----> 1 az.plot_pair(non_centered_eight, var_names=["theta", "mu"], combine_dims={"school"});

File ~/checkouts/readthedocs.org/user_builds/arviz/envs/latest/lib/python3.10/site-packages/arviz/plots/pairplot.py:272, in plot_pair(data, group, var_names, filter_vars, combine_dims, coords, marginals, figsize, textsize, kind, gridsize, divergences, colorbar, labeller, ax, divergences_kwargs, scatter_kwargs, kde_kwargs, hexbin_kwargs, backend, backend_kwargs, marginal_kwargs, point_estimate, point_estimate_kwargs, point_estimate_marker_kwargs, reference_values, reference_values_kwargs, show)
    270 # TODO: Add backend kwargs
    271 plot = get_plotting_function("plot_pair", "pairplot", backend)
--> 272 ax = plot(**pairplot_kwargs)
    273 return ax

File ~/checkouts/readthedocs.org/user_builds/arviz/envs/latest/lib/python3.10/site-packages/arviz/plots/backends/matplotlib/pairplot.py:176, in plot_pair(ax, plotters, numvars, figsize, textsize, kind, scatter_kwargs, kde_kwargs, hexbin_kwargs, gridsize, colorbar, divergences, diverging_mask, divergences_kwargs, flat_var_names, backend_kwargs, marginal_kwargs, show, marginals, point_estimate, point_estimate_kwargs, point_estimate_marker_kwargs, reference_values, reference_values_kwargs)
    173         ax = np.atleast_2d(ax)[0, 0]
    175 if "scatter" in kind:
--> 176     ax.scatter(x, y, **scatter_kwargs)
    177 if "kde" in kind:
    178     plot_kde(x, y, ax=ax, **kde_kwargs)

File ~/checkouts/readthedocs.org/user_builds/arviz/envs/latest/lib/python3.10/site-packages/matplotlib/__init__.py:1446, in _preprocess_data.<locals>.inner(ax, data, *args, **kwargs)
   1443 @functools.wraps(func)
   1444 def inner(ax, *args, data=None, **kwargs):
   1445     if data is None:
-> 1446         return func(ax, *map(sanitize_sequence, args), **kwargs)
   1448     bound = new_sig.bind(ax, *args, **kwargs)
   1449     auto_label = (bound.arguments.get(label_namer)
   1450                   or bound.kwargs.get(label_namer))

File ~/checkouts/readthedocs.org/user_builds/arviz/envs/latest/lib/python3.10/site-packages/matplotlib/axes/_axes.py:4578, in Axes.scatter(self, x, y, s, c, marker, cmap, norm, vmin, vmax, alpha, linewidths, edgecolors, plotnonfinite, **kwargs)
   4576 y = np.ma.ravel(y)
   4577 if x.size != y.size:
-> 4578     raise ValueError("x and y must be the same size")
   4580 if s is None:
   4581     s = (20 if mpl.rcParams['_internal.classic_mode'] else
   4582          mpl.rcParams['lines.markersize'] ** 2.0)

ValueError: x and y must be the same size

combine_dims can be used alongside combined, but it can’t be used to replace it. When combined=True, ArviZ does extra processing in addition to adding "chain" to combine_dims under the hood. Therefore:

az.plot_forest(
    centered_eight, var_names="theta", combined=True, combine_dims={"school"}
);

is not equivalent to:

az.plot_forest(
    centered_eight, var_names="theta", combine_dims={"chain", "school"}
);

hdi_prob

Probability for the highest density interval (HDI). Defaults to stats.hdi_prob rcParam.

Plot the 80% HDI interval of simulated regression data using y argument:

az.plot_posterior(centered_eight, var_names="mu", hdi_prob=0.8);

grid

Number of rows and columns. Defaults to None, the rows and columns are automatically inferred.

Plot variables in a 4x5 grid:

az.plot_density([centered_eight, non_centered_eight], grid=(4, 5));

figsize

figsize is short for figure size, expressed as a tuple. By default it is defined automatically.

az.plot_posterior(centered_eight, var_names=["mu", "tau"], figsize=(3, 6));

textsize

Text size for labels, titles and lines. By default it is autoscaled based on figsize.

az.plot_posterior(centered_eight, var_names="theta", coords=coords, textsize=30);

color or colors

Color used for the main element or elements of the plot. It should be a valid matplotlib color, even if using the bokeh backend.

While both libraries use CSS colors as their base named colors, matplotlib also supports theme based colors like C0 as well as tableau and xkcd colors. ArviZ converts the provided colors to hex RGB format using matplotlib before passing it to either plotting backend.

Plot the HDI interval of simulated regression data using y argument, in red:

az.plot_hdi(x_data, y_data, color="red");

colors behaves like color but it takes an iterable of colors instead of a single color. The number of colors to be provided is defined by the models being compared (like in plot_density) of by the number of different quantities being plotted (like in plot_ppc).

Warning

In plot_elpd() and plot_khat(), where scatter plots are generated with one dot per observation, color can also take an array_like of colors, one per dot.

There are examples in their respective docstrings.

az.plot_density([centered_eight, non_centered_eight], colors=["salmon", "indigo"]);

See also

Matplotlib Specifying colors tutorial.

Module bokeh.colors

rope

The rope argument is used to indicate the lower and upper limits of the Region Of Practical Equivalence (ROPE). These limits can be expressed in two ways, depending on whether the ROPE is common between all variables or not:

1. A single list. If a single list of two floats is given as rope argument, these two provided values will be used as limits of the ROPE in all plotted variables.

2. A dictionary of lists.

Example of using a single list as rope

az.plot_forest(non_centered_eight, var_names="~theta_t", rope=[-1, 2]);

An example of using a dictionary as rope to highlight the ROPE for a single variable:

rope = {'mu': [{"rope": (4, 5)}]}

az.plot_forest(non_centered_eight, rope=rope, var_names='~theta_t', combined=True);

An example of using a dictionary as rope to highlight different ROPEs for different variables:

rope = {
    "mu": [{"rope": (4, 5)}],
    "theta": [
        {"school": "Choate",    "rope": (0, 3)},
        {"school": "Phillips Andover", "rope": (10, 14)},
        {"school": "Hotchkiss", "rope": (3, 9)},
        {"school": "St. Paul's", "rope": (3, 8)},
    ]
}

az.plot_forest(non_centered_eight, rope=rope, var_names="~theta_t", combined=True);

Moreover, for multidimensional variables, it is easy to share a common ROPE for all its components with a different one for other variables:

rope = {
    "mu": [{"rope": (4, 5)}],
    "theta": [{"rope": (0, 3)}],
    "tau": [{"rope": (0, 1)}],
}

az.plot_forest(non_centered_eight, rope=rope, var_names="~theta_t", combined=True);

legend

Show a legend with the color encoded model information. Defaults to True, if there are multiple models.

List with names for the models in the list of data. Useful when plotting more than one dataset.

ax

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

backend

Select plotting backend {“matplotlib”,”bokeh”}. Defaults to “matplotlib”.

backend_kwargs

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.

show

Call backend show function.