Skip to content

DOC: document optional arguments on plot submethods #27381

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

Closed
wants to merge 2 commits into from
Closed

DOC: document optional arguments on plot submethods #27381

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
572751a
11042 refactor(plot sub-methods): signatures
Jul 13, 2019
002fc51
11042 refactor(plot sub-methods): req. changes 2
Nov 19, 2019
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
145 changes: 103 additions & 42 deletions pandas/plotting/_core.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
import importlib
import warnings

import numpy as np

from pandas._config import get_option

from pandas.util._decorators import Appender, Substitution
Expand All @@ -10,6 +12,22 @@

from pandas.core.base import PandasObject

_shared_docs = """figsize : a tuple (width, height) in inches
subplots : boolean, default False
Make separate subplots for each column
sharex : boolean, default True if ax is None else False
In case subplots=True, share x axis and set some x axis labels to invisible;
defaults to True if ax is None otherwise False if an ax is passed in;
Be aware, that passing in both an ax and sharex=True will alter all x axis
labels for all axis in a figure!
sharey : boolean, default False
In case subplots=True, share y axis and set some y axis labels to subplots
layout : tuple (optional)
(rows, columns) for the layout of subplots
title : string or list
Title to use for the plot. If a string is passed, print the string at the
top of the figure. If a list is passed and subplots is True, print each item
in the list above the corresponding subplot."""

