Change signature to grouped_bar(heights, *, positions=None,

tick_labels=None, labels=None, ...)

Author: timhoffm

doc/_embedded_plots/grouped_bar.py

@@ -0,0 +1,15 @@
+import matplotlib.pyplot as plt
+
+group_labels = ['group A', 'group B']
+data0 = [1.0, 3.0]
+data1 = [1.4, 3.4]
+data2 = [1.8, 3.8]
+
+fig, ax = plt.subplots(figsize=(4, 2.2))
+ax.grouped_bar(
+    [data0, data1, data2],
+    tick_labels=group_labels,
+    labels=['dataset 0', 'dataset 1', 'dataset 2'],
+    colors=['#1f77b4', '#58a1cf', '#abd0e6'],
+)
+ax.legend()

galleries/examples/lines_bars_and_markers/grouped_bar_chart.py

@@ -17,28 +17,27 @@
 import matplotlib.pyplot as plt
 import numpy as np
 
-x = ['A', 'B']
+group_labels = ['A', 'B']
 data1 = [1, 1.2]
 data2 = [2, 2.4]
 data3 = [3, 3.6]
 
 
 fig, axs = plt.subplots(1, 2)
 
-# current solution: manual positioning with multiple bar)= calls
+# current solution: manual positioning with multiple bar() calls
 label_pos = np.array([0, 1])
 bar_width = 0.8 / 3
 data_shift = -1*bar_width + np.array([0, bar_width, 2*bar_width])
 axs[0].bar(label_pos + data_shift[0], data1, width=bar_width, label="data1")
 axs[0].bar(label_pos + data_shift[1], data2, width=bar_width, label="data2")
 axs[0].bar(label_pos + data_shift[2], data3, width=bar_width, label="data3")
-axs[0].set_xticks(label_pos, x)
+axs[0].set_xticks(label_pos, group_labels)
 axs[0].legend()
 
 # grouped_bar() with list of datasets
-# note also that this is a straight-forward generalization of the single-dataset case:
-#   bar(x, data1, label="data1")
-axs[1].grouped_bar(x, [data1, data2, data3], labels=["data1", "data2", "data3"])
+axs[1].grouped_bar([data1, data2, data3],
+                   tick_labels=group_labels, labels=["data1", "data2", "data3"])
 axs[1].legend()
 
 
@@ -61,10 +60,10 @@
 fig, axs = plt.subplots(1, 2)
 
 # explicitly extract values and labels from a dict and feed to grouped_bar():
-axs[0].grouped_bar(x, datasets.values(), labels=datasets.keys())
+axs[0].grouped_bar(datasets.values(), tick_labels=group_labels, labels=datasets.keys())
 axs[0].legend()
 # accepting a dict as input
-axs[1].grouped_bar(x, datasets)
+axs[1].grouped_bar(datasets, tick_labels=group_labels)
 axs[1].legend()
 
 # %%
@@ -86,57 +85,56 @@
 # i.e. hen turning a list into a numpy array, you have to transpose that array to get
 # the correct representation. Those two behave the same::
 #
-#     grouped_bar(x, [data1, data2])
-#     grouped_bar(x, np.array([data1, data2]).T)
+#     grouped_bar([data1, data2])
+#     grouped_bar(np.array([data1, data2]).T)
 #
 # This is a conscious decision, because the commonly understood dimension ordering
 # semantics of "list of datasets" and 2D array of datasets is different.
 
-x = ['A', 'B']
+group_labels = ['A', 'B']
 data = np.array([
     [1, 2, 3],
     [1.2, 2.4, 3.6],
 ])
 columns = ["data1", "data2", "data3"]
 
 fig, ax = plt.subplots()
-ax.grouped_bar(x, data, labels=columns)
+ax.grouped_bar(data, tick_labels=group_labels, labels=columns)
 
 # %%
 # This creates the same plot as pandas (code cannot be executed because pandas
-# os not a doc dependency)::
+# is not a doc dependency)::
 #
-#     df = pd.DataFrame(data, index=x, columns=columns)
+#     df = pd.DataFrame(data, index=group_labels, columns=columns)
 #     df.plot.bar()
 
 # %%
