From a2b2e2449d825de89b5435d6138476744b59d137 Mon Sep 17 00:00:00 2001 From: Miquel Camprodon Date: Sat, 10 Mar 2018 15:21:01 +0100 Subject: [PATCH 1/8] Bar plot documentation with examples --- pandas/plotting/_core.py | 75 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 71 insertions(+), 4 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 98fdcf8f94ae0..b3e23453c851e 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -2721,18 +2721,85 @@ def line(self, x=None, y=None, **kwds): def bar(self, x=None, y=None, **kwds): """ - Vertical bar plot + 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, y : label or position, optional - Coordinates for each point. - `**kwds` : optional + x : label or position, default None + y : label or position, default None + Allows plotting of one column versus another. + **kwds : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns ------- axes : matplotlib.AxesSubplot or np.array of them + + Examples + -------- + + Basic plot + + .. plot:: + :context: close-figs + + >>> df = pd.DataFrame({'lab':['A','B','C'], 'val':[10,30,20]}) + >>> ax = df.plot.bar(x='lab',y='val') + + + Plot a whole dataframe to a 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.bar() + + + Plot a column of the dataframe to a 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.bar(y='speed') + + + Plot only selected categories for the dataframe + + .. 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.bar(x='lifespan') + + + See Also + -------- + pandas.DataFrame.plot.barh : Horizontal bar plot. + pandas.DataFrame.plot : Make plots of DataFrame using matplotlib. + matplotlib.pyplot.bar : Make a bar plot. """ return self(kind='bar', x=x, y=y, **kwds) From 209d8a01de9e5d6b14352e5c312c2c6302098612 Mon Sep 17 00:00:00 2001 From: Miquel Camprodon Date: Sat, 10 Mar 2018 15:31:26 +0100 Subject: [PATCH 2/8] Bar plot documentation with examples --- pandas/plotting/_core.py | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index b3e23453c851e..19ff15b739204 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -2732,6 +2732,7 @@ def bar(self, x=None, y=None, **kwds): Parameters ---------- x : label or position, default None + Allows plotting of one column versus another. y : label or position, default None Allows plotting of one column versus another. **kwds : optional @@ -2752,7 +2753,6 @@ def bar(self, x=None, y=None, **kwds): >>> df = pd.DataFrame({'lab':['A','B','C'], 'val':[10,30,20]}) >>> ax = df.plot.bar(x='lab',y='val') - Plot a whole dataframe to a bar plot .. plot:: @@ -2766,7 +2766,6 @@ def bar(self, x=None, y=None, **kwds): ... 'lifespan': lifespan}, index=index) >>> ax = df.plot.bar() - Plot a column of the dataframe to a bar plot .. plot:: @@ -2780,7 +2779,6 @@ def bar(self, x=None, y=None, **kwds): ... 'lifespan': lifespan}, index=index) >>> ax = df.plot.bar(y='speed') - Plot only selected categories for the dataframe .. plot:: @@ -2794,7 +2792,6 @@ def bar(self, x=None, y=None, **kwds): ... 'lifespan': lifespan}, index=index) >>> ax = df.plot.bar(x='lifespan') - See Also -------- pandas.DataFrame.plot.barh : Horizontal bar plot. From b231f36d3b96eeaea33ba2f1c5299003d8f5543b Mon Sep 17 00:00:00 2001 From: Miquel Camprodon Date: Sat, 10 Mar 2018 15:52:19 +0100 Subject: [PATCH 3/8] Bar plot documentation with examples --- pandas/plotting/_core.py | 1 - 1 file changed, 1 deletion(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 19ff15b739204..29db6e45952bd 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -2744,7 +2744,6 @@ def bar(self, x=None, y=None, **kwds): Examples -------- - Basic plot .. plot:: From c6e6ca2beb8cefe5c06c87f3c4fec0dde78619d3 Mon Sep 17 00:00:00 2001 From: Miquel Camprodon Date: Tue, 13 Mar 2018 00:20:46 +0100 Subject: [PATCH 4/8] Adapting to reviewers comments. Added default behaviour --- pandas/plotting/_core.py | 25 ++++++++----------------- 1 file changed, 8 insertions(+), 17 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 29db6e45952bd..7bf4d13657d83 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -2731,12 +2731,15 @@ def bar(self, x=None, y=None, **kwds): Parameters ---------- - x : label or position, default None - Allows plotting of one column versus another. - y : label or position, default None - Allows plotting of one column versus another. + x : label or position, optional + Allows plotting of one column versus another. If not specified, + index of dataframe is taken. + y : label or position, optional + Allows plotting of one column versus another. If not specified, + all numerical columns are taken. **kwds : optional - Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. + Additional keyword arguments are documented in + meth:`pandas.DataFrame.plot`. Returns ------- @@ -2770,12 +2773,6 @@ def bar(self, x=None, y=None, **kwds): .. 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.bar(y='speed') Plot only selected categories for the dataframe @@ -2783,12 +2780,6 @@ def bar(self, x=None, y=None, **kwds): .. 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.bar(x='lifespan') See Also From 09065f8a480fecc0e51235fe5040ace4b3720195 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 12 Mar 2018 21:24:43 -0500 Subject: [PATCH 5/8] Grammar. Moved See Also. Label rotation. --- pandas/plotting/_core.py | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 76a1c0d1744f2..8dceb5ebfd43b 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -2847,29 +2847,36 @@ def bar(self, x=None, y=None, **kwds): ---------- x : label or position, optional Allows plotting of one column versus another. If not specified, - index of dataframe is taken. + the index of the DataFrame is use. y : label or position, optional Allows plotting of one column versus another. If not specified, - all numerical columns are taken. + all numerical columns are used. **kwds : optional Additional keyword arguments are documented in - meth:`pandas.DataFrame.plot`. + :meth:`pandas.DataFrame.plot`. Returns ------- - axes : matplotlib.AxesSubplot or np.array of them + axes : matplotlib.axes.Axes or np.array of them + + See Also + -------- + pandas.DataFrame.plot.barh : Horizontal bar plot. + pandas.DataFrame.plot : Make plots of DataFrame using matplotlib. + matplotlib.pyplot.bar : Make a bar plot with matplotlib. Examples -------- - Basic plot + Basic plot. .. plot:: :context: close-figs - >>> df = pd.DataFrame({'lab':['A','B','C'], 'val':[10,30,20]}) - >>> ax = df.plot.bar(x='lab',y='val') + >>> df = pd.DataFrame({'lab':['A', 'B', 'C'], 'val':[10, 30, 20]}) + >>> ax = df.plot.bar(x='lab', y='val', rot=0) - Plot a whole dataframe to a bar plot + Plot a whole dataframe to a bar plot. Each row is plotted as a group on + the horizontal axis, and each column is assigned a distinct color. .. plot:: :context: close-figs @@ -2880,27 +2887,21 @@ def bar(self, x=None, y=None, **kwds): ... 'rabbit', 'giraffe', 'coyote', 'horse'] >>> df = pd.DataFrame({'speed': speed, ... 'lifespan': lifespan}, index=index) - >>> ax = df.plot.bar() + >>> ax = df.plot.bar(rot=0) - Plot a column of the dataframe to a bar plot + Plot a single column. .. plot:: :context: close-figs - >>> ax = df.plot.bar(y='speed') + >>> ax = df.plot.bar(y='speed', rot=0) - Plot only selected categories for the dataframe + Plot only selected categories for the DataFrame. .. plot:: :context: close-figs - >>> ax = df.plot.bar(x='lifespan') - - See Also - -------- - pandas.DataFrame.plot.barh : Horizontal bar plot. - pandas.DataFrame.plot : Make plots of DataFrame using matplotlib. - matplotlib.pyplot.bar : Make a bar plot. + >>> ax = df.plot.bar(x='lifespan', rot=0) """ return self(kind='bar', x=x, y=y, **kwds) From 1892d35da02fac776aa39531d2977590eac8aa1a Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 12 Mar 2018 21:31:37 -0500 Subject: [PATCH 6/8] Subplots --- pandas/plotting/_core.py | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 8dceb5ebfd43b..7168511ee7673 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -2857,7 +2857,9 @@ def bar(self, x=None, y=None, **kwds): Returns ------- - axes : matplotlib.axes.Axes or np.array of them + axes : matplotlib.axes.Axes or np.ndarray of them + An ndarray is returned with one :class:`matplotlib.axes.Axes` + per column when ``subplots=True``. See Also -------- @@ -2875,8 +2877,9 @@ def bar(self, x=None, y=None, **kwds): >>> df = pd.DataFrame({'lab':['A', 'B', 'C'], 'val':[10, 30, 20]}) >>> ax = df.plot.bar(x='lab', y='val', rot=0) - Plot a whole dataframe to a bar plot. Each row is plotted as a group on - the horizontal axis, and each column is assigned a distinct color. + Plot a whole dataframe to a bar plot. Each column is assigned a + distinct color, and each row is nested in a group along the + horizontal axis. .. plot:: :context: close-figs @@ -2889,6 +2892,16 @@ def bar(self, x=None, y=None, **kwds): ... 'lifespan': lifespan}, index=index) >>> ax = df.plot.bar(rot=0) + Instead of nesting, the figure can be split by column with + ``subplots=True``. In this case, a :class:`numpy.ndarray` of + :class:`matplotlib.axes.Axes` are returned. + + .. plot:: + :context: close-figs + + >>> axes = df.plot.bar(rot=0, subplots=True) + >>> axes[1].legend(loc=2) # doctest: +SKIP + Plot a single column. .. plot:: From a5897d5a60516f049013effac92fede29ae4a62c Mon Sep 17 00:00:00 2001 From: miquelcamprodon Date: Tue, 13 Mar 2018 07:24:51 +0100 Subject: [PATCH 7/8] Update _core.py Fix typo --- pandas/plotting/_core.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 7168511ee7673..2a3f5092711c9 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -2847,7 +2847,7 @@ def bar(self, x=None, y=None, **kwds): ---------- x : label or position, optional Allows plotting of one column versus another. If not specified, - the index of the DataFrame is use. + 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. From 18fc6e2e66c474ea48ccceff97b047454030cb3b Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Tue, 13 Mar 2018 11:47:13 +0100 Subject: [PATCH 8/8] Update _core.py --- 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 2a3f5092711c9..0c2560abb0165 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -2851,7 +2851,7 @@ def bar(self, x=None, y=None, **kwds): y : label or position, optional Allows plotting of one column versus another. If not specified, all numerical columns are used. - **kwds : optional + **kwds Additional keyword arguments are documented in :meth:`pandas.DataFrame.plot`. @@ -2864,7 +2864,7 @@ def bar(self, x=None, y=None, **kwds): See Also -------- pandas.DataFrame.plot.barh : Horizontal bar plot. - pandas.DataFrame.plot : Make plots of DataFrame using matplotlib. + pandas.DataFrame.plot : Make plots of a DataFrame. matplotlib.pyplot.bar : Make a bar plot with matplotlib. Examples