add examples to customize 2D KDE (#1158)

* add examples to customize 2D KDE

* blackify gallery example

* update changelog

* briefly explain contour_kwargs and contourf_kwargs

CHANGELOG.md

@@ -15,6 +15,7 @@
 * Add out-of-sample groups (`predictions` and `predictions_constant_data`) and `constant_data` group to pyro and numpyro translation (#1090, #1125)
 * Add `num_chains` and `pred_dims` arguments to from_pyro and from_numpyro (#1090, #1125)
 * Integrate jointplot into pairplot, add point-estimate and overlay of plot kinds (#1079)
+
 ### Maintenance and fixes
 * Fixed behaviour of `credible_interval=None` in `plot_posterior` (#1115)
 * Fixed hist kind of `plot_dist` with multidimensional input (#1115)
@@ -26,6 +27,7 @@
 * Rank plot: rename `axes` argument to `ax` (#1144)
 * Added a warning specifying log scale is now the default in compare/loo/waic functions ([#1150](https://github.com/arviz-devs/arviz/pull/1150))
 * Fixed bug in `plot_posterior` with rcParam "plot.matplotlib.show" = True (#1151)
+* Set `fill_last` argument of `plot_kde` to False by default (#1158)
 
 ### Deprecation
 
@@ -34,6 +36,7 @@
 * Image thumbs generation updated to be Bokeh 2 compatible (#1116)
 * Add new examples for `plot_pair` (#1110)
 * Add examples for `psislw` and `r2_score` (#1129)
+* Add more examples on 2D kde customization (#1158)
 
 ## v0.7.0 (2020 Mar 2)
 

arviz/plots/kdeplot.py

@@ -18,7 +18,7 @@ def plot_kde(
     quantiles=None,
     rotated=False,
     contour=True,
-    fill_last=True,
+    fill_last=False,
     textsize=None,
     plot_kwargs=None,
     fill_kwargs=None,
@@ -61,7 +61,7 @@ def plot_kde(
     contour : bool
         If True plot the 2D KDE using contours, otherwise plot a smooth 2D KDE. Defaults to True.
     fill_last : bool
-        If True fill the last contour of the 2D KDE plot. Defaults to True.
+        If True fill the last contour of the 2D KDE plot. Defaults to False.
     textsize: float
         Text size scaling factor for labels, titles and lines. If None it will be autoscaled based
         on figsize. Not implemented for bokeh backend.
@@ -75,9 +75,9 @@ def plot_kde(
         Use `space` keyword (float) to control the position of the rugplot. The larger this number
         the lower the rugplot.
     contour_kwargs : dict
-        Keywords passed to ax.contour. Ignored for 1D KDE.
+        Keywords passed to ax.contour to draw contour lines. Ignored for 1D KDE.
     contourf_kwargs : dict
-        Keywords passed to ax.contourf. Ignored for 1D KDE.
+        Keywords passed to ax.contourf to draw filled contours. Ignored for 1D KDE.
     pcolormesh_kwargs : dict
         Keywords passed to ax.pcolormesh. Ignored for 1D KDE.
     ax: axes, optional
@@ -111,6 +111,7 @@ def plot_kde(
         >>> import arviz as az
         >>> non_centered = az.load_arviz_data('non_centered_eight')
         >>> mu_posterior = np.concatenate(non_centered.posterior["mu"].values)
+        >>> tau_posterior = np.concatenate(non_centered.posterior["tau"].values)
         >>> az.plot_kde(mu_posterior)
 
 
@@ -144,15 +145,26 @@ def plot_kde(
     .. plot::
         :context: close-figs
 
-        >>> tau_posterior = np.concatenate(non_centered.posterior["tau"].values)
         >>> az.plot_kde(mu_posterior, values2=tau_posterior)
 
-    Remove fill for last contour in 2d KDE
+
+    Plot 2d contour KDE, without filling and countour lines using viridis cmap
+
+    .. plot::
+        :context: close-figs
+
+        >>> az.plot_kde(mu_posterior, values2=tau_posterior,
+        ...             contour_kwargs={"colors":None, "cmap":plt.cm.viridis},
+        ...             contourf_kwargs={"alpha":0});
+
+    Plot 2d contour KDE, set the number of levels to 3.
 
     .. plot::
         :context: close-figs
 
-        >>> az.plot_kde(mu_posterior, values2=tau_posterior, fill_last=False)
+        >>> az.plot_kde(mu_posterior, values2=tau_posterior,
+        ...             contour_kwargs={"levels":3}
+        ...             contourf_kwargs={"levels":3};
 
     Plot 2d smooth KDE
 

examples/matplotlib/mpl_plot_kde_2d_bis.py

@@ -0,0 +1,20 @@
+"""
+2d KDE
+======
+
+_thumb: .1, .8
+"""
+import matplotlib.pyplot as plt
+import numpy as np
+import arviz as az
+
+az.style.use("arviz-darkgrid")
+
+az.plot_kde(
+    np.random.beta(2, 5, size=100),
+    np.random.beta(2, 5, size=100),
+    contour_kwargs={"colors": None, "cmap": plt.cm.viridis, "levels": 30},
+    contourf_kwargs={"alpha": 0.5, "levels": 30},
+)
+
+plt.show()