@@ -3013,6 +3013,7 @@ def broken_barh(self, xranges, yrange, **kwargs):
30133013
30143014return col
30153015
3016+ @_docstring .interpd
30163017def grouped_bar (self ,x ,heights ,* ,group_spacing = 1.5 ,bar_spacing = 0 ,
30173018labels = None ,orientation = "vertical" ,colors = None ,
30183019** kwargs ):
@@ -3023,6 +3024,10 @@ def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
30233024 This function is new in v3.10, and the API is still provisional.
30243025 We may still fine-tune some aspects based on user-feedback.
30253026
3027+ This is a convenience function to plot bar charts for multiple datasets
3028+ into one Axes. In particular, it simplifies positioning of the bars
3029+ compared to individual `~.Axes.bar` plots.
3030+
30263031 Parameters
30273032 ----------
30283033 x : array-like or list of str
@@ -3039,44 +3044,57 @@ def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
30393044
30403045 .. code-block:: none
30413046
3042- x = ['a', 'b']
3043- group_labels = ['ds0', 'ds1', 'ds2']
3047+ x = ["a", "b"]
3048+
3049+ # x[0] x[1]
3050+ dataset_0 = [ds0_a, ds0_b]
3051+ dataset_1 = [ds1_a, ds1_b]
3052+ dataset_2 = [ds2_a, ds2_b]
3053+
3054+ heights = [dataset_0, dataset_1, dataset_2]
3055+
3056+ Example call::
3057+
3058+ grouped_bar(x, [dataset_0, dataset_1, dataset_2])
3059+
3060+ - dict of array-like: A mapping names to datasets. Each dataset
3061+ (dict value) must have ``len(x)`` elements.
30443062
3045- # group_labels: ds0 ds1 dw2
3046- heights = [dataset_0, dataset_1, dataset_2]
3063+ This is similar to passing a list of array-like, with the addition that
3064+ each dataset gets a name.
30473065
3048- # x[0] x[1]
3049- dataset_0 = [ds0_a, ds0_b]
3066+ Example call::
30503067
3051- # x[0] x[1]
3052- heights = [[ds0_a, ds0_b], # dataset_0
3053- [ds1_a, ds1_b], # dataset_1
3054- [ds2_a, ds2_b], # dataset_2
3055- ]
3068+ grouped_bar(x, {'ds0': dataset_0, 'ds1': dataset_1, 'ds2': dataset_2]})
30563069
3057- - dict of array-like: A names to datasets, each dataset (dict value)
3058- must have ``len(x)`` elements.
3070+ The names are used as *labels*, i.e. the following two calls are
3071+ equivalent::
30593072
3060- group_labels = heights.keys()
3061- heights = heights.values()
3073+ data_dict = {'ds0': dataset_0, 'ds1': dataset_1, 'ds2': dataset_2]}
3074+ grouped_bar(x, data_dict)
3075+ grouped_bar(x, data_dict.values(), labels=data_dict.keys())
30623076
3063- - a 2D array: columns map to *x*, columns are the different datasets.
3077+ When using a dict-like input, you must not pass *labels* explicitly.
3078+
3079+ - a 2D array: The columns are the different datasets.
30643080
30653081 .. code-block:: none
30663082
30673083 dataset_0 dataset_1 dataset_2
3068- x[0]='a' ds0_a ds1_a ds2_a
3069- x[1]='b' ds0_b ds1_b ds2_b
3084+ x[0]="a" ds0_a ds1_a ds2_a
3085+ x[1]="b" ds0_b ds1_b ds2_b
30703086
3071- Note that this is consistent with pandas. These two calls produce
3072- the same bar plot structure::
3087+ .. code-block::
30733088
3074- grouped_bar(x, array, group_labels=group_labels)
3075- pd.DataFrame(array, index=x, columns=group_labels).plot.bar()
3089+ x = ["a", "b"]
3090+ dataset_labels = ["dataset_0", "dataset_1", "dataset_2"]
3091+ array = np.random.random((2, 3))
30763092
3093+ Note that this is consistent with pandas. These two calls produce
3094+ the same bar plot structure::
30773095
3078- An iterable of array-like: The iteration runs over the groups.
3079- Each individual array-like is the list of label values for that group.
3096+ grouped_bar(x, array, labels=dataset_labels)
3097+ pd.DataFrame(array, index=x, columns=dataset_labels).plot.bar()
30803098
30813099 group_spacing : float
30823100 The space between two bar groups in units of bar width.
@@ -3091,7 +3109,8 @@ def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
30913109 Note: The "other" label dimension are the group labels, which
30923110 can be set via *x*.
30933111
3094- orientation : {"vertical", "horizontal"}, default: vertical
3112+ orientation : {"vertical", "horizontal"}, default: "vertical"
3113+ The direction of the bars.
30953114
30963115 colors : list of :mpltype:`color`, optional
30973116 A sequence of colors to be cycled through and used to color bars
@@ -3107,7 +3126,12 @@ def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
31073126
31083127 Returns
31093128 -------
3110- A list of `.BarContainer` instances, one for each dataset.
3129+ list of `.BarContainer`
3130+ The results of the individual `~.Axes.bar` calls for each dataset.
3131+
3132+ .. warning::
3133+ The return type is provisional and will likely be replaced
3134+ by a more convenient object.
31113135
31123136 """
31133137if hasattr (heights ,'keys' ):