Skip to content

DOC: update the pandas.DataFrame.plot.pie docstring #20133

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 17, 2018
Merged

DOC: update the pandas.DataFrame.plot.pie docstring #20133

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ad5fb29
DOC: update the pandas.DataFrame.plot.pie docstring
Mar 10, 2018
b7c98bb
Updated [ci skip]
TomAugspurger Mar 16, 2018
c49fbb3
Merge remote-tracking branch 'upstream/master' into dim1tri-master
TomAugspurger Mar 16, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 29 additions & 5 deletions pandas/plotting/_core.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2835,18 +2835,42 @@ def area(self, x=None, y=None, **kwds):

def pie(self, y=None, **kwds):
"""
Pie chart
Generate a pie plot.

A pie plot is a representation of the distribution of numerical data
in a DataFrame column. This function wraps the `matplotlib.pyplot.pie`
function for specified column. If no column reference is passed and
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for the specified column

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

refer to 'y' here (its the column reference)

``subplots`` argument is set to ``True``, an np.array of plots for
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you can use single backticks for 'subplots' (because it is a reference to a parameter)

all DataFrame columns will be returned.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for all the DataFrame columns


Parameters
----------
y : label or position, optional
Column to plot.
`**kwds` : optional
y : str or int, optional
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a bit a corner case as well, but in another PR we decide to keep the 'label', as 'str' can actually be too strict on the column name (column names can be other things as strings) ..

Label or position of the column to plot.
If not provided, ``subplots=True`` argument must be passed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really? What happens if we don't pass subplots=True and we don't pass a y argument? Does it raise an error? What does the subplots=True argument change?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. This error is raised:
ValueError: pie requires either y column or 'subplots=True'
with subplots=True, pie() returns an array of plots for all columns

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Improvement proposal: If not provided, the ``subplots=True`` argument must be passed. In this case, a subplot will be created for every column of the DataFrame.

**kwds : optional
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no ** on kwds

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jreback there is a huge confusion here. @datapythonista said we DO want ** on kwds and they are modifying the validation script to accept it. Now you say we don't want it. Can we make a decision about this?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jreback we decided to keep them

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jreback I thought the consensus was to have them. We've got a bug in the script that was validating the opposite, which created some confusion, but in the documentation we've got that they should have the ** in the name.

If there is no final decision, I'd accept both. I think it should be quite easy to use validate_docstrings.py to detect all the ones that have, or not have them. And we can quickly change all them later on.

Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`.

Returns
-------
axes : matplotlib.AxesSubplot or np.array of them
axes : matplotlib.AxesSubplot or np.array of them.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you explain here when an array is returned?


See Also
--------
:meth:`pandas.Series.plot.pie` : Generate a pie plot for a Series.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can leave out the :meth:` part here (the link is automatically made by numpydoc

I would also add the see also to matplotlib.pyplot.pie


Examples
--------
In the example below we have a DataFrame with the information about
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps a matter of style, but I'd say:

Given a DataFrame with information about some planets mass and radius, create a pie plot of their masses:

Because the fact that it is an example can be determined from the section it is in, and the fact that we pass the 'mass' column to the pie method can be seen in the code itself.

What about another example without specifying the y argument?

planet's mass and radius. We pass the the 'mass' column to the
pie function to get a pie plot.

.. plot::
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add some text above explaining what is the example about in plain English? Also, perhaps you want to create different plots for different y values to show how the plot changes when changing the y argument.

:context: close-figs

>>> df = pd.DataFrame({'mass': [0.330, 4.87 , 5.97],
... 'radius': [2439.7, 6051.8, 6378.1]})
>>> plot = df.plot.pie(y='mass', labels=['Mercury', 'Venus', 'Earth'])
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe also add an example with the subplots argument?

"""
return self(kind='pie', y=y, **kwds)

Expand Down