From d44221429b71b4de684db4de55bcc1828574c56e Mon Sep 17 00:00:00 2001 From: David Polo Date: Sat, 10 Mar 2018 15:27:21 +0100 Subject: [PATCH 1/4] DOC: Improved the docstring of pandas.plotting._core.FramePlotMethods.barh() - Added examples section - Added extended summary - Added argument explanation --- pandas/plotting/_core.py | 71 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 67 insertions(+), 4 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 98fdcf8f94ae0..53349d73c4c92 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -2738,18 +2738,81 @@ def bar(self, x=None, y=None, **kwds): def barh(self, x=None, y=None, **kwds): """ - Horizontal bar plot + Make a horizontal bar plot. + + A horizontal 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, y : label or position, optional - Coordinates for each point. - `**kwds` : optional + x : label or position, optional + Column to be used for categories. + y : label or position, optional + Columns to be plotted from the DataFrame. + kwds : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns ------- axes : matplotlib.AxesSubplot or np.array of them + + See Also + -------- + pandas.DataFrame.plot.bar: Vertical bar plot + pandas.DataFrame.plot : Make plots of DataFrame using matplotlib. + matplotlib.axes.Axes.bar : Plot a vertical bar plot using matplotlib. + + Examples + -------- + Basic example + + .. plot:: + :context: close-figs + + >>> df = pd.DataFrame({'lab':['A','B','C'], 'val':[10,30,20]}) + >>> ax = df.plot.barh(x='lab',y='val') + + Plot a whole DataFrame to a horizontal bar plot + + .. plot:: + :context: close-figs + + >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] + >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] + >>> index = ['snail', 'pig', 'elephant', + ... 'rabbit', 'giraffe', 'coyote', 'horse'] + >>> df = pd.DataFrame({'speed': speed, + ... 'lifespan': lifespan}, index=index) + >>> ax = df.plot.barh() + + Plot a column of the DataFrame to a horizontal bar plot + + .. plot:: + :context: close-figs + + >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] + >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] + >>> index = ['snail', 'pig', 'elephant', + ... 'rabbit', 'giraffe', 'coyote', 'horse'] + >>> df = pd.DataFrame({'speed': speed, + ... 'lifespan': lifespan}, index=index) + >>> ax = df.plot.barh(y='speed') + + Plot DataFrame versus the desired column + + .. plot:: + :context: close-figs + + >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] + >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] + >>> index = ['snail', 'pig', 'elephant', + ... 'rabbit', 'giraffe', 'coyote', 'horse'] + >>> df = pd.DataFrame({'speed': speed, + ... 'lifespan': lifespan}, index=index) + >>> ax = df.plot.barh(x='lifespan') """ return self(kind='barh', x=x, y=y, **kwds) From a3f1982c24c7e0bee190871ba84126f8d2652780 Mon Sep 17 00:00:00 2001 From: David Polo Date: Sat, 10 Mar 2018 15:49:59 +0100 Subject: [PATCH 2/4] DOC: Improved the docstring of pandas.plotting._core.FramePlotMethods.barh() - Correcting PR comments --- pandas/plotting/_core.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 53349d73c4c92..2bb1bac7dace9 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -2740,7 +2740,7 @@ def barh(self, x=None, y=None, **kwds): """ Make a horizontal bar plot. - A horizontal bar plot is a plot that presents categorical data with + 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 @@ -2752,16 +2752,16 @@ def barh(self, x=None, y=None, **kwds): Column to be used for categories. y : label or position, optional Columns to be plotted from the DataFrame. - kwds : optional + kwds 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. See Also -------- - pandas.DataFrame.plot.bar: Vertical bar plot + pandas.DataFrame.plot.bar: Vertical bar plot. pandas.DataFrame.plot : Make plots of DataFrame using matplotlib. matplotlib.axes.Axes.bar : Plot a vertical bar plot using matplotlib. @@ -2772,8 +2772,8 @@ def barh(self, x=None, y=None, **kwds): .. plot:: :context: close-figs - >>> df = pd.DataFrame({'lab':['A','B','C'], 'val':[10,30,20]}) - >>> ax = df.plot.barh(x='lab',y='val') + >>> df = pd.DataFrame({'lab':['A', 'B', 'C'], 'val':[10, 30, 20]}) + >>> ax = df.plot.barh(x='lab', y='val') Plot a whole DataFrame to a horizontal bar plot From 3c48ca07f1a2491991da8b1f34f2402c1ca1c773 Mon Sep 17 00:00:00 2001 From: David Polo Date: Sat, 10 Mar 2018 15:57:33 +0100 Subject: [PATCH 3/4] DOC: Improved the docstring of pandas.plotting._core.FramePlotMethods.barh() - Adding defaults for variables. --- pandas/plotting/_core.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 2bb1bac7dace9..4105ac60a90d8 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -2748,9 +2748,9 @@ def barh(self, x=None, y=None, **kwds): Parameters ---------- - x : label or position, optional + x : label or position, default DataFrame.index Column to be used for categories. - y : label or position, optional + y : label or position, default All numeric columns in dataframe Columns to be plotted from the DataFrame. kwds Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. From f9c2c3ca359f6a2c6e8b11892e341f66fef7409c Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sun, 11 Mar 2018 16:50:13 -0500 Subject: [PATCH 4/4] Update reference --- pandas/plotting/_core.py | 42 ++++++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 4105ac60a90d8..6d1f3fea1bf12 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -1873,7 +1873,7 @@ def _plot(data, x=None, y=None, subplots=False, Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them Notes ----- @@ -2536,7 +2536,7 @@ def line(self, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them Examples -------- @@ -2560,7 +2560,7 @@ def bar(self, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='bar', **kwds) @@ -2575,7 +2575,7 @@ def barh(self, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='barh', **kwds) @@ -2590,7 +2590,7 @@ def box(self, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='box', **kwds) @@ -2607,7 +2607,7 @@ def hist(self, bins=10, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='hist', bins=bins, **kwds) @@ -2632,7 +2632,7 @@ def kde(self, bw_method=None, ind=None, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='kde', bw_method=bw_method, ind=ind, **kwds) @@ -2649,7 +2649,7 @@ def area(self, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='area', **kwds) @@ -2664,7 +2664,7 @@ def pie(self, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='pie', **kwds) @@ -2715,7 +2715,7 @@ def line(self, x=None, y=None, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='line', x=x, y=y, **kwds) @@ -2732,7 +2732,7 @@ def bar(self, x=None, y=None, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='bar', x=x, y=y, **kwds) @@ -2752,12 +2752,12 @@ def barh(self, x=None, y=None, **kwds): Column to be used for categories. y : label or position, default All numeric columns in dataframe Columns to be plotted from the DataFrame. - kwds - Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. + **kwds + Keyword arguments to pass on to :meth:`pandas.DataFrame.plot`. Returns ------- - axes : matplotlib.AxesSubplot or np.array of them. + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them. See Also -------- @@ -2829,7 +2829,7 @@ def box(self, by=None, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='box', by=by, **kwds) @@ -2848,7 +2848,7 @@ def hist(self, by=None, bins=10, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='hist', by=by, bins=bins, **kwds) @@ -2873,7 +2873,7 @@ def kde(self, bw_method=None, ind=None, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='kde', bw_method=bw_method, ind=ind, **kwds) @@ -2892,7 +2892,7 @@ def area(self, x=None, y=None, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='area', x=x, y=y, **kwds) @@ -2909,7 +2909,7 @@ def pie(self, y=None, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='pie', y=y, **kwds) @@ -2930,7 +2930,7 @@ def scatter(self, x, y, s=None, c=None, **kwds): Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ return self(kind='scatter', x=x, y=y, c=c, s=s, **kwds) @@ -2955,7 +2955,7 @@ def hexbin(self, x, y, C=None, reduce_C_function=None, gridsize=None, Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them """ if reduce_C_function is not None: kwds['reduce_C_function'] = reduce_C_function