DOC: update the pandas.DataFrame.plot.density docstring
State: closed

This docstring is quite similar to the one of #20041.

Unfortunately, I was not able to compute a kernel estimate of a
two-dimensional random variable. Hence, the example is more of an
analysis of some independent data series.

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [ ] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [ ] It has been proofread on language by another sprint participant (sort of; it's based on PR20041)

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
################## Docstring (pandas.DataFrame.plot.density)  ##################
################################################################################

Generate Kernel Density Estimate plot using Gaussian kernels.

In statistics, `kernel density estimation`_ (KDE) is a non-parametric
way to estimate the probability density function (PDF) of a random
variable. This function uses Gaussian kernels and includes automatic
bandwith determination.

.. _kernel density estimation:
    https://en.wikipedia.org/wiki/Kernel_density_estimation

Parameters
----------
bw_method : str, scalar or callable, optional
    The method used to calculate the estimator bandwidth. This can be
    'scott', 'silverman', a scalar constant or a callable.
    If None (default), 'scott' is used.
    See :class:`scipy.stats.gaussian_kde` for more information.
ind : NumPy array or integer, optional
    Evaluation points for the estimated PDF. If None (default),
    1000 equally spaced points are used. If `ind` is a NumPy array, the
    KDE is evaluated at the points passed. If `ind` is an integer,
    `ind` number of equally spaced points are used.
**kwds : optional
    Additional keyword arguments are documented in
    :meth:`pandas.DataFrame.plot`.

Returns
-------
axes : matplotlib.AxesSubplot or np.array of them

See Also
--------
scipy.stats.gaussian_kde : Representation of a kernel-density
    estimate using Gaussian kernels. This is the function used
    internally to estimate the PDF.
Series.plot.kde : Generate a KDE plot for a Series.

Examples
--------
Given several Series of points randomly sampled from unknown
distributions, estimate their distribution using KDE with automatic
bandwidth determination and plot the results, evaluating them at
1000 equally spaced points (default):

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame({
    ...     'x': [1, 2, 2.5, 3, 3.5, 4, 5],
    ...     'y': [4, 4, 4.5, 5, 5.5, 6, 6],
    ... })
    >>> ax = df.plot.kde()

A scalar bandwidth can be specified. Using a small bandwidth value can
lead to overfitting, while using a large bandwidth value may result
in underfitting:

.. plot::
    :context: close-figs

    >>> ax = df.plot.kde(bw_method=0.3)

.. plot::
    :context: close-figs

    >>> ax = df.plot.kde(bw_method=3)

Finally, the `ind` parameter determines the evaluation points for the
plot of the estimated PDF:

.. plot::
    :context: close-figs

    >>> ax = df.plot.kde(ind=[1, 2, 3, 4, 5, 6])

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'kwds'} not documented
		Unknown parameters {'**kwds'}
```

I left the error because David and Israel mentioned doing it either way on Gitter ..

Labels:
name: Docs
name: Visualization
description: plotting

Comments:
Damn, we again have the problem of miscommunication that this one was already take one of the previous days: https://github.com/pandas-dev/pandas/pull/20041 
Sorry about that!

cc @dukebody it would be good if one of both of you can combine both PRs and take the best bits of both PRs
If either of you are comfortable with git, you should be able to cherry pick the other's commit so you'll both show up as authors.

LMK if you need help with the git stuff.
@jorisvandenbossche and @TomAugspurger thanks for the quick responses! I noticed the other PR during the sprint, but that one improved the function of Series and not DataFrame. I'm not that comfortable in git, I'd appreciate any help. What about the requested changes in the other PR?
Hmm, OK, didn't see it was DataFrame vs Series. 
We should probably share the docstrings somehow, but let's do that in a follow-up issue. Can you for now see if can 'steal' ideas of the other one?
I agree; I had the same idea with sharing the docstrings between DataFrames and Series. Most DataFrame plotting functions just seem to "pass the call" to the Series it's containing.

What do you mean by "steal ideas of the other one"? I basically copied the Series docstring, included all (but `See Also`) requested changes and extended the example Series to 2-column DataFrames.
Ah, then you already 'stole' the ideas :-) 
No, I assumed you wrote it completely independent, and then it would have been nice to combine the different enhancements in both PRs here. But that already happened then
So I think the main difference between the frame vs series methods is that the frame version has `x, y` as keywords?
~~this dupes #20041~~
@jreback see discussion we are having. It's not an exact duplciate, as it is frame vs series. But I agree the docstring is certainly duplicative and can be shared. 
We only need to figure out how to exactly do that.
@jorisvandenbossche yep, just noticed. nvm.
OK, I merged the other PR. 
@jonas-schulze the comments that were left there (and the ones you added yourself), can you address them here? 
You will need to fetch upstream, merge upstream/master and fix the conflicts though

I included the changes and updated the very first comment to include the new output of the validation script.
What do you think of my concern with the docstring / the DataFrame density function?
```
Unfortunately, I was not able to compute a kernel estimate of a
two-dimensional random variable. Hence, the example is more of an
analysis of some independent data series.
```
Updates to the existing docstring look good!

What is the difference now exactly between both docstrings? Only the examples section?
Unless I missed something, that's the only difference.
Can you then maybe pull out the common part into a variable, and use `@Appender(_kde_docstring % _kde_series_example)` to add it to both functions?

(if that was very cryptic, say so :-))
I just noticed two more differences:

1. the `**kwds` arguments include their own class (Series or DataFrame)
2. the `See Also` sections references the other class (DataFrame or Series)

So there would be some more processing required than just appending the examples .. shall I still proceed? I think it might be better to come up with a more general solution to this phenomenon of "sibling functions" between Series and DataFrame. It should then be applied to all the other plotting functions as well once their PRs got merged, hence I would do it in a later PR.
Hello @jonas-schulze! Thanks for updating the PR.



Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on March 11, 2018 at 19:25 Hours UTC
The new commit for the unified docstrings introduces two new errors in the validation script:
```
Errors found:
	Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
	Use only one blank line to separate sections or paragraphs
```
I have no idea how to fix them .. can you help me please?
@jonas-schulze Great work on combining both docstrings and addressing the comments on my PR! LGTM.

Regarding the issue raised by the validator, can you check the output of the compiled docstring when running it in both methods? It's probably a silly formatting issue when using the Appender.
Adding a `.strip()` to the dictionaries fixes the validation errors. In order to keep the amount of changes low, and because the strings would look very weird otherwise, I added 1 level of indent to the common docstring above `class KdePlot`.
Off topic: why doesn't pandas have a panda as its logo/mascot?
Thanks!