add examples

CHANGELOG.md

@@ -3,7 +3,8 @@
 ## v0.x.x Unreleased
 
 ### New features
-* loo-pit plot. The kde is computed over the data interval (this could be shorter than [0, 1]). The hdi is computed analitically (#1215) 
+* loo-pit plot. The kde is computed over the data interval (this could be shorter than [0, 1]). The hdi is computed analitically (#1215)
+* plot_bpv. A new plot intented to plot Bayesian p-values (#1222)
 
 ### Maintenance and fixes
 

arviz/plots/bpvplot.py

@@ -18,11 +18,11 @@
 
 def plot_bpv(
     data,
-    kind="kde",
+    kind="u_value",
     t_stat="median",
     bpv=True,
     mean=True,
-    reference=None,
+    reference="samples",
     n_ref=100,
     hdi_prob=0.94,
     color="C0",
@@ -128,6 +128,26 @@ def plot_bpv(
     Returns
     -------
     axes: matplotlib axes or bokeh figures
+
+    Examples
+    --------
+    Plot Bayesian p_values.
+
+    .. plot::
+        :context: close-figs
+
+        >>> import arviz as az
+        >>> data = az.load_arviz_data("regression1d")
+        >>> az.plot_bpv(data, kind="p_value")
+
+    Plot custom t statistic comparison.
+
+    .. plot::
+        :context: close-figs
+
+        >>> import arviz as az
+        >>> data = az.load_arviz_data("regression1d")
+        >>> az.plot_bpv(data, kind="t_stat", t_stat=lambda x:np.percentile(x, q=50, axis=-1))
     """
     if group not in ("posterior", "prior"):
         raise TypeError("`group` argument must be either `posterior` or `prior`")
@@ -139,8 +159,11 @@ def plot_bpv(
     if kind.lower() not in ("t_stat", "u_value", "p_value"):
         raise TypeError("`kind` argument must be either `t_stat`, `u_value`, or `p_value`")
 
-    if reference.lower() not in ("analytical", "samples", None):
-        raise TypeError("`reference` argument must be either `analytical`, `samples`, or `None`")
+    if reference is not None:
+        if reference.lower() not in ("analytical", "samples"):
+            raise TypeError(
+                "`reference` argument must be either `analytical`, `samples`, or `None`"
+            )
 
     if hdi_prob is None:
         hdi_prob = rcParams["stats.hdi_prob"]

arviz/plots/plot_utils.py

@@ -663,6 +663,7 @@ def matplotlib_kwarg_dealiaser(args, kind, backend="matplotlib"):
         "plot": mpl.lines.Line2D,
         "hist": mpl.patches.Patch,
         "hexbin": mpl.collections.PolyCollection,
+        "fill_between": mpl.collections.PolyCollection,
         "hlines": mpl.collections.LineCollection,
         "text": mpl.text.Text,
         "contour": mpl.contour.ContourSet,

examples/bokeh/bokeh_plot_bpv.py

@@ -0,0 +1,10 @@
+"""
+Bayesian p-value Posterior plot
+===============================
+
+_thumb: .6, .5
+"""
+import arviz as az
+
+data = az.load_arviz_data("regression1d")
+az.plot_bpv(data, backend="bokeh")

examples/bokeh/bokeh_plot_bpv_tstat.py

@@ -0,0 +1,10 @@
+"""
+Bayesian p-value Posterior plot
+===============================
+
+_thumb: .6, .5
+"""
+import arviz as az
+
+data = az.load_arviz_data("regression1d")
+az.plot_bpv(data, kind="t_stat", t_stat="0.5", backend="bokeh")

examples/matplotlib/mpl_plot_bpv.py

@@ -0,0 +1,15 @@
+"""
+Bayesian p-value Posterior plot
+===============================
+
+_thumb: .6, .5
+"""
+import matplotlib.pyplot as plt
+import arviz as az
+
+az.style.use("arviz-darkgrid")
+
+data = az.load_arviz_data("regression1d")
+az.plot_bpv(data)
+
+plt.show()

examples/matplotlib/mpl_plot_bpv_tstat.py

@@ -0,0 +1,15 @@
+"""
+Bayesian p-value Posterior plot
+===============================
+
+_thumb: .6, .5
+"""
+import matplotlib.pyplot as plt
+import arviz as az
+
+az.style.use("arviz-darkgrid")
+
+data = az.load_arviz_data("regression1d")
+az.plot_bpv(data, kind="t_stat", t_stat="0.5")
+
+plt.show()