-# Numeric x values
-# ----------------
-# In the most common case, one will want to pass categorical labels as *x*.
-# Additionally, we allow numeric values for *x*, as with `~.Axes.bar()`.
-# But for simplicity and clarity, we require that these are equidistant.
+# Controlling bar group center positions
+# ======================================
+# By default, bars groups are centered on integer positions 0, 1, 2, ...
+# This can be overridden using the *positions* parameter, but for simplicity
+# and clarity, we require that the positions are equidistant
 
-x = [0, 2, 4]
+positions = [0, 2, 4]
 data = {
     'data1': [1, 2, 3],
     'data2': [1.2, 2.2, 3.2],
 }
 
 fig, ax = plt.subplots()
-ax.grouped_bar(x, data)
+ax.grouped_bar(data, positions=positions)
 
 
 # %%
 # Bar width and spacing
 # =====================
-# The center positions of the bar groups are given by x. We can still choose
+# The center positions of the bar groups are equidistantly spaced. We can still choose
 # two of the following properties: bar width, spacing between groups, and
 # spacing between bars.
 #
 # We believe the most convenient approach is defining spacing between groups
 # and spacing between bars as fraction of the bar width.
 
-x = ['A', 'B', 'C']
 data = {
     'data1': [1, 2, 3],
     'data2': [1.2, 2.2, 3.2],
@@ -145,10 +143,10 @@
 }
 
 fig, axs = plt.subplots(2, 2)
-axs[0, 0].grouped_bar(x, data)
-axs[0, 1].grouped_bar(x, data, group_spacing=0.5)
-axs[1, 0].grouped_bar(x, data, bar_spacing=0.2)
-axs[1, 1].grouped_bar(x, data, group_spacing=0.5, bar_spacing=0.1)
+axs[0, 0].grouped_bar(data)
+axs[0, 1].grouped_bar(data, group_spacing=0.5)
+axs[1, 0].grouped_bar(data, bar_spacing=0.2)
+axs[1, 1].grouped_bar(data, group_spacing=0.5, bar_spacing=0.1)
 
 
 # %%
@@ -167,7 +165,7 @@
 }
 
 fig, ax = plt.subplots()
-ax.grouped_bar(x, data, colors=["r", "g", "b", "m"], edgecolor="black")
+ax.grouped_bar(data, tick_labels=x, colors=["r", "g", "b", "m"], edgecolor="black")
 
 
 # %%
@@ -182,4 +180,4 @@
 }
 
 fig, ax = plt.subplots()
-ax.grouped_bar(x, data, orientation="horizontal")
+ax.grouped_bar(data, tick_labels=x, orientation="horizontal")

lib/matplotlib/axes/_axes.py

@@ -3066,8 +3066,8 @@ def broken_barh(self, xranges, yrange, **kwargs):
         return col
 
     @_docstring.interpd