def hist_series(
self,
Expand Down Expand Up @@ -852,8 +870,7 @@ def __call__(self, *args, **kwargs):

return plot_backend.plot(data, kind=kind, **kwargs)

def line(self, x=None, y=None, **kwargs):
"""
_line_docs = """
Plot Series or DataFrame as lines.

This function is useful to plot lines using DataFrame's values
Expand All @@ -869,6 +886,7 @@ def line(self, x=None, y=None, **kwargs):
The values to be plotted.
Either the location or the label of the columns to be used.
By default, it will use the remaining DataFrame numeric columns.
%s
**kwargs
Keyword arguments to pass on to :meth:`DataFrame.plot`.

Expand Down Expand Up @@ -919,10 +937,14 @@ def line(self, x=None, y=None, **kwargs):

>>> lines = df.plot.line(x='pig', y='horse')
"""
return self(kind="line", x=x, y=y, **kwargs)

def bar(self, x=None, y=None, **kwargs):
"""
@Appender(_line_docs % _shared_docs)
Copy link
Member

Choose a reason for hiding this comment

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

Rather than putting this all in Appender you can use Appender with Substitution decorators. Check pandas.core.frame for pre-existing examples

Copy link
Author

Choose a reason for hiding this comment

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

Just to be sure: do you mean to replace

@Appender(_line_docs % _shared_docs)

by

@Substitution(_shared_docs)
@Appender(_line_docs)

???

For me this is just more decorators making the code more complex, but not really nicer. Even in pandas.core.frame there are counter examples:

@Appender(_shared_docs["align"] % _shared_doc_kwargs)

So, do we really want that many decorators?

Copy link
Member

Choose a reason for hiding this comment

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

OK sure. Looks like some CI failures can you merge master and we can get this one in

def line(self, x=None, y=None, *, figsize=None, subplots=False, sharex=None,
sharey=False, layout=None, title=None, **kwargs):
return self(kind="line", x=x, y=y, figsize=figsize, subplots=subplots,
sharex=sharex, sharey=sharey, layout=layout, title=title, **kwargs)

_bar_docs = """
Vertical bar plot.

A bar plot is a plot that presents categorical data with
Expand All @@ -939,6 +961,7 @@ def bar(self, x=None, y=None, **kwargs):
y : label or position, optional
Allows plotting of one column versus another. If not specified,
all numerical columns are used.
%s
**kwargs
Additional keyword arguments are documented in
:meth:`DataFrame.plot`.
Expand Down Expand Up @@ -1004,10 +1027,14 @@ def bar(self, x=None, y=None, **kwargs):

>>> ax = df.plot.bar(x='lifespan', rot=0)
"""
return self(kind="bar", x=x, y=y, **kwargs)

def barh(self, x=None, y=None, **kwargs):
"""
@Appender(_bar_docs % _shared_docs)
def bar(self, x=None, y=None, *, figsize=None, subplots=False, sharex=None,
sharey=False, layout=None, title=None, **kwargs):
return self(kind="bar", x=x, y=y, figsize=figsize, subplots=subplots,
sharex=sharex, sharey=sharey, layout=layout, title=title, **kwargs)

_barh_docs = """
Make a horizontal bar plot.

A horizontal bar plot is a plot that presents quantitative data with
Expand All @@ -1022,6 +1049,7 @@ def barh(self, x=None, y=None, **kwargs):
Column to be used for categories.
y : label or position, default All numeric columns in dataframe
Columns to be plotted from the DataFrame.
%s
**kwargs
Keyword arguments to pass on to :meth:`DataFrame.plot`.

Expand Down Expand Up @@ -1083,11 +1111,15 @@ def barh(self, x=None, y=None, **kwargs):
>>> df = pd.DataFrame({'speed': speed,
... 'lifespan': lifespan}, index=index)
>>> ax = df.plot.barh(x='lifespan')
"""
return self(kind="barh", x=x, y=y, **kwargs)
"""

@Appender(_barh_docs % _shared_docs)
def barh(self, x=None, y=None, *, figsize=None, subplots=False, sharex=None,
sharey=False, layout=None, title=None, **kwargs):
return self(kind="barh", x=x, y=y, figsize=figsize, subplots=subplots,
sharex=sharex, sharey=sharey, layout=layout, title=title, **kwargs)

def box(self, by=None, **kwargs):
r"""
_box_docs = r"""
Make a box plot of the DataFrame columns.

A box plot is a method for graphically depicting groups of numerical
Expand All @@ -1108,6 +1140,7 @@ def box(self, by=None, **kwargs):
----------
by : str or sequence
Column in the DataFrame to group by.
%s
**kwargs
Additional keywords are documented in
:meth:`DataFrame.plot`.
Expand All @@ -1134,10 +1167,14 @@ def box(self, by=None, **kwargs):
>>> df = pd.DataFrame(data, columns=list('ABCD'))
>>> ax = df.plot.box()
"""
return self(kind="box", by=by, **kwargs)

def hist(self, by=None, bins=10, **kwargs):
"""
@Appender(_box_docs % _shared_docs)
def box(self, by=None, *, figsize=None, subplots=False, sharex=None, sharey=False,
layout=None, title=None, **kwargs):
return self(kind="box", by=by, figsize=figsize, subplots=subplots,
sharex=sharex, sharey=sharey, layout=layout, title=title, **kwargs)

_hist_docs = """
Draw one histogram of the DataFrame's columns.

A histogram is a representation of the distribution of data.
Expand All @@ -1151,6 +1188,7 @@ def hist(self, by=None, bins=10, **kwargs):
Column in the DataFrame to group by.
bins : int, default 10
Number of histogram bins to be used.
%s
**kwargs
Additional keyword arguments are documented in
:meth:`DataFrame.plot`.
Expand Down Expand Up @@ -1181,10 +1219,13 @@ def hist(self, by=None, bins=10, **kwargs):
>>> df['two'] = df['one'] + np.random.randint(1, 7, 6000)
>>> ax = df.plot.hist(bins=12, alpha=0.5)
"""
return self(kind="hist", by=by, bins=bins, **kwargs)

def kde(self, bw_method=None, ind=None, **kwargs):
"""
@Appender(_hist_docs % _shared_docs)
def hist(self, by=None, bins=10, *, figsize=None, subplots=False, sharex=None,
sharey=False, layout=None, title=None, **kwargs):
return self(kind="hist", by=by, bins=bins, figsize=figsize, subplots=subplots,
sharex=sharex, sharey=sharey, layout=layout, title=title, **kwargs)
_kde_docs = """
Generate Kernel Density Estimate plot using Gaussian kernels.

In statistics, `kernel density estimation`_ (KDE) is a non-parametric
Expand All @@ -1207,9 +1248,10 @@ def kde(self, bw_method=None, ind=None, **kwargs):
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.
%s
**kwargs
Additional keyword arguments are documented in
:meth:`pandas.%(this-datatype)s.plot`.
:meth:`pandas.%%(this-datatype)s.plot`.

Returns
-------
Expand Down Expand Up @@ -1289,12 +1331,17 @@ def kde(self, bw_method=None, ind=None, **kwargs):

>>> ax = df.plot.kde(ind=[1, 2, 3, 4, 5, 6])
"""
return self(kind="kde", bw_method=bw_method, ind=ind, **kwargs)

@Appender(_kde_docs % _shared_docs)
def kde(self, bw_method=None, ind=None, *, figsize=None, subplots=False, sharex=None,
sharey=False, layout=None, title=None, **kwargs):
return self(kind="kde", bw_method=bw_method, ind=ind, figsize=figsize,
subplots=subplots, sharex=sharex, sharey=sharey, layout=layout,
**kwargs)

density = kde

def area(self, x=None, y=None, **kwargs):
"""
_area_docs = """
Draw a stacked area plot.

An area plot displays quantitative data visually.
Expand All @@ -1309,6 +1356,7 @@ def area(self, x=None, y=None, **kwargs):
stacked : bool, default True
Area plots are stacked by default. Set to False to create a
unstacked plot.
%s
**kwargs
Additional keyword arguments are documented in
:meth:`DataFrame.plot`.
Expand Down Expand Up @@ -1364,10 +1412,14 @@ def area(self, x=None, y=None, **kwargs):
... })
>>> ax = df.plot.area(x='day')
"""
return self(kind="area", x=x, y=y, **kwargs)

def pie(self, **kwargs):
"""
@Appender(_area_docs % _shared_docs)
def area(self, x=None, y=None, *, figsize=None, subplots=False, sharex=None,
sharey=False, layout=None, title=None, **kwargs):
return self(kind="area", x=x, y=y, figsize=figsize, subplots=subplots,
sharex=sharex, sharey=sharey, layout=layout, title=title, **kwargs)

_pie_docs = """
Generate a pie plot.

A pie plot is a proportional representation of the numerical data in a
Expand All @@ -1381,6 +1433,7 @@ def pie(self, **kwargs):
y : int or label, optional
Label or position of the column to plot.
If not provided, ``subplots=True`` argument must be passed.
%s
**kwargs
Keyword arguments to pass on to :meth:`DataFrame.plot`.

Expand Down Expand Up @@ -1413,16 +1466,16 @@ def pie(self, **kwargs):

>>> plot = df.plot.pie(subplots=True, figsize=(6, 3))
"""
if (
isinstance(self._parent, ABCDataFrame)
and kwargs.get("y", None) is None
and not kwargs.get("subplots", False)
):

@Appender(_pie_docs % _shared_docs)
def pie(self, y=None, *, figsize=None, subplots=False, sharex=None,
sharey=False, layout=None, title=None, **kwargs):
if isinstance(self._parent, ABCDataFrame) and y is None and not subplots:
raise ValueError("pie requires either y column or 'subplots=True'")
return self(kind="pie", **kwargs)
return self(kind="pie", y=y, figsize=figsize, subplots=subplots, sharex=sharex,
sharey=sharey, layout=layout, title=title, **kwargs)

def scatter(self, x, y, s=None, c=None, **kwargs):
"""
_scatter_docs = """
Create a scatter plot with varying marker point size and color.

The coordinates of each point are defined by two dataframe columns and
Expand Down Expand Up @@ -1462,7 +1515,7 @@ def scatter(self, x, y, s=None, c=None, **kwargs):

- A column name or position whose values will be used to color the
marker points according to a colormap.

%s
**kwargs
Keyword arguments to pass on to :meth:`DataFrame.plot`.

Expand Down Expand Up @@ -1500,10 +1553,15 @@ def scatter(self, x, y, s=None, c=None, **kwargs):
... c='species',
... colormap='viridis')
"""
return self(kind="scatter", x=x, y=y, s=s, c=c, **kwargs)

def hexbin(self, x, y, C=None, reduce_C_function=None, gridsize=None, **kwargs):
"""
@Appender(_scatter_docs % _shared_docs)
def scatter(self, x, y, s=None, c=None, *, figsize=None, subplots=False, sharex=None,
sharey=False, layout=None, title=None, **kwargs):
return self(kind="scatter", x=x, y=y, s=s, c=c, figsize=figsize,
subplots=subplots, sharex=sharex, sharey=sharey, layout=layout,
title=title, **kwargs)

_hexbin_docs = """
Generate a hexagonal binning plot.

Generate a hexagonal binning plot of `x` versus `y`. If `C` is `None`
Expand Down Expand Up @@ -1535,6 +1593,7 @@ def hexbin(self, x, y, C=None, reduce_C_function=None, gridsize=None, **kwargs):
Alternatively, gridsize can be a tuple with two elements
specifying the number of hexagons in the x-direction and the
y-direction.
%s
**kwargs
Additional keyword arguments are documented in
:meth:`DataFrame.plot`.
Expand Down Expand Up @@ -1584,12 +1643,14 @@ def hexbin(self, x, y, C=None, reduce_C_function=None, gridsize=None, **kwargs):
... gridsize=10,
... cmap="viridis")
"""
if reduce_C_function is not None:
kwargs["reduce_C_function"] = reduce_C_function
if gridsize is not None:
kwargs["gridsize"] = gridsize

return self(kind="hexbin", x=x, y=y, C=C, **kwargs)
@Appender(_hexbin_docs % _shared_docs)
def hexbin(self, x, y, C=None, reduce_C_function=np.mean, gridsize=100, *,
figsize=None, subplots=False, sharex=None, sharey=False, layout=None,
title=None, **kwargs):
return self(kind="hexbin", x=x, y=y, C=C, reduce_C_function=reduce_C_function,
gridsize=gridsize, figsize=figsize, subplots=subplots,
sharex=sharex, sharey=sharey, layout=layout, title=title, **kwargs)


_backends = {}
Expand Down