ENH: Add grouped_bar() method

Author: timhoffm

doc/_embedded_plots/grouped_bar.py

@@ -0,0 +1,15 @@
+import matplotlib.pyplot as plt
+
+categories = ['A', '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=categories,
+    labels=['dataset 0', 'dataset 1', 'dataset 2'],
+    colors=['#1f77b4', '#58a1cf', '#abd0e6'],
+)
+ax.legend()

doc/api/axes_api.rst

@@ -67,6 +67,7 @@ Basic
    Axes.bar
    Axes.barh
    Axes.bar_label
+   Axes.grouped_bar
 
    Axes.stem
    Axes.eventplot

doc/api/pyplot_summary.rst

@@ -61,6 +61,7 @@ Basic
    bar
    barh
    bar_label
+   grouped_bar
    stem
    eventplot
    pie

doc/users/next_whats_new/grouped_bar.rst

@@ -0,0 +1,25 @@
+Grouped bar charts
+------------------
+
+The new method `~.Axes.grouped_bar()` simplifies the creation of grouped bar charts
+significantly. It supports different input data types (lists of datasets, dicts of
+datasets, data in 2D arrays, pandas DataFrames), and allows for easy customization
+of placement via controllable distances between bars and between bar groups.
+
+Example:
+
+.. plot::
+    :include-source: true
+
+    import matplotlib.pyplot as plt
+
+    categories = ['A', 'B']
+    datasets = {
+        'dataset 0': [1.0, 3.0],
+        'dataset 1': [1.4, 3.4],
+        'dataset 2': [1.8, 3.8],
+    }
+
+    fig, ax = plt.subplots(figsize=(4, 2.2))
+    ax.grouped_bar(datasets, tick_labels=categories)
+    ax.legend()

galleries/examples/lines_bars_and_markers/grouped_bar_chart.py

@@ -0,0 +1,183 @@
+"""
+=================
+Grouped bar chart
+=================
+
+This example serves to showcase and discuss the API. It's geared towards illustating
+API usage and design decisions only through the development phase. It's not intended
+to go into the final PR in this form.
+
+Input data formats
+==================
+
+Case 1: multiple separate datasets
+----------------------------------
+
+"""
+import matplotlib.pyplot as plt
+import numpy as np
+
+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
+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, group_labels)
+axs[0].legend()
+
+# grouped_bar() with list of datasets
+axs[1].grouped_bar([data1, data2, data3],
+                   tick_labels=group_labels, labels=["data1", "data2", "data3"])
+axs[1].legend()
+
+
+# %%
+# Case 1b: multiple datasets as dict
+# ----------------------------------
+# instead of carrying a list of datasets and a list of dataset labels, users may
+# want to organize their datasets in a dict.
+
+datasets = {
+    'data1': data1,
+    'data2': data2,
+    'data3': data3,
+}
+
+# %%
+# While you can feed keys and values into the above API, it may be convenient to pass
+# the whole dict as "data" and automatically extract the labels from the keys:
+
+fig, axs = plt.subplots(1, 2)
+
+# explicitly extract values and labels from a dict and feed to grouped_bar():
+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(datasets, tick_labels=group_labels)
+axs[1].legend()
+
+# %%
+# Case 2: 2D array data
+# ---------------------
+# When receiving a 2D array, we interpret the data as
+#
+# .. 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
+#
+# This is consistent with the standard data science interpretation of instances
+# on the vertical and features on the horizontal. And also matches how pandas is
+# interpreting rows and columns.
+#
+# Note that a list of individual datasets and a 2D array behave structurally different,
+# 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([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.
+
+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(data, tick_labels=group_labels, labels=columns)
+
+# %%
+# This creates the same plot as pandas (code cannot be executed because pandas
+# is not a doc dependency)::
+#
+#     df = pd.DataFrame(data, index=group_labels, columns=columns)
+#     df.plot.bar()
+
+# %%
+# 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
+
+positions = [0, 2, 4]
+data = {
+    'data1': [1, 2, 3],
+    'data2': [1.2, 2.2, 3.2],
+}
+
+fig, ax = plt.subplots()
+ax.grouped_bar(data, positions=positions)
+
+
+# %%
+# Bar width and spacing
+# =====================
+# 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.
+
+data = {
+    'data1': [1, 2, 3],
+    'data2': [1.2, 2.2, 3.2],
+    'data3': [1.4, 2.4, 3.4],
+    'data4': [1.6, 2.6, 3.6],
+}
+
+fig, axs = plt.subplots(2, 2)
+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)
+
+
+# %%
+# Styling
+# =======
+# The bars can be styled through additional keyword arguments. Currently,
+# the only per-dataset setting is ``colors``. Additionally, all
+# `.Rectangle` parameters are passed through and applied to all datasets.
+
+x = ['A', 'B', 'C']
+data = {
+    'data1': [1, 2, 3],
+    'data2': [1.2, 2.2, 3.2],
+    'data3': [1.4, 2.4, 3.4],
+    'data4': [1.6, 2.6, 3.6],
+}
+
+fig, ax = plt.subplots()
+ax.grouped_bar(data, tick_labels=x, colors=["r", "g", "b", "m"], edgecolor="black")
+
+
+# %%
+# Horizontal grouped bars
+# =======================
+# Use ``orientation="horizontal"`` to create horizontal grouped bar charts.
+
+x = ['A', 'B', 'C']
+data = {
+    'data1': [1, 2, 3],
+    'data2': [1.2, 2.2, 3.2],
+}
+
+fig, ax = plt.subplots()
+ax.grouped_bar(data, tick_labels=x, orientation="horizontal")