11042 refactor(plot sub-methods): signatures

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 = {}