🎨 share docs

Author: MarcoGorelli

pandas/plotting/_core.py

@@ -386,6 +386,45 @@ def hist_frame(
 """
 
 
+_bar_or_line_doc = """\
+Parameters
+----------
+x : label or position, optional
+ Allows plotting of one column versus another. If not specified,
+ the index of the DataFrame is used.
+y : label or position, optional
+ Allows plotting of one column versus another. If not specified,
+ all numerical columns are used.
+color : str, array_like, or dict, optional
+ The color for each of the DataFrame's columns. Possible values are:
+
+ - A single color string referred to by name, RGB or RGBA code,
+ for instance 'red' or '#a98d19'.
+
+ - A sequence of color strings referred to by name, RGB or RGBA
+ code, which will be used for each column recursively. For
+ instance ['green','yellow'] each column's %(kind)s will be filled in
+ green or yellow, alternatively.
+
+ - A dict of the form {column name : color}, so that each column will be
+ colored accordingly. For example, if your columns are called `a` and `b`,
+ then passing {'a': 'green', 'b': 'red'} will color %(kind)ss for column `a` in
+ green and %(kind)ss for column `b` in red.
+
+ .. versionadded:: 1.1.0
+
+**kwargs
+ Additional keyword arguments are documented in
+ :meth:`DataFrame.plot`.
+
+Returns
+-------
+matplotlib.axes.Axes or np.ndarray of them
+ An ndarray is returned with one :class:`matplotlib.axes.Axes`
+ per column when ``subplots=True``.
+"""
+
+
 @Substitution(backend="")
 @Appender(_boxplot_doc)
 def boxplot(
@@ -847,46 +886,8 @@ def __call__(self, *args, **kwargs):
 
  return plot_backend.plot(data, kind=kind, **kwargs)
 
- def line(self, x=None, y=None, **kwargs):
+ @Appender(
  """
- Plot Series or DataFrame as lines.
-
- This function is useful to plot lines using DataFrame's values
- as coordinates.
-
- Parameters
- ----------
- x : int or str, optional
- Columns to use for the horizontal axis.
- Either the location or the label of the columns to be used.
- By default, it will use the DataFrame indices.
- y : int, str, or list of them, optional
- 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.
- color : str, int, array_like, or dict, optional
- The color for each of the DataFrame's columns. Possible values are:
-
- - A single color string referred to by name, RGB or RGBA code,
- for instance 'red' or '#a98d19'.
-
- - A sequence of color strings referred to by name, RGB or RGBA
- code, which will be used for each column recursively. For
- instance ['green','yellow'] each column's line will be coloured in
- green or yellow, alternatively.
-
- - A dict of the form {column name : color}, so that each column will be
- colored accordingly. For example, if your columns are called `a` and `b`,
- then passing {'a': 'green', 'b': 'red'} will color lines for column `a` in
- green and lines for column `b` in red.
- **kwargs
- Keyword arguments to pass on to :meth:`DataFrame.plot`.
-
- Returns
- -------
- :class:`matplotlib.axes.Axes` or :class:`numpy.ndarray`
- Return an ndarray when ``subplots=True``.
-
  See Also
  --------
  matplotlib.pyplot.plot : Plot y versus x as lines and/or markers.
@@ -939,51 +940,21 @@ 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):
+ )
+ @Substitution(kind="line")
+ @Appender(_bar_or_line_doc)
+ def line(self, x=None, y=None, **kwargs):
  """
- Vertical bar plot.
-
- A bar plot is a plot that presents categorical data with
- rectangular bars with lengths proportional to the values that they
- represent. A bar plot shows comparisons among discrete categories. One
- axis of the plot shows the specific categories being compared, and the
- other axis represents a measured value.
-
- Parameters
- ----------
- x : label or position, optional
- Allows plotting of one column versus another. If not specified,
- the index of the DataFrame is used.
- y : label or position, optional
- Allows plotting of one column versus another. If not specified,
- all numerical columns are used.
- color : str, int, array_like, or dict, optional
- The color for each of the DataFrame's columns. Possible values are:
-
- - A single color string referred to by name, RGB or RGBA code,
- for instance 'red' or '#a98d19'.
+ Plot Series or DataFrame as lines.
 
- - A sequence of color strings referred to by name, RGB or RGBA
- code, which will be used for each column recursively. For
- instance ['green','yellow'] each column's bar will be filled in
- green or yellow, alternatively.
-
- - A dict of the form {column name : color}, so that each column will be
- colored accordingly. For example, if your columns are called `a` and `b`,
- then passing {'a': 'green', 'b': 'red'} will color bars for column `a` in
- green and bars for column `b` in red.
- **kwargs
- Additional keyword arguments are documented in
- :meth:`DataFrame.plot`.
+ This function is useful to plot lines using DataFrame's values
+ as coordinates.
 
- Returns
- -------
- matplotlib.axes.Axes or np.ndarray of them
- An ndarray is returned with one :class:`matplotlib.axes.Axes`
- per column when ``subplots=True``.
+ """
+ return self(kind="line", x=x, y=y, **kwargs)
 
