Plotting functions
Distribution
ArviZPythonPlots.plot_dist — Function
Plot 1D marginal densities in the style of John K. Kruschke’s book [1]_.
Generate :term:`faceted` :term:`plots` with: a graphical representation of 1D marginal
densities (as KDE, histogram, ECDF or dotplot), a credible interval and a point estimate.
Parameters
----------
dt : DataTree or dict of {str : 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_names : str or list 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.
group : str, default "posterior"
Group to be plotted.
coords : dict, optional
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
kind : {"auto", "kde", "hist", "dot", "ecdf"}, optional
How to represent the marginal density.
Defaults to ``rcParams["plot.density_kind"]``
point_estimate : {"mean", "median", "mode"}, optional
Which point estimate to plot. Defaults to rcParam :data:`stats.point_estimate`
ci_kind : {"eti", "hdi"}, optional
Which credible interval to use. Defaults to ``rcParams["stats.ci_kind"]``
ci_prob : float, optional
Indicates the probability that should be contained within the plotted credible interval.
Defaults to ``rcParams["stats.ci_prob"]``
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals`.
With a single model, no aesthetic mappings are generated by default,
each variable+coord combination gets a :term:`plot` but they all look the same,
unless there are user provided aesthetic mappings.
With multiple models, ``plot_dist`` maps "color" and "y" to the "model" dimension.
By default, all aesthetics but "y" are mapped to the density representation,
and if multiple models are present, "color" and "y" are mapped to the
credible interval and the point estimate.
When "point_estimate" key is provided but "point_estimate_text" isn't,
the values assigned to the first are also used for the second.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* dist -> depending on the value of `kind` passed to:
* "kde" -> passed to :func:`~arviz_plots.visuals.line_xy`
* "ecdf" -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* "hist" -> passed to :func: `~arviz_plots.visuals.step_hist`
* "dot" -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* face -> :term:`visual` that fills the area under the marginal distribution representation.
Defaults to False. Depending on the value of `kind` it is passed to:
* "kde", "ecdf" or "dot" -> passed to :func:`~arviz_plots.visuals.fill_between_y`
* "hist" -> passed to :func:`~arviz_plots.visuals.hist`
* credible_interval -> passed to :func:`~arviz_plots.visuals.line_x`
* point_estimate -> passed to :func:`~arviz_plots.visuals.scatter_x`
* point_estimate_text -> passed to :func:`~arviz_plots.visuals.point_estimate_text`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* rug -> passed to :func:`~arviz_plots.visuals.scatter_x`. Defaults to False.
* remove_axis -> not passed anywhere, can only be ``False`` to skip calling this function
stats : mapping of {str : mapping or Dataset}, optional
Valid keys are:
* dist -> passed to :func:`~arviz_stats.kde`, :func:`~arviz_stats.histogram`,
:func:`~arviz_stats.ecdf`, or :func:`~arviz_stats.qds` depending on `kind`
* credible_interval -> passed to :func:`~arviz_stats.eti` or :func:`arviz_stats.hdi`
* point_estimate -> passed to mean, median or mode. Defaults to
round the result according to ``rcParams["stats.round_to"]``.
In case a :class:`~xarray.Dataset` is provided, it will be interpreted
as pre-computed values for that statistic.
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
See Also
--------
:ref:`plots_intro` :
General introduction to batteries-included plotting functions, common use and logic overview
Examples
--------
Map the color to the variable, and have the mapping apply
to the title too instead of only the density representation:
.. plot::
:context: close-figs
>>> from arviz_plots import plot_dist, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> non_centered = load_arviz_data('non_centered_eight')
>>> pc = plot_dist(
>>> non_centered,
>>> coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>> aes={"color": ["__variable__"]},
>>> aes_by_visuals={"title": ["color"]},
>>> )
Faceting and aesthetics mappings happen on unique coordinate values. If there are repeated
coordinate values they will be grouped and reduced along with `sample_dims`.
.. plot::
:context: close-figs
>>> post = non_centered.posterior.to_dataset()
>>> repeated_coords = ["a", "a", "a", "b", "b", "b", "b", "c"]
>>> pc = plot_dist(post.assign_coords(school=repeated_coords))
.. minigallery:: plot_dist
References
----------
.. [1] Kruschke. Doing Bayesian Data Analysis, Second Edition: A Tutorial with R,
JAGS, and Stan. Academic Press, 2014. ISBN 978-0-12-405888-0.
https://www.sciencedirect.com/book/9780124058880
ArviZPythonPlots.plot_forest — Function
Plot 1D marginal credible intervals in a single plot.
Parameters
----------
dt : DataTree or dict of {str : 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.
``plot_forest`` uses the dimension "column" (creating it if necessary) to generate the grid
then adds the intervals+point estimates to its "forest" coordinate
and labels to its "labels" coordinates. The data used to plot is then the subset
``column="forest"``.
var_names : str or list 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.
group : str, default "posterior"
Group to be plotted.
coords : dict, optional
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
combined : bool, default False
Whether to plot intervals for each chain or not. Ignored when the "chain" dimension
is not present.
point_estimate : {"mean", "median", "mode"}, optional
Which point estimate to plot. Defaults to rcParam :data:`stats.point_estimate`
ci_kind : {"eti", "hdi"}, optional
Which credible interval to use. Defaults to ``rcParams["stats.ci_kind"]``
ci_probs : array-like of shape (2,), optional
Indicates the probabilities that should be contained within the plotted credible intervals.
It should be sorted as the elements refer to the probabilities of the "trunk" and "twig"
elements. Defaults to ``(0.5, rcParams["stats.ci_prob"])``
labels : sequence of str, optional
Sequence with the dimensions to be labelled in the plot. By default all dimensions
except "chain" and "model" (if present). The order of `labels` is ignored,
only elements being present in it matters.
It can include the special "__variable__" indicator, and does so by default.
shade_label : str, default None
Element of `labels` that should be used to add shading horizontal strips to the plot.
Note that labels and credible intervals are plotted in different :term:`plots`.
The shading is applied to both plots, and the spacing between them is set to 0
*if possible*, which is not always the case (one notable example being matplotlib's
constrained layout).
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence 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` except "ticklabels"
and "remove_axis" which do not apply, and "twig" and "trunk" which
take the same aesthetics through the "credible_interval" key.
By default, aesthetic mappings are generated for: y, alpha, overlay and color
(if multiple models are present). All aesthetic mappings but alpha are applied
to both the credible intervals and the point estimate; overlay is applied
to labels; and both overlay and alpha are applied to the shade.
"overlay" is a dummy aesthetic to trigger looping over variables and/or
dimensions using all aesthetics in every iteration. "alpha" gets two
values (0, 0.3) in order to trigger the alternate shading effect.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* trunk, twig -> passed to :func:`~.visuals.line_x`
* point_estimate -> passed to :func:`~.visuals.scatter_x`
* labels -> passed to :func:`~.visuals.annotate_label`
* shade -> passed to :func:`~.visuals.fill_between_y`
* ticklabels -> passed to :func:`~.backend.xticks`
* remove_axis -> not passed anywhere, can only take ``False`` as value to skip calling
:func:`~.visuals.remove_axis`
stats : mapping, optional
Valid keys are:
* trunk, twig -> passed to eti or hdi
* point_estimate -> passed to mean, median or mode
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.grid`
Returns
-------
PlotCollection
Notes
-----
The separation between variables and all its coordinate values is set to 1.
The only two exceptions to this are the dimensions named "chain" and "model"
in case they are present, which get a smaller spacing to give a sense of
grouping among visual elements that only differ on their chain or model id.
See Also
--------
:ref:`plots_intro` :
General introduction to batteries-included plotting functions, common use and logic overview
plot_ridge : Visual representation of marginal distributions over the y axis
Examples
--------
Single model forest plot with color mapped to the variable (mapping which is also applied
to the labels) and alternate shading per school.
Moreover, to ensure the shading looks continuous, we'll specify we don't want to use
constrained layout (set by the "arviz-variat" theme) and to avoid having the labels
too squished we'll set the ``width_ratios`` for
:func:`~arviz_plots.backend.none.create_plotting_grid` via ``pc_kwargs``.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_forest, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> non_centered = load_arviz_data('non_centered_eight')
>>> pc = plot_forest(
>>> non_centered,
>>> var_names=["theta", "mu", "theta_t", "tau"],
>>> aes={"color": ["__variable__"]},
>>> figure_kwargs={"width_ratios": [1, 2], "layout": "none"},
>>> aes_by_visuals={"labels": ["color"]},
>>> shade_label="school",
>>> )
.. minigallery:: plot_forest
ArviZPythonPlots.plot_ridge — Function
Plot 1D marginal densities in a single plot, akin to a forest plot.
Parameters
----------
dt : DataTree or dict of {str : 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.
``plot_ridge`` uses the dimension "column" (creating it if necessary) to generate the grid
then adds the intervals+point estimates to its "ridge" coordinate
and labels to its "labels" coordinates. The data used to plot is then the subset
``column="ridge"``.
var_names : str or list 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.
group : str, default "posterior"
Group to be plotted.
coords : dict, optional
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
combined : bool, default True
Whether to plot intervals for each chain or not. Ignored when the "chain" dimension
is not present.
ridge_height : float, default 0.9
Regulates the height of the ridge (tallest peak in the ridge). 1 or lower means
no overlap (with ``combined=True``), higher than 1 means some overlap might occur.
See the "Notes" section for more info on vertical spacing.
labels : sequence of str, optional
Sequence with the dimensions to be labelled in the plot. By default all dimensions
except "chain" and "model" (if present). The order of `labels` is ignored,
only elements being present in it matters.
It can include the special "__variable__" indicator, and does so by default.
kind : {"kde", "ecdf", "hist", "dot"}, optional
How to represent the marginal density.
Defaults to ``rcParams["plot.density_kind"]``
shade_label : str, default None
Element of `labels` that should be used to add shading horizontal strips to the plot.
Note that labels and credible intervals are plotted in different :term:`plots`.
The shading is applied to both plots, and the spacing between them is set to 0
*if possible*, which is not always the case (one notable example being matplotlib's
constrained layout).
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence 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` except "ticklabels"
which doesn't apply.
By default, aesthetic mappings are generated for: y, alpha, overlay and color
(if multiple models are present). All aesthetic mappings but alpha are applied
to both the ridge and ridge base; overlay is applied
to labels; and both overlay and alpha are applied to the shade.
"overlay" is a dummy aesthetic to trigger looping over variables and/or
dimensions using all aesthetics in every iteration. "alpha" gets two
values (0, 0.3) in order to trigger the alternate shading effect.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* edge -> passed to :func:`~visuals.line_xy`
* face -> passed to :func:`~.visuals.fill_between_y`
* labels -> passed to :func:`~.visuals.annotate_label`
* shade -> passed to :func:`~.visuals.fill_between_y`
* ticklabels -> passed to :func:`~.backend.xticks`
* remove_axis -> not passed anywhere, can only take ``False`` as value to skip calling
:func:`~.visuals.remove_axis`
stats : mapping, optional
Valid keys are:
* dist -> passed to kde
pc_kwargs : mapping
Passed to :class:`arviz_plots.PlotCollection.grid`
Returns
-------
PlotCollection
Notes
-----
The separation between variables and all its coordinate values is set to 1.
The only two exceptions to this are the dimensions named "chain" and "model"
in case they are present, which get a smaller spacing to give a sense of
grouping among visual elements that only differ on their chain or model id.
See Also
--------
plot_forest : Plot 1D marginal credible intervals in a single plot
Examples
--------
The following example focuses on behaviour specific to ``plot_ridge``.
For a general introduction to batteries-included functions like this one and common
usage examples see :ref:`plots_intro`
This example shows a ridge plot for single model, with color mapped to a given
variable (which is also applied to the labels) and alternate shading per school.
To ensure the shading looks continuous, we'll specify we don't want to use
a constrained layout (set by the "arviz-variat" theme) and to avoid having the labels
too squished we'll set the ``width_ratios`` for
:func:`~arviz_plots.backend.create_plotting_grid` via ``pc_kwargs``.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_ridge, style
>>> from arviz_base import load_arviz_data
>>> style.use("arviz-variat")
>>> non_centered = load_arviz_data('non_centered_eight')
>>> pc = plot_ridge(
>>> non_centered,
>>> var_names=["theta", "mu", "theta_t", "tau"],
>>> aes={"color": ["__variable__"]},
>>> figure_kwargs={"width_ratios": [1, 2], "layout": "none"},
>>> aes_by_visuals={"labels": ["color"]},
>>> shade_label="school",
>>> )
For more examples see below
.. minigallery:: plot_ridge
ArviZPythonPlots.plot_pair — Function
Plot all variables against each other in the dataset.
Parameters
----------
dt : DataTree
Input data
var_names: str or list 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 (default), 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.
group : str, default "posterior"
Group to use for plotting. Defaults to "posterior".
coords : mapping, optional
Coordinates to use for plotting.
sample_dims : iterable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
marginal : bool, default True
Whether to plot marginal distributions on the diagonal.
marginal_kind : {"kde", "hist", "ecdf", "dot"}, optional
How to represent the marginal density.
Defaults to ``rcParams["plot.density_kind"]``
triangle : {"both", "upper", "lower"}, Defaults to "both"
Which triangle of the pair plot to plot.
plot_matrix : PlotMatrix, optional
backend : {"matplotlib", "bokeh", "plotly", "none"}, optional
Plotting backend to use. Defaults to ``rcParams["plot.backend"]``
labeller : labeller, optional
aes_by_visuals : mapping, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_matrix`
when plotted. Valid keys are the same as for `visuals`.
By default, there are no aesthetic mappings at all
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* scatter -> passed to :func:`~.visuals.scatter_couple`
* divergence -> passed to :func:`~.visuals.scatter_couple`. Defaults to False.
* dist -> depending on the value of `marginal_kind` passed to:
* "kde" -> passed to :func:`~arviz_plots.visuals.line_xy`
* "ecdf" -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* "hist" -> passed to :func: `~arviz_plots.visuals.step_hist`
* "dot" -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* credible_interval -> passed to :func:`~arviz_plots.visuals.line_x`
* point_estimate -> passed to :func:`~arviz_plots.visuals.scatter_x`
* point_estimate_text -> passed to :func:`~arviz_plots.visuals.point_estimate_text`
* label -> Keyword arguments passed to :func:`~arviz_plots.visuals.label_plot`.
Used to customize the variable name labels on the diagonal. Applied only
if ``marginal=False``.
* xlabel -> passed to :func:`~.visuals.labelled_x`.
used to customize the xaxis labels on the bottom-most plots or diagonal plots depending
upon the value of ``triangle``. If ``triangle`` is "lower" or "both" then it is used to
map bottom-most row plots by using :meth:`arviz_plots.PlotMatrix.map_row` method and if
``triangle`` is "upper" then it is used to map diagonal plots by using
:meth:`arviz_plots.PlotMatrix.map` method.It is applied only if ``marginal=True``, since
in this case diagonal plots won't have labels to map variables to columns.
* ylabel -> passed to :func:`~.visuals.labelled_y`.
used to customize the yaxis labels on the left-most plots. It is applied, only if
``triangle`` is "lower" or "both" and ``marginal=True``, by using
:meth:`arviz_plots.PlotMatrix.map_col` method. Not applied if ``triangle`` is
"upper" or ``marginal=False``.
* remove_axis -> not passed anywhere.
It can only be set to ``False`` to disable the default removal of ``x`` and ``y`` axes
from the plots of other half triangle. If ``triangle`` is "upper" then the lower triangle
plot's axes will be removed and if ``triangle`` is "lower" then the upper triangle axes
will be removed, in case if it is not set ``False`` manually.
stats : mapping, optional
Valid keys are:
* dist -> passed to kde, ecdf, ...
* credible_interval -> passed to eti or hdi
* point_estimate -> passed to mean, median or mode
**pc_kwargs
Passed to :class:`arviz_plots.PlotMatrix`
Returns
-------
PlotMatrix
Examples
--------
plot_pair with ``triangle`` set to "upper" and ``marginal=True`` with ``marginal_kind`` set to
"ecdf". In this case, since ``triangle`` is "upper", so the ``xlabels`` are mapped to the
diagonal plots. ``marginals`` are plotted on the diagonal and the ``point_estimate`` and
``credible_interval`` are set to ``False`` by default. Also since ``marginal=True``, so
``sharex`` is set to "col", while ``sharey`` is not set to anything by default.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_pair, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('centered_eight')
>>> plot_pair(
>>> dt,
>>> var_names=["mu", "tau"],
>>> visuals={"divergence": True},
>>> marginal=True,
>>> marginal_kind="ecdf",
>>> triangle="upper",
>>> )
plot_pair with `triangle` set to "both", so in this case the ``xlabels`` are mapped to the
bottom-most plots and ``ylabels`` are mapped to the left-most plots. In this example we set
``color`` as "red" for ``credible_interval`` and ``point_estimate``, which enables
``credible_interval`` and ``point_estimate``. By default ``marginal`` is set to ``True`` and
``marginal_kind`` is set to ``rcParams["plot.density_kind"]``.
.. plot::
:context: close-figs
>>> visuals = {"credible_interval":{"color":"red"},"point_estimate":{"color":"red"}}
>>> plot_pair(
>>> dt,
>>> var_names=["mu", "tau"],
>>> visuals=visuals,
>>> triangle="both",
>>> )
plot_pair with ``marginal=False`` and ``triangle`` set to "upper". In this case, since
``marginal=False``, so ``xlabel`` and ``ylabel`` are disabled by default, and diagonal
plots contain variable names as labels. ``xticks`` and ``yticks`` are also set on
diagonal plots along with ``ticklabels``, to map ticks to rows and columns.
Since ``marginal=False``, so ``sharex`` is set to "col" and ``sharey`` is set to "row"
by default.
.. plot::
:context: close-figs
>>> plot_pair(
>>> dt,
>>> coords = {"school":"Choate"},
>>> visuals={"divergence": True},
>>> marginal=False,
>>> triangle="upper",
>>> )
.. minigallery:: plot_pair
ArviZPythonPlots.plot_pair_focus — Function
Plot a fixed variable against other variables in the dataset.
Parameters
----------
dt : DataTree
Input data
focus_var: str or DataArray
Name of the variable or DataArray to be plotted against all other variables.
focus_var_coords : mapping, optional
Coordinates to use for the target variable.
var_names: str or list 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 (default), 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.
group : str, default "posterior"
Group to use for plotting. Defaults to "posterior".
coords : mapping, optional
Coordinates to use for plotting.
sample_dims : iterable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly", "none"}, optional
Plotting backend to use. Defaults to ``rcParams["plot.backend"]``
labeller : labeller, optional
aes_by_visuals : mapping, 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, there are no aesthetic mappings at all
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* scatter -> passed to :func:`~.visuals.scatter_x`
* divergence -> passed to :func:`~.visuals.scatter_xy`. Defaults to False.
* xlabel -> :func:`~.visuals.labelled_x`
* ylabel -> :func:`~.visuals.labelled_y`
**pc_kwargs
Passed to :meth:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
Examples
--------
Default plot_pair_focus
.. plot::
:context: close-figs
>>> from arviz_plots import plot_pair_focus, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('centered_eight')
>>> plot_pair_focus(
>>> dt,
>>> var_names=["mu", "tau"],
>>> focus_var="theta",
>>> focus_var_coords={"school": "Choate"},
>>> )
.. minigallery:: plot_pair_focus
ArviZPythonPlots.plot_prior_posterior — Function
Plot 1D marginal densities for prior and posterior.
The Bayes factor is estimated by comparing a model (H1) against a model
in which the parameter of interest has been restricted to be a point-null (H0)
This computation assumes the models are nested and thus H0 is a special case of H1.
Parameters
----------
dt : DataTree or dict of {str : 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_names : str or list 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.
group : None
This argument is ignored. Have it here for compatibility with other plotting functions.
coords : dict, optional
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
kind : {"kde", "hist", "dot", "ecdf"}, optional
How to represent the marginal density.
Defaults to ``rcParams["plot.density_kind"]``
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. The prior and posterior groups are combined creating a new
dimension "group". By default, there is an aesthetic mapping from group to color.
Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* dist -> depending on the value of `kind` passed to:
* "kde" -> passed to :func:`~arviz_plots.visuals.line_xy`
* "ecdf" -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* "hist" -> passed to :func: `~arviz_plots.visuals.step_hist`
* "dot" -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* legend -> passed to :class:`arviz_plots.PlotCollection.add_legend`
stats : mapping, optional
Valid keys are:
* dist -> passed to kde, ecdf, ...
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
Examples
--------
Select two variables and plot them with an ecdf.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_prior_posterior, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('centered_eight')
>>> plot_prior_posterior(dt, var_names=["mu", "tau"], kind="ecdf")
.. minigallery:: plot_prior_posterior
ArviZPythonPlots.plot_dgof — Function
Plot a Δ-ECDF-PIT diagnostic for 1D marginal distributions.
A Δ-ECDF-PIT diagnostic is plotted to assess the goodness-of-fit of the
estimated distributions to the underlying data using the specified `kind` (kde, histogram,
or quantile dot plot) [1]_. If the estimated distributions are accurate, the PIT values
should be uniformly distributed on [0, 1], resulting in a Δ-ECDF close to zero.
The points that contribute the most to deviations from uniformity are
computed as described in [2]_.
Parameters
----------
dt : DataTree
Input data
var_names : str or list 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"}, optional, default=None
If None (default), 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.
group : str, default "posterior"
Group to be plotted.
coords : dict, optional
Coordinates to be used to index data variables.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
kind : {"kde", "hist", "dot"}, optional
Which method to diagnose the distribution fit.
Defaults to ``rcParams["plot.density_kind"]``
method : {"pot_c", "prit_c", "piet_c", "envelope"}, optional
Method to use for the uniformity test. Defaults to "pot_c". Check the documentation of
:func:`~arviz_plots.plot_ecdf_pit` for more details.
envelope_prob : float, optional
If method is "envelope", indicates the probability that should be contained within the
envelope, otherwise indicates the probability threshold to highlight points.
Defaults to ``rcParams["stats.envelope_prob"]``.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection` when
plotted. Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* credible_interval -> passed to :func:`~arviz_plots.visuals.fill_between_y`
* ecdf_lines -> passed to :func:`~arviz_plots.visuals.line_xy`
* title -> passed to :func:`~arviz_plots.visuals.title`
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
stats : mapping, optional
Valid keys are:
* ecdf_pit -> passed to :func:`~arviz_stats.ecdf_utils.ecdf_pit` or
:func:`~xarray.Dataset.azstats.uniformity_test` depending on the value of `method`.
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.grid`
Returns
-------
PlotCollection
See Also
--------
plot_dgof_dist : Δ-ECDF-PIT diagnostic for 1D density estimation (kde, histogram, or quantile).
plot_dist : Plot 1D marginal distributions.
Examples
--------
Δ-ECDF-PIT diagnostic for quantile dot marginals:
.. plot::
:context: close-figs
>>> from arviz_plots import plot_dgof, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data("centered_eight")
>>> plot_dgof(dt, var_names=["mu" , "tau"], kind="dot");
.. minigallery:: plot_dgof
References
----------
.. [1] Säilynoja et al. *Recommendations for visual predictive checks in Bayesian workflow*.
(2025) arXiv preprint https://arxiv.org/abs/2503.01509
.. [2] Tasso et al. *LOO-PIT predictive model checking* arXiv:2603.02928 (2026).
ArviZPythonPlots.plot_dgof_dist — Function
Plot 1D marginal distributions and a Δ-ECDF-PIT diagnostic.
The marginal distributions are plotted using the specified `kind` (kde, histogram, or quantile
dot plot). Additionally, a Δ-ECDF-PIT diagnostic is plotted to assess the goodness-of-fit of
the estimated distributions to the underlying data [1]_. If the estimated distributions are
accurate, the PIT values should be uniformly distributed on [0, 1], resulting in a Δ-ECDF close
to zero.
The points that contribute the most to deviations from uniformity are
computed as described in [2]_.
Parameters
----------
dt : DataTree
Input data
var_names : str or list 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"}, optional, default=None
If None (default), 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.
group : str, default "posterior"
Group to be plotted.
coords : dict, optional
Coordinates to be used to index data variables.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
kind : {"kde", "hist", "dot"}, optional
How to represent the marginal density.
Defaults to ``rcParams["plot.density_kind"]``
method : {"pot_c", "prit_c", "piet_c", "envelope"}, optional
Method to use for the uniformity test. Defaults to "pot_c". Check the documentation of
:func:`~arviz_plots.plot_ecdf_pit` for more details.
envelope_prob : float, optional
If `method` is "envelope", indicates the probability that should be contained within the
envelope, otherwise indicates the probability threshold to highlight points.
Defaults to ``rcParams["stats.envelope_prob"]``.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection` when
plotted. Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* dist -> depending on the value of `kind` passed to:
* "kde" -> passed to :func:`~arviz_plots.visuals.line_xy`
* "hist" -> passed to :func: `~arviz_plots.visuals.step_hist`
* "dot" -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* credible_interval -> passed to :func:`~arviz_plots.visuals.fill_between_y`
* ecdf_lines -> passed to :func:`~arviz_plots.visuals.line_xy`
* title -> passed to :func:`~arviz_plots.visuals.title`
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
stats : mapping, optional
Valid keys are:
* dist -> passed to kde, ecdf and qds for both dist plot and dgof plot
* ecdf_pit -> passed to :func:`~arviz_stats.ecdf_utils.ecdf_pit` or
:func:`~xarray.Dataset.azstats.uniformity_test` depending on the value of `method`.
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.grid`
Returns
-------
PlotCollection
See Also
--------
plot_dgof : Δ-ECDF-PIT diagnostic for 1D density estimation (kde, histogram, or quantile)
plot_dist : Plot 1D marginal distributions.
Examples
--------
Default plot with quantile dot marginals and Δ-ECDF-PIT diagnostic:
.. plot::
:context: close-figs
>>> from arviz_plots import plot_dgof_dist, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data("centered_eight")
>>> plot_dgof_dist(dt, var_names=["mu" , "tau"], kind="dot");
.. minigallery:: plot_dgof_dist
References
----------
.. [1] Säilynoja et al. *Recommendations for visual predictive checks in Bayesian workflow*.
(2025) arXiv preprint https://arxiv.org/abs/2503.01509
.. [2] Tasso et al. *LOO-PIT predictive model checking* arXiv:2603.02928 (2026).
Inference diagnostics
ArviZPythonPlots.plot_trace — Function
Plot iteration versus sampled values.
Parameters
----------
dt : DataTree
Input data
var_names : str or list 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"}, optional, default=None
If None (default), 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.
group : str, default "posterior"
Group to be plotted.
coords : dict, optional
sample_dims : iterable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh"}, optional
labeller : labeller, optional
aes_by_visuals : mapping, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Defaults to only mapping properties to the trace lines.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* trace -> passed to :func:`~.visuals.line`
* divergence -> passed to :func:`~.visuals.trace_rug`
* title -> :func:`~.visuals.labelled_title`
* xlabel -> :func:`~.visuals.labelled_x`
* ticklabels -> :func:`~.visuals.ticklabel_props`
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection`
Returns
-------
PlotCollection
Examples
--------
The following examples focus on behaviour specific to ``plot_trace``.
For a general introduction to batteries-included functions like this one and common
usage examples see :ref:`plots_intro`
Default plot_trace
.. plot::
:context: close-figs
>>> from arviz_plots import plot_trace, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> centered = load_arviz_data('centered_eight')
>>> plot_trace(centered)
ArviZPythonPlots.plot_trace_dist — Function
Plot 1D marginal distributions and iteration versus sampled values.
Parameters
----------
dt : DataTree
Input data
var_names : str or list 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”}, optional, default=None
If None (default), 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.
group : str, default "posterior"
Group to be plotted.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
compact : bool, default True
Plot multidimensional variables in a single :term:`plot`.
combined : bool, default False
Whether to plot intervals for each chain or not. Ignored when the "chain" dimension
is not present.
kind : {"kde", "hist", "dot", "ecdf"}, optional
How to represent the marginal distribution.
Defaults to ``rcParams["plot.density_kind"]``
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh"}, optional
labeller : labeller, optional
aes_by_visuals : mapping, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection` when
plotted. The defaults depend on the combination of `compact` and `combined`,
see the examples section for an illustrated description.
Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* dist -> depending on the value of `kind` passed to:
* "kde" -> passed to :func:`~arviz_plots.visuals.line_xy`
* "ecdf" -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* "hist" -> passed to :func: `~arviz_plots.visuals.step_hist`
* "dot" -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* "trace" -> passed to :func:`~.visuals.line`
* "divergence" -> passed to :func:`~.visuals.trace_rug`
* "label" -> :func:`~.visuals.labelled_x` and :func:`~.visuals.labelled_y`
* "ticklabels" -> :func:`~.visuals.ticklabel_props`
* "xlabel_trace" -> :func:`~.visuals.labelled_x`
* remove_axis -> not passed anywhere, can only be ``False`` to skip calling this function
stats : mapping, optional
Valid keys are:
* density -> passed to kde, ecdf, ...
pc_kwargs : mapping
Passed to :class:`arviz_plots.PlotCollection`
Returns
-------
PlotCollection
Examples
--------
The following examples focus on behaviour specific to ``plot_trace_dist``.
For a general introduction to batteries-included functions like this one and common
usage examples see :ref:`plots_intro`
Default plot_trace_dist (``compact=True`` and ``combined=False``). In this case,
the multiple coordinate values are overlaid on the same plot for multidimensional values;
by default, the color is mapped to all dimensions of each variable (but `sample_dims`)
to allow distinguising the different coordinate values.
As ``combined=False`` each chain is also being plotted, overlaying them on their
corresponding plots; as the color property is already taken, the chain information
is encoded in the linestyle as default.
Both mappings are applied to the trace and dist elements.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_trace_dist, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> centered = load_arviz_data('centered_eight')
>>> coords = {"school": ["Choate", "Deerfield", "Hotchkiss"]}
>>> pc = plot_trace_dist(centered, coords=coords, compact=True, combined=False)
>>> pc.add_legend(["__variable__", "school"])
plot_trace_dist with ``compact=True`` and ``combined=True``. The aesthetic mappings
stay the same as in the previous case, but now the linestyle property mapping
is only taken into account for the trace as in the left column, we use
the data from all chains to generate a single distribution representation
for each variable+coordinate value combination.
Similarly to the first case, this default and now only mapping is applied to both
the trace and the dist elements.
.. plot::
:context: close-figs
>>> pc = plot_trace_dist(centered, coords=coords, compact=True, combined=True)
>>> pc.add_legend(["__variable__", "school"])
When ``compact=False``, each variable and coordinate value gets its own plot,
and so the color property is no longer used to encode this information.
Instead, it is now used to encode the chain information.
.. plot::
:context: close-figs
>>> pc = plot_trace_dist(centered, coords=coords, compact=False, combined=False)
Similarly to the other ``combined=True`` case, the aesthetics stay the same
as with ``combined=False``, but they are ignored by default when plotting
on the left column.
.. plot::
:context: close-figs
>>> pc = plot_trace_dist(centered, coords=coords, compact=False, combined=True)
>>> pc.add_legend("chain")
ArviZPythonPlots.plot_rank — Function
Fractional rank Δ-ECDF plots.
Rank plots are built by replacing the posterior draws by their ranking computed over all chains.
Then each chain is plotted independently. If all of the chains are targeting the same posterior,
we expect the ranks in each chain to be uniformly distributed.
To simplify comparison we compute the ordered fractional ranks, which are distributed
uniformly in [0, 1]. Additionally, we plot the Δ-ECDF, that is, the difference between the
expected CDF from the observed ECDF.
Simultaneous confidence bands are computed using the simulation method described in [1]_.
The confidence bands assumes no autocorrelation, thus by default the draws are thinned following
the recommendation in [1]_.
Parameters
----------
dt : DataTree
Input data
var_names : str or list of str, optional
One or more variables to be plotted. Currently only one variable is supported.
Prefix the variables by ~ when you want to exclude them from the plot.
filter_vars : {None, “like”, “regex”}, optional, default=None
If None (default), 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.
group : str, optional
Which group to use. Defaults to "posterior".
coords : dict, optional
Coordinates to plot.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
envelope_prob : float, optional
Indicates the probability that should be contained within the envelope.
Defaults to ``rcParams["stats.envelope_prob"]``.
thin : bool, default True
Whether to thin the data before plotting.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* ecdf_lines -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* credible_interval -> passed to :func:`~arviz_plots.visuals.fill_between_y`
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* remove_axis -> not passed anywhere, can only be ``False`` to skip calling this function
stats : mapping, optional
Valid keys are:
* ecdf_pit -> passed to :func:`~arviz_stats.ecdf_utils.ecdf_pit`. Default is
``{"n_simulations": 1000}``.
* thin -> passed to :func:`~arviz_stats.thin`
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
Examples
--------
Rank plot for the crabs hurdle-negative-binomial dataset.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_rank, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('crabs_hurdle_nb')
>>> plot_rank(dt, var_names=["~mu"])
.. minigallery:: plot_rank
References
----------
.. [1] Säilynoja et al. *Graphical test for discrete uniformity and
its applications in goodness-of-fit evaluation and multiple sample comparison*.
Statistics and Computing 32(32). (2022) https://doi.org/10.1007/s11222-022-10090-6
ArviZPythonPlots.plot_rank_dist — Function
Plot 1D marginal distributions and fractional rank Δ-ECDF plots.
Rank plots are built by replacing the posterior draws by their ranking computed over all chains.
Then each chain is plotted independently. If all of the chains are targeting the same posterior,
we expect the ranks in each chain to be uniformly distributed.
To simplify comparison we compute the ordered fractional ranks, which are distributed
uniformly in [0, 1]. Additionally, we plot the Δ-ECDF, that is, the difference between the
expected CDF from the observed ECDF.
Simultaneous confidence bands are computed using simulation method described in [1]_.
Parameters
----------
dt : DataTree
Input data
var_names : str or list 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”}, optional, default=None
If None (default), 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.
group : str, default "posterior"
Group to be plotted.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
compact : bool, default True
Plot multidimensional variables in a single :term:`plot`.
combined : bool, default False
Whether to plot intervals for each chain or not. Ignored when the "chain" dimension
is not present.
kind : {"kde", "hist", "ecdf", "dot"}, optional
How to represent the marginal density.
Defaults to ``rcParams["plot.density_kind"]``
envelope_prob : float, optional
Indicates the probability that should be contained within the envelope.
Defaults to ``rcParams["stats.envelope_prob"]``.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh"}, optional
labeller : labeller, optional
aes_by_visuals : mapping, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection` when
plotted. The defaults depend on the combination of `compact` and `combined`,
see the examples section for an illustrated description.
Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* dist -> depending on the value of `kind` passed to:
* "kde" -> passed to :func:`~arviz_plots.visuals.line_xy`
* "ecdf" -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* "hist" -> passed to :func: `~arviz_plots.visuals.step_hist`
* "dot" -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* "rank" -> passed to :func:`~.visuals.ecdf_line`
* "label" -> :func:`~.visuals.labelled_x` and :func:`~.visuals.labelled_y`
* "ticklabels" -> :func:`~.visuals.ticklabel_props`
* "xlabel_rank" -> :func:`~.visuals.labelled_x`
* remove_axis -> not passed anywhere, can only be ``False`` to skip calling this function
stats : mapping, optional
Valid keys are:
* dist -> passed to kde, ecdf, ...
* ecdf_pit -> passed to :func:`~arviz_stats.ecdf_utils.ecdf_pit`. Default is
``{"n_simulations": 1000}``.
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.grid`
Returns
-------
PlotCollection
Examples
--------
The following examples focus on behaviour specific to ``plot_rank_dist``.
For a general introduction to batteries-included functions like this one and common
usage examples see :ref:`plots_intro`
Default plot_rank_dist (``compact=True`` and ``combined=False``). In this case,
the multiple coordinate values are overlaid on the same plot for multidimensional values;
by default, the color is mapped to all dimensions of each variable (but `sample_dims`)
to allow distinguishing the different coordinate values.
As ``combined=False`` each chain is also being plotted, overlaying them on their
corresponding plots; as the color property is already taken, the chain information
is encoded in the linestyle as default.
Both mappings are applied to the rank and dist elements.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_rank_dist, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> centered = load_arviz_data('centered_eight')
>>> coords = {"school": ["Choate", "Deerfield", "Hotchkiss"]}
>>> pc = plot_rank_dist(centered, coords=coords, compact=True, combined=False)
>>> pc.add_legend(["__variable__", "school"])
plot_rank_dist with ``compact=True`` and ``combined=True``. The aesthetic mappings
stay the same as in the previous case, but now the linestyle property mapping
is only taken into account for the rank as in the left column, we use
the data from all chains to generate a single distribution representation
for each variable+coordinate value combination.
Similarly to the first case, this default and now only mapping is applied to both
the rank and the dist elements.
.. plot::
:context: close-figs
>>> pc = plot_rank_dist(centered, coords=coords, compact=True, combined=True)
>>> pc.add_legend(["__variable__", "school"])
When ``compact=False``, each variable and coordinate value gets its own plot,
and so the color property is no longer used to encode this information.
Instead, it is now used to encode the chain information.
.. plot::
:context: close-figs
>>> pc = plot_rank_dist(centered, coords=coords, compact=False, combined=False)
Similarly to the other ``combined=True`` case, the aesthetics stay the same
as with ``combined=False``, but they are ignored by default when plotting
on the left column.
.. plot::
:context: close-figs
>>> pc = plot_rank_dist(centered, coords=coords, compact=False, combined=True)
>>> pc.add_legend("chain")
References
----------
.. [1] Säilynoja et al. *Graphical test for discrete uniformity and
its applications in goodness-of-fit evaluation and multiple sample comparison*.
Statistics and Computing 32(32). (2022) https://doi.org/10.1007/s11222-022-10090-6
ArviZPythonPlots.plot_ess — Function
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
----------
dt : DataTree or dict of {str : 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_names : str 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.
group : str, default "posterior"
Group to be plotted.
coords : dict, optional
sample_dims : str 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.
relative : bool, default False
Show relative ess in plot ``ress = ess / N``.
rug : bool, default False
Add a `rug plot <https://en.wikipedia.org/wiki/Rug_plot>`_ for a specific subset of values.
rug_kind : str, default "diverging"
Variable in sample stats to use as rug mask. Must be a boolean variable.
n_points : int, default 20
Number of points for which to plot their quantile/local ess or number of subsets
in the evolution plot.
extra_methods : bool, default False
Plot mean and sd ESS as horizontal lines.
min_ess : int, 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_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence 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.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* ess -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* rug -> passed to :func:`~.visuals.trace_rug`
* mean -> passed to :func:`~arviz.plots.visuals.line_xy`
* mean_text -> passed to :func:`~arviz.plots.visuals.annotate_xy`
* sd_text -> passed to :func:`~arviz.plots.visuals.annotate_xy`
* sd -> passed to :func:`~arviz.plots.visuals.line_xy`
* min_ess -> passed to :func:`~arviz.plots.visuals.line_xy`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
* legend -> passed to :class:`arviz_plots.PlotCollection.add_legend`
stats : mapping, 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 :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
See Also
--------
:ref:`plots_intro` :
General introduction to batteries-included plotting functions, common use and logic overview
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:
.. plot::
:context: close-figs
>>> 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"]},
>>> )
We can add extra methods to plot the mean and standard deviation as lines, and adjust
the minimum ess baseline as well:
.. plot::
:context: close-figs
>>> pc = plot_ess(
>>> non_centered,
>>> coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>> extra_methods=True,
>>> min_ess=200,
>>> )
Rugs can also be added:
.. plot::
:context: close-figs
>>> pc = plot_ess(
>>> non_centered,
>>> coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>> rug=True,
>>> )
Relative ESS can be plotted instead of absolute:
.. plot::
:context: close-figs
>>> pc = plot_ess(
>>> non_centered,
>>> coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>> relative=True,
>>> )
We can also adjust the number of points:
.. plot::
:context: close-figs
>>> pc = plot_ess(
>>> non_centered,
>>> coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>> n_points=10,
>>> )
.. minigallery:: plot_ess
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
ArviZPythonPlots.plot_ess_evolution — Function
Plot estimated effective sample size plots for increasing number of iterations.
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
----------
dt : DataTree or dict of {str : 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_names : str 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.
group : str, default "posterior"
Group to be plotted.
coords : dict, optional
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
relative : bool, default False
Show relative ess in plot ``ress = ess / N``.
n_points : int, default 20
Number of subsets in the evolution plot.
extra_methods : bool, default False
Plot mean and sd ESS as horizontal lines.
min_ess : int, default 400
Minimum number of ESS desired. If ``relative=True`` the line is plotted at
``min_ess / n_samples`` as a curve following the ``min_ess / n`` dependency
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence 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`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* ess_bulk -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* ess_bulk_line -> passed to :func:`~arviz_plots.visuals.line_xy`
* ess_tail -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* ess_tail_line -> passed to :func:`~arviz_plots.visuals.line_xy`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
* mean -> passed to :func:`~arviz_plots.visuals.line_xy`
* sd -> passed to :func:`~arviz_plots.visuals.line_xy`
* mean_text -> passed to :func:`~arviz.plots.visuals.annotate_xy`
* sd_text -> passed to :func:`~arviz.plots.visuals.annotate_xy`
* min_ess -> passed to :func:`~arviz_plots.visuals.line_xy`
stats : mapping, optional
Valid keys are:
* ess_bulk -> passed to ess, method = 'bulk'
* ess_tail -> passed to ess, method = 'tail'
* mean -> passed to ess, method='mean'
* sd -> passed to ess, method='sd'
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
See Also
--------
:ref:`plots_intro` :
General introduction to batteries-included plotting functions, common use and logic overview
Examples
--------
When adding a mapping for color across variables, the same color for a variable gets
applied to both the 'bulk' and 'tail' ess. In such a case, if separate linestyles for
'bulk' and 'tail' are desired to distinguish them instead of colors (which is what is
used by default), then this can be implemented:
.. plot::
:context: close-figs
>>> from arviz_plots import plot_ess_evolution, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> non_centered = load_arviz_data('non_centered_eight')
>>> pc = plot_ess_evolution(
>>> non_centered,
>>> var_names=["mu", "tau"],
>>> extra_methods=True,
>>> visuals={
>>> "ess_bulk_line": {"linestyle": "-."},
>>> "ess_tail_line": {"linestyle": ":"},
>>> "ess_bulk": False,
>>> "ess_tail": False,
>>> },
>>> aes= {"color": ["__variable__"]},
>>> aes_by_visuals={"title": ["color"]},
>>> )
The points and lines for ess 'bulk' and 'tail' can be individually switched on and off.
If only the points are desired, and a situation like the previous example occurs,
markers can be used to distinguish between points for 'bulk' and 'tail':
.. plot::
:context: close-figs
>>> pc = plot_ess_evolution(
>>> non_centered,
>>> var_names=["mu", "tau"],
>>> extra_methods=True,
>>> visuals={
>>> "ess_bulk": {"marker": "x"},
>>> "ess_tail": {"marker": "_"},
>>> },
>>> aes={"color": ["__variable__"]},
>>> aes_by_visuals={"title": ["color"]},
>>> )
We can add extra methods to plot the mean and standard deviation as lines, and adjust
the minimum ess baseline as well:
.. plot::
:context: close-figs
>>> pc = plot_ess_evolution(
>>> non_centered,
>>> coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>> extra_methods=True,
>>> min_ess=200,
>>> )
Relative ESS can be plotted instead of absolute:
.. plot::
:context: close-figs
>>> pc = plot_ess_evolution(
>>> non_centered,
>>> coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>> relative=True,
>>> )
We can also adjust the number of points:
.. plot::
:context: close-figs
>>> pc = plot_ess_evolution(
>>> non_centered,
>>> coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>> n_points=10,
>>> )
.. minigallery:: plot_ess_evolution
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
ArviZPythonPlots.plot_mcse — Function
Plot Monte Carlo standard error.
The Monte Carlo standard error (mcse) is a measure of the uncertainty associated
with the estimation of a posterior distribution using Monte Carlo methods.
See [1]_ for more details.
Parameters
----------
dt : DataTree or dict of {str : 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_names : str 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.
group : str, default "posterior"
Group to be plotted.
coords : dict, optional
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
rug : bool, default False
Add a `rug plot <https://en.wikipedia.org/wiki/Rug_plot>`_ for a specific subset of values.
rug_kind : str, default "diverging"
Variable in sample stats to use as rug mask. Must be a boolean variable.
n_points : int, default 20
Number of points for which to plot their quantile/local mcse or number of subsets
in the evolution plot.
extra_methods : bool, default False
Plot mean and sd mcse as horizontal lines.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence 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.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* mcse -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* rug -> passed to :func:`~.visuals.trace_rug`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
* mean -> passed to :func:`~arviz.plots.visuals.line_xy`
* mean_text -> passed to :func:`~arviz.plots.visuals.annotate_xy`
* sd_text -> passed to :func:`~arviz.plots.visuals.annotate_xy`
* sd -> passed to :func:`~arviz.plots.visuals.line_xy`
stats : mapping, optional
Valid keys are:
* mcse -> passed to mcse, method = 'quantile'
* mean -> passed to mcse, method='mean'
* sd -> passed to mcse, method='sd'
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
See Also
--------
:ref:`plots_intro` :
General introduction to batteries-included plotting functions, common use and logic overview
Examples
--------
We can manually map the color to the variable, and have the mapping apply
to the title too instead of only the mcse markers:
.. plot::
:context: close-figs
>>> from arviz_plots import plot_mcse, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> non_centered = load_arviz_data('non_centered_eight')
>>> pc = plot_mcse(
>>> non_centered,
>>> coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>> aes={"color": ["__variable__"]},
>>> aes_by_visuals={"title": ["color"]},
>>> )
We can add extra methods to plot the mean and standard deviation as lines
.. plot::
:context: close-figs
>>> pc = plot_mcse(
>>> non_centered,
>>> coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>> extra_methods=True,
>>> )
Rugs can also be added:
.. plot::
:context: close-figs
>>> pc = plot_mcse(
>>> non_centered,
>>> coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>> rug=True,
>>> )
We can also adjust the number of points:
.. plot::
:context: close-figs
>>> pc = plot_mcse(
>>> non_centered,
>>> coords={"school": ["Choate", "Deerfield", "Hotchkiss"]},
>>> n_points=10,
>>> )
.. minigallery:: plot_mcse
References
----------
.. [1] Vehtari et al. *Rank-normalization, folding, and localization: An improved Rhat for
assmcseing convergence of MCMC*. Bayesian Analysis. 16(2) (2021)
https://doi.org/10.1214/20-BA1221. arXiv preprint https://arxiv.org/abs/1903.08008
ArviZPythonPlots.plot_autocorr — Function
Autocorrelation plots for the given dataset.
Line plot of the autocorrelation function (ACF)
The ACF plots can be used as a convergence diagnostic for posteriors from MCMC
samples.
Parameters
----------
dt : DataTree
Input data
var_names : str or list of str, optional
One or more variables to be plotted. Currently only one variable is supported.
Prefix the variables by ~ when you want to exclude them from the plot.
filter_vars : {None, “like”, “regex”}, optional, default=None
If None (default), 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.
group : str, optional
Which group to use. Defaults to "posterior".
coords : dict, optional
Coordinates to plot.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
max_lag : int, optional
Maximum lag to compute the ACF. Defaults to 100.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* lines -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* ref_line -> passed to :func:`~arviz_plots.visuals.line_xy`
* credible_interval -> passed to :func:`~arviz_plots.visuals.fill_between_y`
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.grid`
Returns
-------
PlotCollection
Examples
--------
Autocorrelation plot for mu variable in the centered eight dataset.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_autocorr, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('centered_eight')
>>> plot_autocorr(dt, var_names=["mu"])
.. minigallery:: plot_autocorr
ArviZPythonPlots.plot_convergence_dist — Function
Plot the distribution of convergence diagnostics (ESS and/or R-hat).
By default all variables are grouped together and one plot per diagnostic is created.
If you are interested in representing individual (multidimensional variables) pass them
in `var_names`.
Information on how the diagnostics are computed can be found in [1]_.
Parameters
----------
dt : DataTree
Input data
var_names : str or list 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.
group : str, default "posterior"
Group to be plotted.
coords : dict, optional
The group for which to compute the convergence diagnostics.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
diagnostics : list of str, optional
List of diagnostics to plot. Defaults to ["ess_bulk", "ess_tail", "rhat_rank"].
Valid diagnostics are "rhat_rank", "rhat_folded", "rhat_z_scale", "rhat_split",
"rhat_identity", "ess_bulk", "ess_tail", "ess_mean", "ess_sd", "ess_quantile",
"ess_local", "ess_median", "ess_mad", "ess_z_scale", "ess_folded" and "ess_identity".
grouped: bool, optional
Whether to plot all variables listed in ``var_names`` together (True)
or separately (False). Defaults to True.
If False, all variables listed in ``var_names`` must be multidimensional.
ref_line : bool, default True
Whether to plot a reference line for the recommended value of each diagnostic.
kind : {"kde", "hist", "dot", "ecdf"}, optional
How to represent the distribution of diagnostics. Default to ecdf
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals` except for "remove_axis"
By default, no mappings are defined for this plot.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* dist -> depending on the value of `kind` passed to:
* "kde" -> passed to :func:`~arviz_plots.visuals.line_xy`
* "ecdf" -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* "hist" -> passed to :func: `~arviz_plots.visuals.step_hist`
* "dot" -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* ref_line -> passed to :func:`~arviz_plots.visuals.vline`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* remove_axis -> not passed anywhere, can only be ``False`` to skip calling this function
stats : mapping, optional
Valid keys are:
* dist -> passed to kde, ecdf, ...
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
Examples
--------
Select a single variable and specify diagnostics
.. plot::
:context: close-figs
>>> from arviz_plots import plot_convergence_dist, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> radon = load_arviz_data('radon')
>>> plot_convergence_dist(
>>> radon,
>>> var_names=["za_county"],
>>> diagnostics=["rhat", "ess_tail"]
>>> )
Some ess methods accepts a probability argument
.. plot::
:context: close-figs
>>> plot_convergence_dist(
>>> radon,
>>> var_names=["za_county"],
>>> diagnostics=[
>>> "ess_tail(0.1, 0.9)",
>>> "ess_local(0.1, 0.9)",
>>> "ess_quantile(0.9)"
>>> ]
>>> )
Select two variables and plot them separately
.. plot::
:context: close-figs
>>> plot_convergence_dist(
>>> radon,
>>> var_names=["za_county", "a"],
>>> grouped=False,
>>> )
.. minigallery:: plot_convergence_dist
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
ArviZPythonPlots.plot_energy — Function
Plot energy distributions and bfmi from gradient-based algorithms.
Generate a figure with the marginal energy distribution and the energy transition
distribution. Optionally, include a BFMI panel to inspect chain-wise Bayesian Fraction
of Missing Information values. Values below the threshold indicate poor exploration
of the energy distribution.
For details on BFMI and energy diagnostics see [1]_ for a more practical overview check
the EABM chapter on MCMC diagnostic `of gradient-based algorithms <https://arviz-devs.github.io/EABM/Chapters/MCMC_diagnostics.html#diagnosis-of-gradient-based-algorithms>`_.
Parameters
----------
dt : DataTree
``sample_stats`` group with an ``energy`` variable is mandatory.
sample_dims : sequence of str, optional
Dimensions to consider as sample dimensions when computing BFMI.
Defaults to ``rcParams["data.sample_dims"]``
kind : {"kde", "hist", "dot", "ecdf"}, optional
How to represent the marginal density.
Defaults to ``rcParams["plot.density_kind"]``
show_bfmi : bool, default True
Whether to include the BFMI scatter plot. If ``False``, only the energy plot will be shown.
threshold : float, default 0.3
Reference threshold for BFMI values, values below this indicate poor exploration of the
energy distribution.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* dist -> depending on the value of `kind` passed to:
* "kde" -> passed to :func:`~arviz_plots.visuals.line_xy`
* "ecdf" -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* "hist" -> passed to :func:`~arviz_plots.visuals.step_hist`
* "dot" -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* legend -> passed to :class:`arviz_plots.PlotCollection.add_legend`
* remove_axis -> not passed anywhere, can only be ``False`` to skip calling this function
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* bfmi_points -> passed to :func:`~arviz_plots.visuals.scatter_xy` for BFMI scatter plot
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y` for BFMI column y-axis label
* face -> :term:`visual` that fills the area under the energy distributions.
Defaults to True. Depending on the value of `kind` it is passed to:
* "kde" or "ecdf" -> passed to :func:`~arviz_plots.visuals.fill_between_y`
* "hist" -> passed to :func:`~arviz_plots.visuals.hist`
* dot -> ignored
stats : mapping, optional
Valid keys are:
* dist -> passed to kde, ecdf, ...
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
Examples
--------
Plot an energy plot using ecdf for the energy distributions.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_energy, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> data = load_arviz_data('non_centered_eight')
>>> plot_energy(data, kind="ecdf")
.. minigallery:: plot_energy
References
----------
.. [1] Betancourt. Diagnosing Suboptimal Cotangent Disintegrations in
Hamiltonian Monte Carlo. (2016) https://arxiv.org/abs/1604.00695
ArviZPythonPlots.plot_parallel — Function
Plot parallel coordinates plot showing posterior points with and without divergences.
Parameters
----------
dt : DataTree
Input data
var_names: str or list 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 (default), 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.
group : str, default "posterior"
Group to use for plotting. Defaults to "posterior".
coords : mapping, optional
Coordinates to use for plotting.
sample_dims : iterable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
norm_method : {None, "normal", "minmax", "rank"}, default None
Transformation to apply to the samples before plotting.
label_type : {"flat", "vert"}, default "flat"
Indicator of which `labeller` method to use when generating the
labels of the x axis.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly", "none"}, optional
Plotting backend to use. Defaults to ``rcParams["plot.backend"]``
labeller : labeller, optional
aes_by_visuals : mapping, 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, there is a mapping from the value of `diverging` variable to
color and alpha which is only active for the "line" visual.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* line -> passed to :func:`~.visuals.multiple_lines`
* xticks -> passed to :func:`~.visuals.set_xticks`. Defaults to False.
**pc_kwargs
Passed to :meth:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
Examples
--------
Default plot_parallel without normalization and with default `label_type` as "flat".
.. plot::
:context: close-figs
>>> from arviz_plots import plot_parallel, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('centered_eight')
>>> plot_parallel(dt)
parallel_plot with `norm_method` set to "normal" and `label_type` set to "vert"
and rotation of xaxis labels set to 30 degrees.
.. plot::
:context: close-figs
>>> plot_parallel(
>>> dt,
>>> norm_method="normal",
>>> label_type="vert",
>>> visuals={"xticks": {"rotation": 30}},
>>> )
.. minigallery:: plot_parallel
ArviZPythonPlots.plot_lm — Function
Posterior predictive and mean plots for regression-like data.
Parameters
----------
dt : DataTree
Input data
x : str or sequence of str, optional
Independent variable. If None, use the first variable in group.
Data will be taken from the constant_data group unless the `group` argument is
"predictions" in which case it is taken from the predictions_constant_data group.
The plots and visuals in the generated ``PlotCollection`` object will use `x` for naming.
y : str or sequence of str, optional
Response variable or linear term. If None, use the first variable in observed_data group.
y_obs : str or DataArray, optional
Observed response variable. If None, use `y`.
plot_dim : str, optional
Dimension to be represented as the x axis. Defaults to the last dimension
in the data for `x` not in ``sample_dims``. It should be present in the
data for `y` too.
filter_vars: {None, “like”, “regex”}, default None
If None (default), 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.
It is used for any of y, x, y_pred, and x_pred if they are strings or lists of strings.
group : str, default "posterior_predictive"
Group to use for plotting.
coords : mapping, optional
Coordinates to use for plotting.
sample_dims : iterable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
smooth : bool, default True
If True, apply a Savitzky-Golay filter to smooth the lines.
ci_kind : {"hdi", "eti"}, optional
Which credible interval to use. Defaults to ``rcParams["stats.ci_kind"]``
ci_prob : float or array-like of float, optional
Indicates the probabilities that should be contained within the plotted credible intervals.
Defaults to ``rcParams["stats.ci_prob"]``
point_estimate : {"mean", "median", "mode"}, optional
Which point_estimate to use for the line. Defaults to ``rcParams["stats.point_estimate"]``
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh"}, optional
xlabeller, ylabeller : labeller, optional
Labeller for the x and y axes. Will use the `make_label_vert` method of the labeller.
By default, `xlabeller` is a :class:`~arviz_base.labels.BaseLabeller` and
`ylabeller` is a :class:`~arviz_base.labels.MapLabeller` that maps values of
`x` to their respective `y` value given the first ones are used to name things
in the ``PlotCollection``.
aes_by_visuals : mapping, 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, the color is mapped to the variable which is active for the "ci_band" visual.
If `ci_prob` is not a scalar a mapping from prob->alpha is also added which is
active for "ci_band" and "ci_vlines" visuals.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* pe_line-> passed to :func:`~.visuals.line_xy`.
Line that represent the mean, median, or mode of the predictions, E(y|x), or of the
linear predictor, E(η|x).
* ci_band -> passed to :func:`~.visuals.fill_between_y`.
Filled area that represents a credible interval for E(y|x) or E(η|x).
* ci_bounds -> passed to :func:`~.visuals.line_xy`. Defaults to False
Lines that represent the upper and lower bounds of a credible interval
for E(y|x) or E(η|x). This is similar to "ci_band", but uses lines
for the boundaries instead of a filled area.
* ci_vlines -> passed to :func:`~.visuals.ci_line_y`. Defaults to False
This is intended for categorical x values or discrete variables with
few unique values of x for which ci_band or ci_bounds do not work well.
Represents the same information as these two visuals but as multiple vertical lines,
similar to :func:`~arviz_plots.plot_ppc_interval`
* observed_scatter -> passed to :func:`~.visuals.scatter_xy`.
Represents the observed data points.
* xlabel -> passed to :func:`~.visuals.labelled_x`.
* ylabel -> passed to :func:`~.visuals.labelled_y`.
stats : mapping, optional
Valid keys are:
* credible_interval -> passed to eti or hdi. Affects all 3 visual elements
related to the credible intervals
* pe_line -> passed to mean, median or mode
* smooth -> passed to :func:`scipy.signal.savgol_filter`.
It also takes an extra ``n_points`` key to control the number of points
in the interpolation grid that is passed to the smoothing filter.
Affects the 4 visual elements related to credible intervals or point estimates.
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
Examples
--------
Customized linear model plot for roaches_zinb dataset.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_lm, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('roaches_zinb')
>>> pc = plot_lm(dt,
>>> ci_prob=(0.50, 0.90),
>>> point_estimate="median",
>>> visuals={
>>> "pe_line":{"color":"C2", "linestyle":"C1"},
>>> "ci_band":{"color":"C1"},
>>> "observed_scatter":False,
>>> },
>>> )
.. minigallery:: plot_lm
Predictive checks
ArviZPythonPlots.plot_ppc_dist — Function
Plot 1D marginals for the predictive distribution and the observed data.
Parameters
----------
dt : DataTree
If group is "posterior_predictive", it should contain the ``posterior_predictive`` and
``observed_data`` groups. If group is "prior_predictive", it should contain the
``prior_predictive`` group.
var_names : str or list 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.
group : str,
Group to be plotted. Defaults to "posterior_predictive".
It could also be "prior_predictive".
coords : dict, optional
sample_dims : str or sequence of hashable, optional
Sampled dimensions used to overlay `num_samples` lines.
Defaults to ``rcParams["data.sample_dims"]``
kind : {"auto", "kde", "hist", "ecdf", "dot"}, optional
How to represent the marginal density. Defaults to ``rcParams["plot.density_kind"]``
If "dot" is selected, only the top points of the predictive draws are shown.
num_samples : int, optional
Number of samples to plot. Defaults to 100.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals` except "remove_axis".
With a single model, no aesthetic mappings are generated by default,
each variable+coord combination gets a :term:`plot` but they all look the same,
unless there are user provided aesthetic mappings.
With multiple models, ``plot_dist`` maps "color" and "y" to the "model" dimension.
By default, all aesthetics but "y" are mapped to the distribution representation,
and if multiple models are present, "color" and "y" are mapped to the
credible interval and the point estimate.
When "point_estimate" key is provided but "point_estimate_text" isn't,
the values assigned to the first are also used for the second.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* predictive_dist, observed_dist -> passed to a function that depends on
the `kind` argument.
* "kde" -> passed to :func:`~arviz_plots.visuals.line_xy`
* "ecdf" -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* "hist" -> passed to :func: `~arviz_plots.visuals.step_hist`
* "dot" -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* remove_axis -> not passed anywhere, can only be ``False`` to skip calling this function
observed_dist defaults to False, no observed data is plotted, if group is
"prior_predictive".
stats : mapping, optional
Valid keys are:
* predictive_dist, observed_dist -> passed to kde, ecdf, ...
**pc_kwargs
Passed to :meth:`~arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
See Also
--------
:ref:`plots_intro` :
General introduction to batteries-included plotting functions, common use and logic overview
Examples
--------
Make a plot of the posterior predictive distribution vs the observed data.
We used an ECDF representation customized the colors.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_ppc_dist, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> radon = load_arviz_data('radon')
>>> pc = plot_ppc_dist(
>>> radon,
>>> kind="ecdf",
>>> visuals={
>>> "predictive_dist": {"color":"C1"},
>>> "observed_dist": {"color":"C3"}
>>> },
>>> )
Faceting and aesthetics mappings happen on unique coordinate values. If there are repeated
coordinate values they will be grouped and reduced along with `sample_dims`.
This example updates the coordinate values to have repeated values and requests
faceting along the "obs_id" dimension. It also keeps 90 out of the 919 observations
in the original dataset; otherwise we'd end up with 85 :term:`plots` in the :term:`figure`
.. plot::
:context: close-figs
>>> county = radon.constant_data["County"][radon.constant_data["county_idx"]]
>>> reindexed_dt = radon.filter(
>>> lambda node: node.name in ("observed_data", "posterior_predictive")
>>> ).map_over_datasets(
>>> lambda node: node.assign_coords(obs_id=county).isel(obs_id=slice(None, 90))
>>> )
>>> pc = azp.plot_ppc_dist(reindexed_dt, cols=["obs_id"], kind="auto")
Note how counties with a lot of observations have a smoother ECDF whereas counties
with only 2-3 observations have only 2-3 steps in their ECDF.
.. minigallery:: plot_ppc_dist
ArviZPythonPlots.plot_ppc_dist_pit — Function
1D marginals for the predictive distribution and PIT Δ-ECDF.
The left column shows 1D marginals for the posterior predictive distribution
overlaid on the observed data, identical to :func:`~arviz_plots.plot_ppc_dist`.
The right column shows the empirical CDF (ECDF) of the PIT values minus the expected
CDF, identical to :func:`~arviz_plots.plot_ppc_pit`.
Suspicious observations are computed from the uniformity test and they are highlighted
in both columns, either as rug marks at y=0 in the dist column or as points in ECDF for
the PIT column. The suspicious observations are the ones that contribute the most to
deviations from uniformity.
Parameters
----------
dt : DataTree
Input data with ``posterior_predictive`` and ``observed_data`` groups.
var_names : str or list of str, optional
Variables to plot.
filter_vars : {None, "like", "regex"}, optional
group : str,
Group to be plotted. Defaults to "posterior_predictive".
It could also be "prior_predictive".
coords : dict, optional
sample_dims : str or sequence of hashable, optional
Defaults to ``rcParams["data.sample_dims"]``.
kind : {"auto", "kde", "hist", "ecdf", "dot"}, optional
Density kind for the dist column.
Defaults to ``rcParams["plot.density_kind"]``.
num_samples : int, default 50
Number of predictive draws to overlay in the dist column.
method : {"pot_c", "prit_c", "piet_c", "envelope"}, default "pot_c"
Uniformity-test method for the PIT column.
envelope_prob : float, optional
Probability inside the simultaneous envelope.
Defaults to ``rcParams["stats.envelope_prob"]``.
coverage : bool, default False
If True, replace PIT with ``2|PIT - 0.5|`` to assess ETI coverage.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping, optional
Valid keys: ``predictive_dist``, ``observed_dist``, ``ecdf_lines``,
``credible_interval``, ``suspicious_points``, ``p_value_text``, ``title``.
visuals : mapping, optional
Valid keys:
* predictive_dist -> density lines for predictive draws
* observed_dist -> density line for observed data
* ecdf_lines -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* credible_interval -> only when ``method="envelope"``
* suspicious_points -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* p_value_text -> passed to :func:`~arviz_plots.visuals.annotate_xy`
* xlabel_dist -> x-axis label for the dist column
* xlabel_pit -> x-axis label for the PIT column
* ylabel -> y-axis label for the PIT column
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* remove_axis -> set to ``False`` to skip axis removal
stats : mapping, optional
Valid keys: ``predictive_dist``, ``observed_dist``, ``ecdf_pit``.
**pc_kwargs
Passed to :class:`~arviz_plots.PlotCollection.grid`.
Returns
-------
PlotCollection
See Also
--------
plot_ppc_dist : Predictive density check only.
plot_ppc_pit : PIT Δ-ECDF check only.
Examples
--------
.. plot::
:context: close-figs
>>> from arviz_plots import plot_ppc_dist_pit, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('radon')
>>> plot_ppc_dist_pit(dt)
.. minigallery:: plot_ppc_dist_pit
ArviZPythonPlots.plot_ppc_rootogram — Function
Rootogram with confidence intervals per predicted count.
Rootograms are useful to check the calibration of count models.
A rootogram shows the difference between observed and predicted counts. The y-axis,
showing frequencies, is on the square root scale. This makes easier to compare
observed and expected frequencies even for low frequencies [1]_ and [2]_.
For more details on how to interpret this plot,
see https://arviz-devs.github.io/EABM/Chapters/Prior_posterior_predictive_checks.html
Parameters
----------
dt : DataTree
If group is "posterior_predictive", it should contain the ``posterior_predictive`` and
``observed_data`` groups. If group is "prior_predictive", it should contain the
``prior_predictive`` group.
var_names : str or list of str, optional
One or more variables to be plotted. Currently only one variable is supported.
Prefix the variables by ~ when you want to exclude them from the plot.
filter_vars : {None, “like”, “regex”}, optional, default=None
If None (default), 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.
group : str,
Group to be plotted. Defaults to "posterior_predictive".
It could also be "prior_predictive".
coords : dict, optional
Coordinates to plot.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to rcParam :data:`data.sample_dims`.
ci_prob : float, optional
Probability for the credible interval. Defaults to rcParam :data:`stats.ci_prob`.
point_estimate : {"mean", "median", "mode"}, optional
Which point estimate to plot. Defaults to rcParam :data:`stats.point_estimate`
yscale : str, optional
Scale for the y-axis. Defaults to "sqrt", pass "linear" for linear scale.
Currently only "matplotlib" backend is supported. For "bokeh" and "plotly"
the y-axis is linear.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* predictive_markers -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* observed_markers -> passed to :func:`~arviz_plots.visuals.scatter_xy`.
* credible_interval -> passed to :func:`~arviz_plots.visuals.ci_line_y`
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
* grid -> passed to :func:`~arviz_plots.visuals.grid`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
observed_markers defaults to False, no observed data is plotted, if group is
"prior_predictive". Pass an (empty) mapping to plot the observed data.
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
Examples
--------
Plot the rootogram for the crabs dataset.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_ppc_rootogram, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('crabs_poisson')
>>> plot_ppc_rootogram(dt)
.. minigallery:: plot_ppc_rootogram
References
----------
.. [1] Kleiber C, Zeileis A. *Visualizing Count Data Regressions Using Rootograms*.
The American Statistician, 70(3). (2016) https://doi.org/10.1080/00031305.2016.1173590
.. [2] Säilynoja et al. *Recommendations for visual predictive checks in Bayesian workflow*.
(2025) arXiv preprint https://arxiv.org/abs/2503.01509
ArviZPythonPlots.plot_ppc_pava — Function
PAV-adjusted calibration plot.
Uses the pool adjacent violators (PAV) algorithm for isotonic regression.
A 45-degree line corresponds to perfect calibration.
Details are discussed in [1]_ and [2]_.
Parameters
----------
dt : DataTree
Input data
var_names : str or list of str, optional
One or more variables to be plotted. Currently only one variable is supported.
Prefix the variables by ~ when you want to exclude them from the plot.
filter_vars : {None, “like”, “regex”}, optional, default=None
If None (default), 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.
group : str, optional
The group from which to get the unique values. Defaults to "posterior_predictive".
It could also be "prior_predictive". Notice that this plots always use the "observed_data"
so use with extra care if you are using "prior_predictive".
coords : dict, optional
Coordinates to plot. CURRENTLY NOT IMPLEMENTED
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
data_type : str
Defaults to "binary". Other options are "categorical" and "ordinal".
If "categorical", the plot will show the "one-vs-others" calibration and generate one plot
per category. If "ordinal", the plot will display cumulative conditional event
probabilities and generate (number of categories - 1) plots.
ci_prob : float, optional
Probability for the credible interval. Defaults to ``rcParams["stats.ci_prob"]``.
plot_collection : PlotCollection, optional
num_samples : int, optional
Number of samples to use for the plot. Defaults to 100.
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* lines -> passed to :func:`~arviz_plots.visuals.line_xy`
* markers -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* reference_line -> passed to :func:`~arviz_plots.visuals.line_xy`
* credible_interval -> passed to :func:`~arviz_plots.visuals.fill_between_y`
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
markers defaults to False, no markers are plotted.
Pass an (empty) mapping to plot markers.
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.grid`
Returns
-------
PlotCollection
Examples
--------
Plot the PAVA calibration plot for the rugby dataset.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_ppc_pava, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('rugby')
>>> plot_ppc_pava(dt, ci_prob=0.90)
.. minigallery:: plot_ppc_pava
References
----------
.. [1] Säilynoja et al. *Recommendations for visual predictive checks in Bayesian workflow*.
(2025) arXiv preprint https://arxiv.org/abs/2503.01509
.. [2] Dimitriadis et al *Stable reliability diagrams for probabilistic classifiers*.
PNAS, 118(8) (2021). https://doi.org/10.1073/pnas.2016191118
ArviZPythonPlots.plot_ppc_pava_residuals — Function
PAV-adjusted calibration residual plot.
Uses the pool adjacent violators (PAV) algorithm for isotonic regression and computes
residuals as the difference between the calibrated event probabilities (CEP) and the
predicted probabilities. A horizontal line at zero corresponds to perfect calibration.
Details are discussed in [1]_ and [2]_.
Parameters
----------
dt : DataTree
Input data
x_var : array-like, series, DataArray, or str
Variable to use for x-axis. If a string is given, it should be the name of a variable
in the `constant_data` group.
var_names : str or list of str, optional
One or more variables to be plotted. Currently only one variable is supported.
Prefix the variables by ~ when you want to exclude them from the plot.
filter_vars : {None, "like", "regex"}, optional, default=None
If None (default), 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.
group : str, optional
The group from which to get the unique values. Defaults to "posterior_predictive".
It could also be "prior_predictive". Notice that this plots always use the "observed_data"
so use with extra care if you are using "prior_predictive".
coords : dict, optional
Coordinates to plot. CURRENTLY NOT IMPLEMENTED
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
data_type : str
Defaults to "binary". Other options are "categorical" and "ordinal".
If "categorical", the plot will show the "one-vs-others" calibration and generate one plot
per category. If "ordinal", the plot will display cumulative conditional event
probabilities and generate (number of categories - 1) plots.
ci_prob : float, optional
Probability for the credible interval. Defaults to ``rcParams["stats.ci_prob"]``.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* markers -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* reference_line -> passed to :func:`~arviz_plots.visuals.line_x`
* credible_interval -> passed to :func:`~arviz_plots.visuals.fill_between_y`
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
markers defaults to True for residual plots.
Pass False to disable markers.
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.grid`
Returns
-------
PlotCollection
Examples
--------
Plot the PAVA residual plot for the zeros and non-zeros in a
negative bimomial model of the roaches dataset.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_ppc_pava_residuals, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('roaches_nb')
>>> plot_ppc_pava_residuals(dt,
>>> var_names="y_pos",
>>> x_var="roach count")
.. minigallery:: plot_ppc_pava_residuals
References
----------
.. [1] Säilynoja et al. *Recommendations for visual predictive checks in Bayesian workflow*.
(2025) arXiv preprint https://arxiv.org/abs/2503.01509
.. [2] Dimitriadis et al *Stable reliability diagrams for probabilistic classifiers*.
PNAS, 118(8) (2021). https://doi.org/10.1073/pnas.2016191118
ArviZPythonPlots.plot_ppc_pit — Function
PIT Δ-ECDF values with simultaneous confidence envelope.
For a calibrated model the Probability Integral Transform (PIT) values,
$p(\tilde{y}_i \le y_i \mid y)$, should be uniformly distributed.
Where $y_i$ represents the observed data for index $i$ and $\tilde y_i$ represents
the posterior predictive sample at index $i$.
This plot shows the empirical cumulative distribution function (ECDF) of the PIT values.
To make the plot easier to interpret, we plot the Δ-ECDF, that is, the difference between
the observed ECDF and the expected CDF.
The points that contribute the most to deviations from uniformity are
computed as described in [1]_ and highlighted in the plot.
Alternatively, we can visualize the coverage of the central posterior credible intervals by
setting ``coverage=True``. This allows us to assess whether the credible intervals includes
the observed values. We can obtain the coverage of the central intervals from the PIT by
replacing the PIT with two times the absolute difference between the PIT values and 0.5.
For more details on how to interpret this plot,
see https://arviz-devs.github.io/EABM/Chapters/Prior_posterior_predictive_checks.html#pit-ecdfs.
Parameters
----------
dt : DataTree
Input data
var_names : str or list of str, optional
One or more variables to be plotted. Currently only one variable is supported.
Prefix the variables by ~ when you want to exclude them from the plot.
filter_vars : {None, “like”, “regex”}, optional, default=None
If None (default), 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.
group : str,
Group to be plotted. Defaults to "posterior_predictive".
It could also be "prior_predictive".
coords : dict, optional
Coordinates to plot.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
method : {"pot_c", "prit_c", "piet_c", "envelope"}, optional
Method to use for the uniformity test. Defaults to "pot_c".
Check the documentation of :func:`~arviz_plots.plot_ecdf_pit` for
more details.
envelope_prob : float, optional
Indicates the probability that should be contained within the envelope.
Defaults to ``rcParams["stats.envelope_prob"]``.
coverage : bool, optional
If True, plot the coverage of the central posterior credible intervals. Defaults to False.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* ecdf_lines -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* credible_interval -> passed to :func:`~arviz_plots.visuals.fill_between_y`,
only when method is "envelope"
* ref_line -> passed to :func:`~arviz_plots.visuals.line_xy`
* suspicious_points -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* p_value_text -> passed to :func:`~arviz_plots.visuals.annotate_xy`
only when method is not "envelope"
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* remove_axis -> not passed anywhere, can only be ``False`` to skip calling this function
stats : mapping, optional
Valid keys are:
* ecdf_pit -> passed to :func:`~arviz_stats.ecdf_utils.ecdf_pit`. Default is
``{"n_simulations": 1000}``.
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
See Also
--------
plot_loo_pit : Predictive check using LOO-PIT Δ-ECDF uniformity test.
plot_ppc_dist : Predictive check using 1D marginals for predictive (and observed data).
plot_ppc_pava : Predictive check ideal for binary, ordinal or categorical data.
plot_ppc_rootogram : Predictive check ideal for discrete (count) data.
Examples
--------
Plot the ecdf-PIT for the crabs hurdle-negative-binomial dataset.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_ppc_pit, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('crabs_hurdle_nb')
>>> plot_ppc_pit(dt)
Plot the coverage for the crabs hurdle-negative-binomial dataset.
.. plot::
:context: close-figs
>>> plot_ppc_pit(dt, coverage=True)
.. minigallery:: plot_ppc_pit
References
----------
.. [1] Tasso et al. *LOO-PIT predictive model checking* arXiv:2603.02928 (2026).
ArviZPythonPlots.plot_ppc_tstat — Function
Plot Bayesian t-stat for observed data and posterior/prior predictive.
Parameters
----------
dt : DataTree
If group is "posterior_predictive", it should contain the ``posterior_predictive`` and
``observed_data`` groups. If group is "prior_predictive", it should contain the
``prior_predictive`` group.
var_names : str or list 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.
group : str,
Group to be plotted. Defaults to "posterior_predictive".
It could also be "prior_predictive".
coords : dict, optional
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
t_stat : str, float, or callable() default "median"
Test statistics to compute from the observations and predictive distributions.
Allowed strings are “mean”, “median”, “std”, “var”, “min”, “max”, “iqr”
(interquartile range) and “mad” (median absolute deviation). Alternative a
quantile can be passed as a float (or str) in the interval (0, 1). Finally,
a user defined function is also accepted.
kind : {"kde", "hist", "ecdf", "dot"}, optional
How to represent the marginal density.
Defaults to ``rcParams["plot.density_kind"]``
point_estimate : {"mean", "median", "mode"}, optional
Which point estimate to plot. Defaults to rcParam :data:`stats.point_estimate`
ci_kind : {"eti", "hdi"}, optional
Which credible interval to use. Defaults to ``rcParams["stats.ci_kind"]``
ci_prob : float, optional
Indicates the probability that should be contained within the plotted credible interval.
Defaults to ``rcParams["stats.ci_prob"]``
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
data_pairs : dict, optional
Dictionary of keys prior/posterior predictive data and values observed data variable names.
If None, it will assume that the observed data and the predictive data have
the same variable name.
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals` exept for "remove_axis"
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* dist -> depending on the value of `kind` passed to:
* "kde" -> passed to :func:`~arviz_plots.visuals.line_xy`
* "ecdf" -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* "hist" -> passed to :func: `~arviz_plots.visuals.step_hist`
* "dot" -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* observed_tstat -> passed to :func:`~arviz_plots.visuals.scatter_x`.
* credible_interval -> passed to :func:`~arviz_plots.visuals.line_x`. Defaults to False.
* point_estimate -> passed to :func:`~arviz_plots.visuals.scatter_x`. Defaults to False.
* point_estimate_text -> passed to :func:`~arviz_plots.visuals.point_estimate_text`.
Defaults to False.
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* rug -> passed to :func:`~arviz_plots.visuals.scatter_x`. Defaults to False.
* remove_axis -> not passed anywhere, can only be ``False`` to skip calling this function
observed_tstat defaults to False, no observed data is plotted, if group is
"prior_predictive".
stats : mapping, optional
Valid keys are:
* dist -> passed to kde, ecdf, ...
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
Examples
--------
Use 25th percentile (quantile 0.25) as t-statistic
.. plot::
:context: close-figs
>>> from arviz_plots import plot_ppc_tstat, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('radon')
>>> plot_ppc_tstat(dt, t_stat="0.25")
Define custom t-statistic function and plot histogram
.. plot::
:context: close-figs
>>> def cv(x):
>>> return np.std(x, axis=0) / np.mean(x, axis=0)
>>> plot_ppc_tstat(dt, t_stat=cv, kind="hist")
Use median as t-statistic and plot point-interval
.. plot::
:context: close-figs
>>> azp.plot_ppc_tstat(
>>> dt,
>>> visuals={
>>> "dist": False,
>>> "credible_interval": {},
>>> "point_estimate": {},
>>> }
>>> )
.. minigallery:: plot_ppc_tstat
ArviZPythonPlots.plot_ppc_interval — Function
Plot posterior predictive intervals with observed data overlaid.
Displays observed data as a point and predicted data as a point estimate plus two
credible intervals.
Parameters
----------
dt : DataTree
Input data. It should contain the ``posterior_predictive`` and
``observed_data`` groups.
var_names : str or list 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.
group : str
Group to be plotted. Defaults to "posterior_predictive".
It could also be "prior_predictive".
coords : dict, optional
Coordinates of `var_names` to be plotted.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
point_estimate : {"mean", "median", "mode"}, optional
Which point estimate to plot for the predictive distribution.
Defaults to rcParam ``stats.point_estimate``.
ci_kind : {"hdi", "eti"}, optional
Which credible interval to use. Defaults to ``rcParams["stats.ci_kind"]``.
ci_probs : (float, float), optional
Indicates the probabilities for the inner (twig) and outer (trunk) credible intervals.
Defaults to ``(0.5, rcParams["stats.ci_prob"])``. It's assumed that
``ci_probs[0] < ci_probs[1]``, otherwise they are sorted.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly", "none"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str or False}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* trunk, twig -> passed to :func:`~arviz_plots.visuals.ci_bound_y`
* observed_markers -> passed to :func:`~arviz_plots.visuals.point_y`
* prediction_markers -> passed to :func:`~arviz_plots.visuals.point_y`
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title` defaults to False
stats : mapping, optional
Valid keys are:
* trunk, twig -> passed to eti or hdi
* point_estimate -> passed to mean, median or mode
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.grid`
Returns
-------
PlotCollection
See Also
--------
plot_loo_interval : Plot LOO posterior predictive intervals and observed data.
plot_ppc_dist : Plot 1D marginals for the posterior/prior predictive and observed data.
plot_ppc_rootogram : Plot ppc rootogram for discrete (count) data
plot_forest : Plot forest plot for posterior/prior groups.
Examples
--------
Plot posterior predictive intervals for the radon dataset, with custom styling.
.. plot::
:context: close-figs
>>> from arviz_base import load_arviz_data
>>> import arviz_plots as azp
>>> azp.style.use("arviz-variat")
>>> data = load_arviz_data("rugby")
>>> pc = azp.plot_ppc_interval(data)
.. minigallery:: plot_ppc_interval
ArviZPythonPlots.plot_ppc_censored — Function
Plot Kaplan-Meier survival curve [1]_ vs predictive draws.
Instead of plotting the raw data observation and predictions, as is common in posterior
predictive checks, this function computes the Kaplan-Meier survival curves for observed
and for predictive data computes survival probabilities limited to a factor of the maximum
observed data to avoid extending the survival curves too far beyond the range of observed data.
Parameters
----------
dt : DataTree
Input data containing the predictive samples and observed data.
Should contain groups specified by `group` and "observed_data",
optionally including a censoring status variable in "constant_data".
This censoring variable should be binary where 1 indicates an event
occurred and 0 indicates censoring.
var_names : str or list of str, optional
One or more variables to be plotted.
filter_vars : {None, "like", "regex"}, optional, default=None
If None (default), 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.
group : str, default "posterior_predictive"
Group to be plotted. Can be "posterior_predictive" or "prior_predictive".
coords : dict, optional
Coordinates to subset the data.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
num_samples : int, optional
Number of samples to plot. Defaults to 100.
extrapolation_factor : float, default 1.2
Factor by which to limit the survival curves beyond the maximum observed time.
Set to None to show the unaffected posterior predictive draws.
plot_collection : PlotCollection, optional
Existing plot collection to add to.
backend : {"matplotlib", "bokeh", "plotly"}, optional
Plotting backend to use.
labeller : labeller, optional
Labeller for plot titles and axes.
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* observed_km -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* predictive -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
**pc_kwargs
Additional arguments passed to PlotCollection.
Returns
-------
PlotCollection
The plot collection containing the survival curve plot.
Examples
--------
Plot Kaplan-Meier curves for posterior predictive checking:
.. plot::
:context: close-figs
>>> from arviz_plots import plot_ppc_censored, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('censored_cats')
>>> plot_ppc_censored(dt)
.. minigallery:: plot_ppc_censored
References
----------
.. [1] Kaplan, E. L., & Meier, P. Nonparametric estimation from incomplete observations.
JASA, 53(282). (1958) https://doi.org/10.1080/01621459.1958.10501452
ArviZPythonPlots.plot_loo_pit — Function
LOO-PIT Δ-ECDF uniformity test.
For a calibrated model the LOO Probability Integral Transform (PIT) values,
$p(\tilde{y}_i \le y_i \mid y_{-i})$, should be uniformly distributed.
Where $y_i$ represents the observed data for index $i$ and $\tilde y_i$ represents
the posterior predictive sample at index $i$. $y_{-i}$ indicates we have left out the
$i$-th observation. LOO-PIT values are computed using the PSIS-LOO-CV method described
in [1]_ and [2]_.
This plot shows the empirical cumulative distribution function (ECDF) of the LOO-PIT values.
To make the plot easier to interpret, we plot the Δ-ECDF, that is, the difference between the
observed ECDF and the expected CDF.
The points that contribute the most to deviations from uniformity are
computed as described in [3]_ and highlighted in the plot.
Alternatively, we can visualize the coverage of the central posterior credible intervals by
setting ``coverage=True``. This allows us to assess whether the credible intervals includes
the observed values. We can obtain the coverage of the central intervals from the LOO-PIT by
replacing the LOO-PIT with two times the absolute difference between the LOO-PIT values and 0.5.
For more details on how to interpret this plot,
see https://arviz-devs.github.io/EABM/Chapters/Prior_posterior_predictive_checks.html#pit-ecdfs.
Parameters
----------
dt : DataTree
Input data
envelope_prob : float, optional
Indicates the probability that should be contained within the envelope.
Defaults to ``rcParams["stats.envelope_prob"]``.
coverage : bool, optional
If True, plot the coverage of the central posterior credible intervals. Defaults to False.
var_names : str or list of str, optional
One or more variables to be plotted. Currently only one variable is supported.
Prefix the variables by ~ when you want to exclude them from the plot.
filter_vars : {None, “like”, “regex”}, optional, default=None
If None (default), 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.
coords : dict, optional
Coordinates to plot.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
CURRENTLY NOT SUPPORTED
method : {"pot_c", "prit_c", "piet_c"}, optional
Method to use for the uniformity test. Defaults to "pot_c".
Check the documentation of :func:`~arviz_plots.plot_ecdf_pit` for
more details.
envelope_prob : float, optional
Indicates the probability threshold to highlight points.
Defaults to ``rcParams["stats.envelope_prob"]``.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals` except for "remove_axis".
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* ecdf_lines -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* credible_interval -> passed to :func:`~arviz_plots.visuals.fill_between_y`
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* remove_axis -> not passed anywhere, can only be a boolean to indicate
whether to call this function. Defaults to ``False`` for plot_loo_pit
stats : mapping, optional
Valid keys are:
* ecdf_pit -> passed to :func:`~xarray.Dataset.azstats.uniformity_test`. Default is
``{"gamma": 0}``.
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.grid`
Returns
-------
PlotCollection
See Also
--------
plot_ppc_pit : Predictive check using PIT Δ-ECDF uniformity test.
plot_loo_interval : Predictive intervals and observed data.
Examples
--------
Plot the ecdf-PIT for the crabs hurdle-negative-binomial dataset.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_loo_pit, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('radon')
>>> plot_loo_pit(dt)
Plot the coverage for the crabs hurdle-negative-binomial dataset.
.. plot::
:context: close-figs
>>> plot_loo_pit(dt, coverage=True)
.. minigallery:: plot_loo_pit
References
----------
.. [1] Vehtari et al. Practical Bayesian model evaluation using leave-one-out cross-validation
and WAIC. Statistics and Computing. 27(5) (2017) https://doi.org/10.1007/s11222-016-9696-4
.. [2] Vehtari et al. Pareto Smoothed Importance Sampling. Journal of Machine Learning
Research, 25(72) (2024) https://jmlr.org/papers/v25/19-556.html
.. [3] Tasso et al. *LOO-PIT predictive model checking* arXiv:2603.02928 (2026).
ArviZPythonPlots.plot_loo_interval — Function
Plot LOO posterior predictive intervals with observed data overlaid.
Displays observed data as a point and LOO predicted data as a point estimate plus two
credible intervals.
Parameters
----------
dt : DataTree
Input data. It should contain the ``posterior_predictive``, the
``log_likelihood`` and ``observed_data`` groups.
var_names : str or list 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.
group : str
Group to be plotted. Defaults to "posterior_predictive".
coords : dict, optional
Coordinates of `var_names` to be plotted.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
point_estimate : {"mean", "median"}, optional
Which point estimate to plot for the predictive distribution.
Defaults to rcParam ``stats.point_estimate``.
ci_probs : (float, float), optional
Indicates the probabilities for the inner (twig) and outer (trunk) credible intervals.
Defaults to ``(0.5, rcParams["stats.ci_prob"])``. It's assumed that
``ci_probs[0] < ci_probs[1]``, otherwise they are sorted.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly", "none"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str or False}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* trunk, twig -> passed to :func:`~arviz_plots.visuals.ci_bound_y`
* observed_markers -> passed to :func:`~arviz_plots.visuals.point_y`
* prediction_markers -> passed to :func:`~arviz_plots.visuals.point_y`
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title` defaults to False
stats : mapping, optional
Valid keys are:
* trunk, twig -> passed to loo_expectations for the trunk and twig intervals, respectively
* point_estimate -> passed to loo_expectations
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.grid`
Returns
-------
PlotCollection
See Also
--------
plot_ppc_interval : Plot prior/posterior predictive intervals and observed data.
plot_ppc_dist : Plot 1D marginals for the posterior/prior predictive and observed data.
plot_ppc_rootogram : Plot ppc rootogram for discrete (count) data
Examples
--------
Plot LOO posterior predictive intervals for the radon dataset, with custom styling.
.. plot::
:context: close-figs
>>> from arviz_base import load_arviz_data
>>> import arviz_plots as azp
>>> azp.style.use("arviz-variat")
>>> data = load_arviz_data("rugby")
>>> pc = azp.plot_loo_interval(data)
.. minigallery:: plot_loo_interval
Prior and likelihood sensitivity checks
ArviZPythonPlots.plot_psense_dist — Function
Plot power scaled posteriors.
The posterior sensitivity is assessed by power-scaling the prior or likelihood and
visualizing the resulting changes, using Pareto-smoothed importance sampling to
avoid refitting as explained in [1]_.
Parameters
----------
dt : DataTree
Input data
var_names : str or list 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”}, optional, default=None
If None (default), 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.
prior_var_names : str, optional
Name of the log-prior variables to include in the power scaling sensitivity diagnostic
likelihood_var_names : str, optional
Name of the log-likelihood variables to include in the power scaling sensitivity diagnostic
prior_coords : dict, optional
Coordinates defining a subset over the group element for which to
compute the log-prior sensitivity diagnostic
likelihood_coords : dict, optional
Coordinates defining a subset over the group element for which to
compute the log-likelihood sensitivity diagnostic
coords : dict, optional
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
alphas : tuple of float
Lower and upper alpha values for power scaling. Defaults to (0.8, 1.25).
kind : {"kde", "hist", "dot", "ecdf"}, optional
How to represent the marginal distribution.
point_estimate : {"mean", "median", "mode"}, optional
Which point estimate to plot. Defaults to rcParam :data:`stats.point_estimate`
ci_kind : {"eti", "hdi"}, optional
Which credible interval to use. Defaults to ``rcParams["stats.ci_kind"]``
ci_prob : float, optional
Indicates the probability that should be contained within the plotted credible interval.
Defaults to ``rcParams["stats.ci_prob"]``
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals` except for "remove_axis"
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* dist -> depending on the value of `kind` passed to:
* "kde" -> passed to :func:`~arviz_plots.visuals.line_xy`
* "ecdf" -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* "hist" -> passed to :func: `~arviz_plots.visuals.step_hist`
* "dot" -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* credible_interval -> passed to :func:`~arviz_plots.visuals.line_x`
* point_estimate -> passed to :func:`~arviz_plots.visuals.scatter_x`
* point_estimate_text -> passed to :func:`~arviz_plots.visuals.point_estimate_text`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* legend -> passed to :class:`arviz_plots.PlotCollection.add_legend`
* remove_axis -> not passed anywhere, can only be ``False`` to skip calling this function
stats : mapping, optional
Valid keys are:
* dist -> passed to kde, ecdf, ...
* credible_interval -> passed to eti or hdi
* point_estimate -> passed to mean, median or mode
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
Examples
--------
Select a single variable and generate a point-interval plot
.. plot::
:context: close-figs
>>> from arviz_plots import plot_psense_dist, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> rugby = load_arviz_data('rugby')
>>> plot_psense_dist(rugby, var_names=["sd_att"], visuals={"dist":False})
.. minigallery:: plot_psense_dist
References
----------
.. [1] Kallioinen et al, *Detecting and diagnosing prior and likelihood sensitivity with
power-scaling*, Stat Comput 34, 57 (2024), https://doi.org/10.1007/s11222-023-10366-5
ArviZPythonPlots.plot_psense_quantities — Function
Plot power scaled posterior quantities.
The posterior quantities are computed by power-scaling the prior or likelihood and
visualizing the resulting changes, using Pareto-smoothed importance sampling to
avoid refitting as explained in [1]_.
Parameters
----------
dt : DataTree
Input data
var_names : str or list 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”}, optional, default=None
If None (default), 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.
prior_var_names : str, optional.
Name of the log-prior variables to include in the power scaling sensitivity diagnostic
likelihood_var_names : str, optional.
Name of the log-likelihood variables to include in the power scaling sensitivity diagnostic
prior_coords : dict, optional.
Coordinates defining a subset over the group element for which to
compute the log-prior sensitivity diagnostic
likelihood_coords : dict, optional
Coordinates defining a subset over the group element for which to
compute the log-likelihood sensitivity diagnostic
coords : dict, optional
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
alphas : tuple of float
Lower and upper alpha values for power scaling. Defaults to (0.8, 1.25).
quantities : list of str
Quantities to plot. Options are 'mean', 'sd', 'median'. For quantiles, use
'0.25', '0.5', etc. Defaults to ['mean', 'sd'].
mcse : bool
Whether to plot the Monte Carlo standard error for each quantity. Defaults to True.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* prior_markers -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* prior_lines -> passed to :func:`~arviz_plots.visuals.line_xy`
* likelihood_markers -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* likelihood_lines -> passed to :func:`~arviz_plots.visuals.line_xy`
* mcse -> passed to :func:`~arviz_plots.visuals.hline`
* ticks -> passed to :func:`~arviz_plots.visuals.set_xticks`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* legend -> passed to :class:`arviz_plots.PlotCollection.add_legend`
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.grid`
Returns
-------
PlotCollection
Examples
--------
Select a single parameter, one of the two likelihoods, and plot the mean, standard deviation,
and 25th percentile.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_psense_quantities, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> rugby = load_arviz_data('rugby')
>>> plot_psense_quantities(rugby,
>>> var_names=["sd_att"],
>>> likelihood_var_names=["home_points"],
>>> quantities=["mean", "sd", "0.25"])
.. minigallery:: plot_psense_quantities
References
----------
.. [1] Kallioinen et al, *Detecting and diagnosing prior and likelihood sensitivity with
power-scaling*, Stat Comput 34, 57 (2024), https://doi.org/10.1007/s11222-023-10366-5
Model comparison
ArviZPythonPlots.plot_compare — Function
Summary plot for model comparison.
Models are compared based on their expected log pointwise predictive density (ELPD).
Or some transformation of it, such as the mean log predictive density (MLPD)
or the geometric mean predictive density (GMPD).
Higher ELPD values indicate better predictive performance.
The ELPD is estimated by Pareto smoothed importance sampling leave-one-out
cross-validation (LOO). Details are presented in [1]_ and [2]_.
The ELPD can only be interpreted in relative terms. But differences in ELPD less than 4
are considered negligible [3]_.
Parameters
----------
cmp_df : pandas.DataFrame
Usually this will be the result of the :func:`arviz_stats.compare` function.
It is assumed that the first row of the DataFrame is the top model and
the DataFrame has at least two columns:
* When ``relative_scale`` is True: one named `elpd_diff`, `mlpd_diff`,
or `gmpd_diff`, the other named `dse`, and the index is the model names.
* When ``relative_scale`` is False: one named `elpd`, `mlpd`, or `gmpd`,
the other named `se`, and the index is the model names.
relative_scale : bool, optional.
If True, the `stats`_diff and dse values are used instead of `stats` and se.
This turns the comparison into a difference from the best model.
Defaults to True.
rotated : bool, optional
If True, the plot is rotated, with models on the y-axis and ELPD on the x-axis.
Defaults to False.
hide_top_model : bool, optional
If True, the top model (first row of `cmp_df`) will not appear as a point with error bars
or in the axis labels. Its performance can still be accessed by the visuals `ref_line`
and/or `ref_band`. Defaults to False.
backend : {"bokeh", "matplotlib", "plotly"}
Select plotting backend. Defaults to rcParams["plot.backend"].
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* point_estimate -> passed to :func:`~arviz_plots.backend.none.scatter`
* error_bar -> passed to :func:`~arviz_plots.backend.none.line`
* ref_line -> passed to :func:`~arviz_plots.backend.none.hline` or
:func:`~arviz_plots.backend.none.vline` depending on the
``rotated`` parameter.
* ref_band -> passed to :func:`~arviz_plots.backend.none.hspan` or
:func:`~arviz_plots.backend.none.vspan` depending on the
``rotated`` parameter. Defaults to ``False``.
* similar_line -> passed to :func:`~arviz_plots.backend.none.hline` or
:func:`~arviz_plots.backend.none.vline` depending on the
``rotated`` parameter. Defaults to ``False``.
* labels -> passed to :func:`~arviz_plots.backend.none.xticks` and
:func:`~arviz_plots.backend.none.yticks`
* title -> passed to :func:`~arviz_plots.backend.none.title`
* ticklabels -> passed to :func:`~arviz_plots.backend.none.yticks`
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection`
Returns
-------
PlotCollection
See Also
--------
:func:`arviz_stats.compare`: Summary plot for model comparison.
:func:`arviz_stats.loo` : Compute the ELPD using Pareto smoothed importance sampling
Leave-one-out cross-validation method.
References
----------
.. [1] Vehtari et al. *Practical Bayesian model evaluation using leave-one-out cross-validation
and WAIC*. Statistics and Computing. 27(5) (2017).
https://doi.org/10.1007/s11222-016-9696-4. arXiv preprint https://arxiv.org/abs/1507.04544.
.. [2] Vehtari et al. *Pareto Smoothed Importance Sampling*.
Journal of Machine Learning Research, 25(72) (2024) https://jmlr.org/papers/v25/19-556.html
arXiv preprint https://arxiv.org/abs/1507.02646
.. [3] Sivula et al. *Uncertainty in Bayesian Leave-One-Out Cross-Validation Based Model
Comparison*. (2025). https://doi.org/10.48550/arXiv.2008.10296
ArviZPythonPlots.plot_khat — Function
Plot Pareto tail indices for diagnosing convergence in PSIS-LOO-CV.
The Generalized Pareto distribution (GPD) is fitted to the largest importance ratios to
diagnose convergence rates. The shape parameter :math:`\hat{k}` estimates the pre-asymptotic
convergence rate based on the fractional number of finite moments. Values :math:`\hat{k} > 0.7`
indicate impractically low convergence rates and unreliable estimates. Details are presented
in [1]_ and [2]_.
Parameters
----------
elpd_data : ELPDData
ELPD data object returned by :func:`arviz_stats.loo` containing Pareto k diagnostics.
threshold : float, optional
Highlight khat values above this threshold with annotations. If None, no points
are highlighted.
hover_format : str, default ``"{index}: {label}"``
Format string for hover annotations. Supports ``{index}``, ``{label}``, and ``{value}``.
legend : bool, optional
Whether to display a legend when color aesthetics are active. If None, a legend is shown
when a color mapping is available.
color : color spec or str, optional
Color for scatter points when no aesthetic mapping supplies one. If the value matches a
dimension name, that dimension is mapped to the color aesthetic.
marker : marker spec or str, optional
Marker style for scatter points when no aesthetic mapping supplies one. If the value
matches a dimension name, that dimension is mapped to the marker aesthetic.
hline_values : sequence of float, optional
Custom horizontal line positions. Defaults to [0.0, 0.7, 1.0].
bin_format : str, default ``"{pct:.1f}%"``
Format string for bin percentages. Supports ``{count}`` and ``{pct}`` placeholders.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
Plotting backend to use. Defaults to ``rcParams["plot.backend"]``.
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence 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:
* khat -> uses all available aesthetic mappings
* threshold_text -> uses no aesthetic mappings
* hover -> uses no aesthetic mappings
* title -> uses no aesthetic mappings
* xlabel -> uses no aesthetic mappings
* ylabel -> uses no aesthetic mappings
* ticks -> uses no aesthetic mappings
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* khat -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* hlines -> passed to :func:`~arviz_plots.visuals.hline`, defaults to False
* bin_text -> passed to :func:`~arviz_plots.visuals.annotate_xy`, defaults to False
* threshold_text -> passed to :func:`~arviz_plots.visuals.annotate_xy`
* hover -> enables interactive hover annotations, defaults to False
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`, defaults to False
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
* legend -> passed to :class:`arviz_plots.PlotCollection.add_legend`
* ticks -> passed to :func:`~arviz_plots.visuals.set_xticks`, defaults to False
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`.
Returns
-------
PlotCollection
Warnings
--------
When using custom markers via the ``visuals`` dict, ensure the marker type is compatible
with your chosen backend. Not all marker types support separate facecolor and edgecolor
across different backends.
Examples
--------
The most basic usage plots the Pareto k values from a LOO-CV computation. Each point
represents one observation, with higher k values indicating less reliable importance
sampling for that observation.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_khat, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> from arviz_stats import loo
>>> dt = load_arviz_data("rugby")
>>> elpd_data = loo(dt, var_name="home_points", pointwise=True)
>>> plot_khat(elpd_data, figure_kwargs={"figsize": (10, 5)})
.. minigallery:: plot_khat
References
----------
.. [1] Vehtari et al. *Practical Bayesian model evaluation using leave-one-out cross-validation
and WAIC*. Statistics and Computing. 27(5) (2017).
https://doi.org/10.1007/s11222-016-9696-4. arXiv preprint https://arxiv.org/abs/1507.04544.
.. [2] Vehtari et al. *Pareto Smoothed Importance Sampling*.
Journal of Machine Learning Research, 25(72) (2024) https://jmlr.org/papers/v25/19-556.html
arXiv preprint https://arxiv.org/abs/1507.02646
ArviZPythonPlots.plot_bf — Function
Bayes Factor for comparing hypothesis of two nested models.
The Bayes factor is estimated by comparing a model (H1) against a model
in which the parameter of interest has been restricted to be a point-null (H0).
This computation assumes H0 is a special case of H1. For more details see
https://arviz-devs.github.io/EABM/Chapters/Model_comparison.html#savagedickey-ratio
Parameters
----------
dt : DataTree
Input data.
var_names : str, optional
Variables for which the Bayes factor will be computed and the prior and
posterior will be plotted.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
ref_val : int, float, or dict, default 0
Reference (point-null) value for Bayes factor estimation.
Can be a single value applied to all variables, or a dict mapping
variable names to values, e.g. ``{"mu": 0, "tau": 0.5}``.
kind : {"kde", "hist", "dot", "ecdf"}, optional
How to represent the marginal density.
Defaults to ``rcParams["plot.density_kind"]``
bf_type : {"BF10", "BF01"}, optional
Whether to annotate the Bayes factor in favor of the alternative (BF10) or the null (BF01).
Defaults to "BF10".
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals`.
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* dist -> depending on the value of `kind` passed to:
* "kde" -> passed to :func:`~arviz_plots.visuals.line_xy`
* "ecdf" -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* "hist" -> passed to :func: `~arviz_plots.visuals.hist`
* ref_line -> passed to :func: `~arviz_plots.visuals.vline`
* ref_value_text -> passed to :func:`~arviz_plots.visuals.annotate_xy`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
stats : mapping, optional
Valid keys are:
* dist -> passed to kde, ecdf, ...
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
Examples
--------
Select one variable.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_bf, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('centered_eight')
>>> plot_bf(dt, var_names="mu", kind="hist")
.. minigallery:: plot_bf
Simulation based calibration
ArviZPythonPlots.plot_ecdf_pit — Function
Plot Δ-ECDF.
Plots the Δ-ECDF, that is the difference between the observed ECDF and the expected CDF.
It assumes the values in the DataTree have already been transformed to PIT values,
as in the case of SBC analysis or values from ``arviz_base.loo_pit``.
Alternatively, we can visualize the coverage of the central posterior credible intervals by
setting ``coverage=True``. This allows us to assess whether the credible intervals includes
the observed values. We can obtain the coverage of the central intervals from the PIT by
replacing the PIT with two times the absolute difference between the PIT values and 0.5.
For more details on how to interpret this plot,
see https://arviz-devs.github.io/EABM/Chapters/Prior_posterior_predictive_checks.html#pit-ecdfs.
Parameters
----------
dt : DataTree
Input data
var_names : str or list of str, optional
One or more variables to be plotted. Currently only one variable is supported.
Prefix the variables by ~ when you want to exclude them from the plot.
filter_vars : {None, “like”, “regex”}, optional, default=None
If None (default), 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.
group : str, optional
Which group to use. Defaults to "prior_sbc".
coords : dict, optional
Coordinates to plot.
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
method : {"pot_c", "prit_c", "piet_c", "envelope"}, optional
Method to use for the uniformity test. See the "Notes" section for the full description of
the different methods available.
envelope_prob : float, optional
If `method` is "envelope", indicates the probability that should be contained within the
envelope, otherwise indicates the probability threshold to highlight points.
Defaults to ``rcParams["stats.envelope_prob"]``.
coverage : bool, optional
Defaults to ``rcParams["stats.envelope_prob"]``.
coverage : bool, optional
If True, plot the coverage of the central posterior credible intervals. Defaults to False.
plot_collection : PlotCollection, optional
backend : {"matplotlib", "bokeh", "plotly"}, optional
labeller : labeller, optional
aes_by_visuals : mapping of {str : sequence of str}, optional
Mapping of visuals to aesthetics that should use their mapping in `plot_collection`
when plotted. Valid keys are the same as for `visuals` except for "remove_axis"
visuals : mapping of {str : mapping or bool}, optional
Valid keys are:
* ecdf_lines -> passed to :func:`~arviz_plots.visuals.ecdf_line`
* credible_interval -> passed to :func:`~arviz_plots.visuals.fill_between_y`,
only when method is "envelope"
* ref_line -> passed to :func:`~arviz_plots.visuals.line_xy`
* suspicious_points -> passed to :func:`~arviz_plots.visuals.scatter_xy`
* p_value_text -> passed to :func:`~arviz_plots.visuals.annotate_xy`
only when method is not "envelope"
* xlabel -> passed to :func:`~arviz_plots.visuals.labelled_x`
* ylabel -> passed to :func:`~arviz_plots.visuals.labelled_y`
* title -> passed to :func:`~arviz_plots.visuals.labelled_title`
* remove_axis -> not passed anywhere, can only be ``False`` to skip calling this function
stats : mapping, optional
Valid keys are:
* ecdf_pit -> passed to :func:`~arviz_stats.ecdf_utils.ecdf_pit`. or
:func:`~xarray.Dataset.azstats.uniformity_test` depending on the value of `method`.
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.wrap`
Returns
-------
PlotCollection
Notes
-----
The following methods are available for testing the uniformity of the PIT values:
* pot_c: Good default choice due to its good power against diverse
type of local departures from the null. Preferred in almost all cases.
* piet_c: Use when you specifically want to evaluate tail deviations.
* prit_c: Mostly compatible with PITs computed as normalized ranks.
Don't use unless you have a specific reason to do so.
* envelope: Legacy method that uses simultaneous confidence bands. It can be used
when you have independent PIT values, as in the case of SBC analysis. The method
is described in method described in [1]_. Notice that pot_c is also valid in those cases.
The methods "pot_c", "piet_c" and "prit_c" compute the points that contribute the most
to deviations from uniformity as described in [2]_.
Examples
--------
Rank plot for the crabs hurdle-negative-binomial dataset.
.. plot::
:context: close-figs
>>> from arviz_plots import plot_ecdf_pit, style
>>> style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> dt = load_arviz_data('sbc')
>>> plot_ecdf_pit(dt)
.. minigallery:: plot_ecdf_pit
References
----------
.. [1] Säilynoja et al. *Graphical test for discrete uniformity and
its applications in goodness-of-fit evaluation and multiple sample comparison*.
Statistics and Computing 32(32). (2022) https://doi.org/10.1007/s11222-022-10090-6
.. [2] Tasso et al. *LOO-PIT predictive model checking* arXiv:2603.02928 (2026).
Combining plots
ArviZPythonPlots.combine_plots — Function
Arrange multiple batteries-included plots in a customizable column or row layout.
Parameters
----------
dt : DataTree of dict of {str : 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.
Note that not all batteries included functions accept dictionary input, so it will
only work when all plotting functions requested in `plots` are compatible with it.
plots : list of tuple of (callable, mapping)
List of all the plotting functions to be combined. Each element in this list
is a tuple with two elements. The first is the function to be called, the second
is a dictionary with any keyword arguments that should be used when calling that function.
var_names : str 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.
group : str, default "posterior"
Group to be plotted.
coords : dict, optional
sample_dims : str or sequence of hashable, optional
Dimensions to reduce unless mapped to an aesthetic.
Defaults to ``rcParams["data.sample_dims"]``
expand : {"column", "row"}, default "column"
How to combine the different plotting functions. If "column", each plotting function
will be added as a new column, if "row" it will be a new row instead.
plot_names : list of str, optional
List of the same length as `plots` with the plot names to use as coordinate values
in the returned :class:`~arviz_plots.PlotCollection`.
backend : {"matplotlib", "bokeh", "plotly"}, optional
Plotting backend to use. Defaults to ``rcParams["plot.backend"]``.
**pc_kwargs
Passed to :class:`arviz_plots.PlotCollection.grid`
Returns
-------
PlotCollection
Examples
--------
Customize the names of the plots in the returned :class:`PlotCollection`
.. plot::
:context: close-figs
>>> import arviz_plots as azp
>>> azp.style.use("arviz-variat")
>>> from arviz_base import load_arviz_data
>>> rugby = load_arviz_data('rugby')
>>> pc = azp.combine_plots(
>>> rugby,
>>> plots=[
>>> (azp.plot_ppc_pit, {}),
>>> (azp.plot_ppc_rootogram, {}),
>>> ],
>>> group="posterior_predictive",
>>> plot_names=["pit", "rootogram"],
>>> )
Now if we inspect the ``pc.viz`` attribute, we can see it has a ``column`` dimension
with the requested coordinate values:
.. plot::
:context: close-figs
>>> pc.viz
.. minigallery:: combine_plots