From 34adc6c07f1b01e0274805bc7d3ac2f995ab28a7 Mon Sep 17 00:00:00 2001 From: "Hancar, Pavel" Date: Sat, 13 Jul 2019 17:29:42 +0200 Subject: [PATCH] 11042 refactor(plot sub-methods): signatures --- pandas/plotting/_core.py | 157 +++++++++++++++++++++++++++------------ 1 file changed, 111 insertions(+), 46 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index d3c9e8ccfa51ca..b0c4136288e754 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -18,6 +18,24 @@ except ImportError: pass +_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, @@ -588,7 +606,7 @@ class PlotAccessor(PandasObject): labels with "(right)" in the legend include_bool : bool, default is False If True, boolean values can be plotted. - `**kwds` : keywords + `**kwargs` : keywords Options to pass to matplotlib plotting method. Returns @@ -795,8 +813,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 @@ -812,7 +829,8 @@ 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. - **kwds + %s + **kwargs Keyword arguments to pass on to :meth:`DataFrame.plot`. Returns @@ -862,9 +880,15 @@ 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) + 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) + + def bar(self, x=None, y=None, figsize=None, subplots=False, sharex=None, + sharey=False, layout=None, title=None, **kwargs): """ Vertical bar plot. @@ -882,7 +906,8 @@ 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. - **kwds + %s + **kwargs Additional keyword arguments are documented in :meth:`DataFrame.plot`. @@ -947,10 +972,10 @@ 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) + return self(kind="bar", x=x, y=y, figsize=figsize, subplots=subplots, + sharex=sharex, sharey=sharey, layout=layout, title=title, **kwargs) - def barh(self, x=None, y=None, **kwargs): - """ + _barh_docs = """ Make a horizontal bar plot. A horizontal bar plot is a plot that presents quantitative data with @@ -965,7 +990,8 @@ 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. - **kwds + %s + **kwargs Keyword arguments to pass on to :meth:`DataFrame.plot`. Returns @@ -1026,11 +1052,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) + """ - def box(self, by=None, **kwargs): - r""" + @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) + + _box_docs = r""" Make a box plot of the DataFrame columns. A box plot is a method for graphically depicting groups of numerical @@ -1051,7 +1081,8 @@ def box(self, by=None, **kwargs): ---------- by : str or sequence Column in the DataFrame to group by. - **kwds : optional + %s + **kwargs : optional Additional keywords are documented in :meth:`DataFrame.plot`. @@ -1077,10 +1108,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. @@ -1094,7 +1129,8 @@ 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. - **kwds + %s + **kwargs Additional keyword arguments are documented in :meth:`DataFrame.plot`. @@ -1124,10 +1160,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 @@ -1150,7 +1189,8 @@ 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. - **kwds : optional + %s + **kwargs : optional Additional keyword arguments are documented in :meth:`pandas.%(this-datatype)s.plot`. @@ -1232,12 +1272,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. @@ -1252,7 +1297,8 @@ 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. - **kwds : optional + %s + **kwargs : optional Additional keyword arguments are documented in :meth:`DataFrame.plot`. @@ -1307,10 +1353,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 @@ -1324,7 +1374,8 @@ 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. - **kwds + %s + **kwargs Keyword arguments to pass on to :meth:`DataFrame.plot`. Returns @@ -1356,16 +1407,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 @@ -1405,8 +1456,9 @@ 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 - **kwds + **kwargs Keyword arguments to pass on to :meth:`DataFrame.plot`. Returns @@ -1443,10 +1495,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` @@ -1478,7 +1535,8 @@ 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. - **kwds + %s + **kwargs Additional keyword arguments are documented in :meth:`DataFrame.plot`. @@ -1527,12 +1585,19 @@ def hexbin(self, x, y, C=None, reduce_C_function=None, gridsize=None, **kwargs): ... gridsize=10, ... cmap="viridis") """ + + @Appender(_hexbin_docs % _shared_docs) + def hexbin(self, x, y, C=None, reduce_C_function=None, gridsize=None, figsize=None, + subplots=False, sharex=None, sharey=False, layout=None, title=None, + **kwargs): 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) + 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 = {}