add examples to customize 2D KDE

[aloctavodia]

Following #1157 this add examples to the docstring of plot_kde and a new example to the gallery.
This also sets fill_last=False as the default, because nobody likes the previous setting :-)

• Follows official PR format
• Code style correct (follows pylint and black guidelines)
• Changes are listed in changelog

[OriolAbril]

LGTM, and I completely agree with the fill_last=False default 🎉

[codecov]

Codecov Report

Merging #1158 into master will decrease coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #1158      +/-   ##
==========================================
- Coverage   93.12%   93.11%   -0.02%     
==========================================
  Files          94       94              
  Lines        9286     9289       +3     
==========================================
+ Hits         8648     8649       +1     
- Misses        638      640       +2     

Impacted Files	Coverage Δ
arviz/plots/kdeplot.py	100.00% <ø> (ø)
arviz/data/converters.py	67.14% <0.00%> (-1.43%)	⬇️
arviz/plots/pairplot.py	92.94% <0.00%> (-0.97%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a341b66...cebebc0. Read the comment docs.

[rpgoldman]

See my feature request #1159 -- we should show usage of the cmap property to control the color scheme. Understanding the effect of cmap turns out to be critical to getting attractive plots.

[aloctavodia]

Two of the new examples show how to pass a cmap argument.

[rpgoldman]

Suggest we briefly explain what the contour_kwargs and contourf_kwargs are for.

I.e., add to the docstring:
"Contour keyword arguments control the formatting of the contour lines." and "Contourf keyword arguments control the filling of contours."

In general -- and I don't think this is ArviZ's fault -- use of these keyword arguments requires a lot of understanding of the underlying implementation. This would be OK if we could leave it to Arviz to choose defaults and be happy with the results, but it seems like we still need a bunch of user input.
Maybe this could be fixed by choosing a good default colormap for the users, so that at least they don't have to understand, instead of leaving it unpredictably to the state of the environment?

[OriolAbril]

Maybe this could be fixed by choosing a good default colormap for the users, so that at least they don't have to understand, instead of leaving it unpredictably to the state of the environment?

We should probably extend ArviZ native style like arviz-darkgrid and so one to be more explicit on the defaults (now they basically are designed to be called on top of matplotlib default and only list the parameters to override), however, for most arguments (at least in matplotlib, which is what I know better) we want the output to depend on matplotlib rcparams. As I see the situation, there are several possibilities, and the least bad is the current setting:

• We do not set the default in ArviZ to use matplotlib defaults. This has the advantage of letting users do plt.rcparams["cmap"] = "plasma" and have plasma be the default in native matplotlib, seaborn, ArviZ... (basically all other libraries on top of matplotlib that do not override the default). The main drawback is dependence on previous state as you said, but extending ArviZ styles should fix this.
• We use an ArviZ rcparam. It is similar to the previous situation, with the main difference that matplotlib defaults no longer affect ArviZ both for the good and for the bad, getting all plots to use the same cmap would require 2 commands (if we use both matplotlib and ArviZ). The main con I see is that if all libraries on top of matplotlib do that, defaults will escalate quickly.
• We set the default in the plotting functions. This hardcodes the default which would then be impossible to override at a general level.

Would the first situation (which is basically the current one) work for your use case if styles were to guarantee reproducibility of results? I hope outlining the alternatives helps in understanding why plots behave like they do.

[aloctavodia]

Using styles you can also do plt.rcparams["cmap"] = "plasma" if you want, styles overwrite the default rcParams and can be overwritten to. Setting values by default in the arviz style do not prevent they to be overwritten, so is not a general solution to the issue Robert is seeing, which is just the combination of two styles.

[rpgoldman]

Thanks! I think that will be helpful.

[aloctavodia]

Thanks @rpgoldman for bringing up the issue.