+ @Appender(
+ """
  See Also
  --------
  DataFrame.plot.barh : Horizontal bar plot.
@@ -1049,47 +1020,25 @@ def bar(self, x=None, y=None, **kwargs):
  :context: close-figs
 
  >>> ax = df.plot.bar(x='lifespan', rot=0)
+ """
+ )
+ @Substitution(kind="bar")
+ @Appender(_bar_or_line_doc)
+ def bar(self, x=None, y=None, **kwargs):
  """
- return self(kind="bar", x=x, y=y, **kwargs)
-
- def barh(self, x=None, y=None, **kwargs):
- """
- Make a horizontal bar plot.
+ Vertical bar plot.
 
- A horizontal bar plot is a plot that presents quantitative data with
+ A bar plot is a plot that presents categorical data with
  rectangular bars with lengths proportional to the values that they
  represent. A bar plot shows comparisons among discrete categories. One
  axis of the plot shows the specific categories being compared, and the
  other axis represents a measured value.
 
- Parameters
- ----------
- x : label or position, default DataFrame.index
- Column to be used for categories.
- y : label or position, default All numeric columns in dataframe
- Columns to be plotted from the DataFrame.
- color : str, int, array_like, or dict, optional
- The color for each of the DataFrame's columns. Possible values are:
-
- - A single color string referred to by name, RGB or RGBA code,
- for instance 'red' or '#a98d19'.
-
- - A sequence of color strings referred to by name, RGB or RGBA
- code, which will be used for each column recursively. For
- instance ['green','yellow'] each column's bar will be filled in
- green or yellow, alternatively.
-
- - A dict of the form {column name : color}, so that each column will be
- colored accordingly. For example, if your columns are called `a` and `b`,
- then passing {'a': 'green', 'b': 'red'} will color bars for column `a` in
- green and bars for column `b` in red.
- **kwargs
- Keyword arguments to pass on to :meth:`DataFrame.plot`.
-
- Returns
- -------
- :class:`matplotlib.axes.Axes` or numpy.ndarray of them
+ """
+ return self(kind="bar", x=x, y=y, **kwargs)
 
+ @Appender(
+ """
  See Also
  --------
  DataFrame.plot.bar: Vertical bar plot.
@@ -1151,6 +1100,20 @@ def barh(self, x=None, y=None, **kwargs):
  >>> df = pd.DataFrame({'speed': speed,
  ... 'lifespan': lifespan}, index=index)
  >>> ax = df.plot.barh(x='lifespan')
+ """
+ )
+ @Substitution(kind="bar")
+ @Appender(_bar_or_line_doc)
+ def barh(self, x=None, y=None, **kwargs):
+ """
+ Make a horizontal bar plot.
+
+ A horizontal bar plot is a plot that presents quantitative data with
+ rectangular bars with lengths proportional to the values that they
+ represent. A bar plot shows comparisons among discrete categories. One
+ axis of the plot shows the specific categories being compared, and the
+ other axis represents a measured value.
+
  """
  return self(kind="barh", x=x, y=y, **kwargs)