-    def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
-                    labels=None, orientation="vertical", colors=None,
+    def grouped_bar(self, heights, *, positions=None, group_spacing=1.5, bar_spacing=0,
+                    tick_labels=None, labels=None, orientation="vertical", colors=None,
                     **kwargs):
         """
         Make a grouped bar plot.
@@ -3080,25 +3080,24 @@ def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
         into one Axes. In particular, it simplifies positioning of the bars
         compared to individual `~.Axes.bar` plots.
 
+        Terminology: A bar *group* is a set of bars drawn next to each other. They
+        can be associated with a group name, which is visualized as the tick label
+        below that group. A *dataset*  is a set of values, one for each bar group.
+        This means *dataset_0* will be rendered as the first bar in each bar group.
+
+        .. plot:: _embedded_plots/grouped_bar.py
+
         Parameters
         ----------
-        x : array-like or list of str
-            The center positions of the bar groups. If these are numeric values,
-            they have to be equidistant. As with `~.Axes.bar`, you can provide
-            categorical labels, which will be used at integer numeric positions
-            ``range(x)``.
-
         heights : list of array-like or dict of array-like or 2D array
             The heights for all x and groups. One of:
 
             - list of array-like: A list of datasets, each dataset must have
-              ``len(x)`` elements.
+              the same number of elements.
 
               .. code-block:: none
 
-                  x = ["a", "b"]
-
-                  #            x[0]   x[1]
+                  #           group_A group_B
                   dataset_0 = [ds0_a, ds0_b]
                   dataset_1 = [ds1_a, ds1_b]
                   dataset_2 = [ds2_a, ds2_b]
@@ -3107,24 +3106,24 @@ def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
 
               Example call::
 
-                  grouped_bar(x, [dataset_0, dataset_1, dataset_2])
+                  grouped_bar([dataset_0, dataset_1, dataset_2])
 
             - dict of array-like: A mapping names to datasets. Each dataset
-              (dict value) must have ``len(x)`` elements.
+              (dict value) must have the same number of elements elements.
 
               This is similar to passing a list of array-like, with the addition that
               each dataset gets a name.
 
               Example call::
 
-                grouped_bar(x, {'ds0': dataset_0, 'ds1': dataset_1, 'ds2': dataset_2]})
+                grouped_bar({'ds0': dataset_0, 'ds1': dataset_1, 'ds2': dataset_2]})
 
               The names are used as *labels*, i.e. the following two calls are
               equivalent::
 
                 data_dict = {'ds0': dataset_0, 'ds1': dataset_1, 'ds2': dataset_2]}
-                grouped_bar(x, data_dict)
-                grouped_bar(x, data_dict.values(), labels=data_dict.keys())
+                grouped_bar(data_dict)
+                grouped_bar(data_dict.values(), labels=data_dict.keys())
 
               When using a dict-like input, you must not pass *labels* explicitly.
 
@@ -3133,33 +3132,41 @@ def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
               .. code-block:: none
 
                           dataset_0 dataset_1 dataset_2
-                 x[0]="a"   ds0_a     ds1_a     ds2_a
-                 x[1]="b"   ds0_b     ds1_b     ds2_b
+                 group_A    ds0_a     ds1_a     ds2_a
+                 group_B    ds0_b     ds1_b     ds2_b
 
               .. code-block::
 
-                  x = ["a", "b"]
+                  group_labels = ["group_A", "group_B"]
                   dataset_labels = ["dataset_0", "dataset_1", "dataset_2"]
                   array = np.random.random((2, 3))
 
               Note that this is consistent with pandas. These two calls produce
               the same bar plot structure::
 
-                  grouped_bar(x, array, labels=dataset_labels)
-                  pd.DataFrame(array, index=x, columns=dataset_labels).plot.bar()
+                  grouped_bar(array, tick_labels=group_labels, labels=dataset_labels)
+                  df = pd.DataFrame(array, index=group_labels, columns=dataset_labels)
+                  df.plot.bar()
 
-        group_spacing : float
-            The space between two bar groups in units of bar width.
+        positions : array-like, optional
+            The center positions of the bar groups. The values have to be equidistant.
+            If not given, a sequence of integer positions 0, 1, 2, ... is used.
 
-        bar_spacing : float
-            The space between bars in units of bar width.
+        tick_labels: list of str, optional
+            The group labels, which are placed on ticks at the center *positions*
+            of the bar groups.
 
-        labels : array-like of str, optional
+            If not set, the axis ticks (positions and labels) are left unchanged.
+
+        labels : list of str, optional
             The labels of the datasets, i.e. the bars within one group.
             These will show up in the legend.
 
-            Note: The "other" label dimension are the group labels, which
-            can be set via *x*.
+        group_spacing : float
+            The space between two bar groups in units of bar width.
+
+        bar_spacing : float
+            The space between bars in units of bar width.
 
         orientation : {"vertical", "horizontal"}, default: "vertical"
             The direction of the bars.
@@ -3196,27 +3203,26 @@ def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
                 raise ValueError(
                     "'labels' cannot be used if 'heights' are a mapping")
             labels = heights.keys()
-            heights = heights.values()
+            heights = list(heights.values())
         elif hasattr(heights, 'shape'):
             heights = heights.T
 
-        num_groups = len(x)
         num_datasets = len(heights)
+        dataset_0 = next(iter(heights))
+        num_groups = len(dataset_0)
 
-        if isinstance(x[0], str):
-            tick_labels = x
+        if positions is None:
             group_centers = np.arange(num_groups)
             group_distance = 1
         else:
-            if num_groups > 1:
-                d = np.diff(x)
+            group_centers = np.asanyarray(positions)
+            if len(group_centers) > 1:
+                d = np.diff(group_centers)
                 if not np.allclose(d, d.mean()):
-                    raise ValueError("'x' must be equidistant")
+                    raise ValueError("'positions' must be equidistant")
                 group_distance = d[0]
             else:
                 group_distance = 1
-            group_centers = np.asarray(x)
-            tick_labels = None
 
         for i, dataset in enumerate(heights):
             if len(dataset) != num_groups: