Rename dataset_labels -> labels

Author: timhoffm

galleries/examples/lines_bars_and_markers/grouped_bar_chart.py

@@ -35,7 +35,7 @@
 # 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], dataset_labels=["data1", "data2", "data3"])
+axs[1].grouped_bar(x, [data1, data2, data3], labels=["data1", "data2", "data3"])
 
 
 # %%
@@ -57,7 +57,7 @@
 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(), dataset_labels=datasets.keys())
+axs[0].grouped_bar(x, datasets.values(), labels=datasets.keys())
 # accepting a dict as input
 axs[1].grouped_bar(x, datasets)
 
@@ -94,7 +94,7 @@
 columns = ["data1", "data2", "data3"]
 
 fig, ax = plt.subplots()
-ax.grouped_bar(x, data, dataset_labels=columns)
+ax.grouped_bar(x, data, labels=columns)
 
 # %%
 # This creates the same plot as pandas (code cannot be executed because pandas

lib/matplotlib/axes/_axes.py

@@ -3049,7 +3049,7 @@ def broken_barh(self, xranges, yrange, **kwargs):
         return col
 
     def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
-                    dataset_labels=None, orientation="vertical", colors=None,
+                    labels=None, orientation="vertical", colors=None,
                     **kwargs):
         """
         Make a grouped bar plot.
@@ -3119,8 +3119,12 @@ def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
         bar_spacing : float
             The space between bars in units of bar width.
 
-        dataset_labels : array-like of str, optional
-            The labels of the datasets.
+        labels : array-like 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*.
 
         orientation : {"vertical", "horizontal"}, default: vertical
 
@@ -3138,10 +3142,10 @@ def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
 
         """
         if hasattr(heights, 'keys'):
-            if dataset_labels is not None:
+            if labels is not None:
                 raise ValueError(
-                    "'dataset_labels' cannot be used if 'heights' are a mapping")
-            dataset_labels = heights.keys()
+                    "'labels' cannot be used if 'heights' are a mapping")
+            labels = heights.keys()
             heights = heights.values()
         elif hasattr(heights, 'shape'):
             heights = heights.T
@@ -3185,23 +3189,23 @@ def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
         bar_spacing_abs = bar_spacing * bar_width
         margin_abs = 0.5 * group_spacing * bar_width
 
-        if dataset_labels is None:
-            dataset_labels = [None] * num_datasets
+        if labels is None:
+            labels = [None] * num_datasets
         else:
-            assert len(dataset_labels) == num_datasets
+            assert len(labels) == num_datasets
 
         # place the bars, but only use numerical positions, categorical tick labels
         # are handled separately below
-        for i, (hs, dataset_label, color) in enumerate(
-                zip(heights, dataset_labels, colors)):
+        for i, (hs, label, color) in enumerate(
+                zip(heights, labels, colors)):
             lefts = (group_centers - 0.5 * group_distance + margin_abs
                      + i * (bar_width + bar_spacing_abs))
             if orientation == "vertical":
                 self.bar(lefts, hs, width=bar_width, align="edge",
-                         label=dataset_label, color=color, **kwargs)
+                         label=label, color=color, **kwargs)
             else:
                 self.barh(lefts, hs, height=bar_width, align="edge",
-                          label=dataset_label, color=color, **kwargs)
+                          label=label, color=color, **kwargs)
 
         if tick_labels is not None:
             if orientation == "vertical":

lib/matplotlib/axes/_axes.pyi

@@ -286,7 +286,7 @@ class Axes(_AxesBase):
         *,
         group_spacing : float | None = ...,
         bar_spacing : float | None = ...,
-        dataset_labels : Sequence[str] | None = ...,
+        labels : Sequence[str] | None = ...,
         orientation: Literal["vertical", "horizontal"] = ...,
         colors: Iterable[ColorType] | None = ...,
         **kwargs

lib/matplotlib/pyplot.py

@@ -3396,7 +3396,7 @@ def grouped_bar(
     *,
     group_spacing: float | None = 1.5,
     bar_spacing: float | None = 0,
-    dataset_labels: Sequence[str] | None = None,
+    labels: Sequence[str] | None = None,
     orientation: Literal["vertical", "horizontal"] = "vertical",
     colors: Iterable[ColorType] | None = None,
     **kwargs,
@@ -3406,7 +3406,7 @@ def grouped_bar(
         heights,
         group_spacing=group_spacing,
         bar_spacing=bar_spacing,
-        dataset_labels=dataset_labels,
+        labels=labels,
         orientation=orientation,
         colors=colors,
         **kwargs,