matplotlib.pyplot.grouped_bar#

matplotlib.pyplot.grouped_bar(heights, *, positions=None, group_spacing=1.5, bar_spacing=0, tick_labels=None, labels=None, orientation='vertical', colors=None, **kwargs)[source]#

绘制分组柱状图。

3.11 版本新增: 该 API 目前仍为试验性。我们可能会根据用户反馈对某些方面进行微调。

分组柱状图用于可视化一组分类数据集。数据集中的每个值都属于一个特定的类别，且这些类别在所有数据集中保持一致。类别通常具有字符串名称，也可以是日期或索引键。每个数据集中的值由一组相同颜色的柱形表示。所有数据集的柱形按其共享的类别进行分组。类别名称被绘制为每个柱形组的刻度标签。每个数据集都有独特的柱形颜色，并可选择性地设置一个用于图例的标签。

示例

grouped_bar([dataset_0, dataset_1, dataset_2],
            tick_labels=['A', 'B'],
            labels=['dataset 0', 'dataset 1', 'dataset 2'])

(源代码, 2x.png, png)

参数:
heights类数组列表、类数组字典、二维数组或 pandas.DataFrame

所有 x 轴和分组的高度。必须满足以下形式之一：

  • 类数组列表：数据集列表，每个数据集必须具有相同数量的元素。

    #           category_A, category_B
dataset_0 = [value_0_A, value_0_B]
dataset_1 = [value_1_A, value_1_B]
dataset_2 = [value_2_A, value_2_B]

    调用示例

    grouped_bar([dataset_0, dataset_1, dataset_2])

  • 类数组字典：从名称到数据集的映射。每个数据集（字典的值）必须具有相同数量的元素。

    调用示例

    data_dict = {'ds0': dataset_0, 'ds1': dataset_1, 'ds2': dataset_2}
grouped_bar(data_dict)

    名称将被用作 labels（标签），即这等同于

    grouped_bar(data_dict.values(), labels=data_dict.keys())

    使用字典输入时，不能显式传入 labels。

  • 二维数组：行表示类别，列表示不同的数据集。

                dataset_0 dataset_1 dataset_2
category_A    ds0_a     ds1_a     ds2_a
category_B    ds0_b     ds1_b     ds2_b

    调用示例

    categories = ["A", "B"]
dataset_labels = ["dataset_0", "dataset_1", "dataset_2"]
array = np.random.random((2, 3))
grouped_bar(array, tick_labels=categories, labels=dataset_labels)

  • 一个 pandas.DataFrame。

    索引（index）用于类别，列（columns）用于数据集。

    df = pd.DataFrame(
    np.random.random((2, 3)),
    index=["A", "B"],
    columns=["dataset_0", "dataset_1", "dataset_2"]
)
grouped_bar(df)

    即这等同于

    grouped_bar(df.to_numpy(), tick_labels=df.index, labels=df.columns)

    注意 grouped_bar(df) 生成的图与 df.plot.bar() 在结构上是等效的。

positions类数组，可选

柱形组的中心位置。数值必须等距。如果不提供，则使用整数序列 0, 1, 2, ...。

tick_labels字符串列表，可选

类别标签，放置在柱形组中心 positions 的刻度上。如果未设置，则坐标轴刻度（位置和标签）保持不变。

labels字符串列表, 可选

数据集的标签，即同一组内的柱形标识。这些将显示在图例中。

group_spacing浮点数，默认：1.5

两个柱形组之间的间距，以柱宽为单位。

默认值 1.5 意味着柱形组之间存在 1.5 倍柱宽的间隙。

bar_spacing浮点数，默认：0

柱形之间的间距，以柱宽为单位。

orientation{"vertical", "horizontal"}，默认："vertical"

柱形的方向。

colors颜色列表，可选

用于循环并为不同数据集的柱形着色的颜色序列。该序列的长度不必与所提供的 y 数据集数量完全相同，若长度不足，颜色将从头开始循环。

如果未指定，将使用 Axes 属性循环中的颜色。

**kwargsRectangle 属性

应用于所有柱形的属性。以下属性额外接受与 heights 中数据集对应的值序列

  • edgecolor

  • facecolor

  • linewidth

  • linestyle

  • hatch

属性

描述

agg_filter

一个过滤函数，它接受一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组以及图像左下角的两个偏移量

alpha

浮点数或 None

angle

未知

animated

布尔值

antialiased 或 aa

布尔值或 None

bounds

(左，下，宽，高)

capstyle

CapStyle 或 {'butt', 'projecting', 'round'}

clip_box

BboxBase 或 None

clip_on

布尔值

clip_path

Patch 或 (Path, Transform) 或 None

color

color

edgecolor 或 ec

颜色 或 None

edgegapcolor

颜色 或 None

facecolor 或 fc

颜色 或 None

figure

Figure 或 SubFigure

fill

布尔值

gid

str

hatch

{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}

hatch_linewidth

未知

hatchcolor

color 或 'edge' 或 None

height

未知

in_layout

布尔值

joinstyle

JoinStyle 或 {'miter', 'round', 'bevel'}

label

object

linestyle 或 ls

{'-', '--', '-.', ':', '', ...} 或 (offset, on-off-seq)

linewidth 或 lw

浮点数或 None

mouseover

布尔值

path_effects

AbstractPathEffect 列表

picker

None 或 布尔值 或 浮点数 或 可调用对象

rasterized

布尔值

sketch_params

(scale: 浮点数, length: 浮点数, randomness: 浮点数)

snap

布尔值或 None

transform

变换

url

str

visible

布尔值

width

未知

x

未知

xy

(浮点数, 浮点数)

y

未知

zorder

浮点数
返回:
_GroupedBarReturn

一个试验性的结果对象。这将在未来进行完善。目前，返回对象保证提供的 API 仅限于

  • 属性 bar_containers，它是一个 BarContainer 列表，即每个数据集调用 bar 的结果。

  • 一个 remove() 方法，用于从坐标轴中移除所有柱形。另请参见 Artist.remove()。

另请参阅

bar

用于柱状图的底层 API，具有更高的自由度，如可定制单个柱形的大小和颜色。

备注

注意

这是 axes.Axes.grouped_bar 的 pyplot 包装器。

为了更好地理解，我们对比 grouped_bar 与 bar 和 boxplot 的 API。

与 bar() 的比较

grouped_bar 在某些方面有意偏离了 bar API。bar(x, y) 是一个底层 API，它在明确的位置 x 放置高度为 y 的柱形。它还允许指定单个柱形的宽度和颜色。这种详细的控制和灵活性在绘制多数据集的分组柱状图时难以管理且通常是不必要的。因此，grouped_bar 专注于将柱状图抽象为分类数据的可视化工具。

以下示例有助于从 bar 过渡到 grouped_bar。

由于分类的存在，位置不再被强调，默认使用整数值。如果您曾经使用 range(N) 作为位置，现在可以省略该值。

bar(range(N), heights)
grouped_bar([heights])

如果需要，位置仍可通过关键字参数传递。

bar(x, heights)
grouped_bar([heights], positions=x)

在 bar 中放置类别标签可以使用 tick_label 参数，或者使用类别名称列表作为 x。grouped_bar 期望通过 tick_labels 参数传入。

bar(range(N), heights, tick_label=["A", "B"])
bar(["A", "B"], heights)
grouped_bar([heights], tick_labels=["A", "B"])

显示在图例中的数据集标签仍通过 label 参数传入。

bar(..., label="dataset")
grouped_bar(..., label=["dataset"])

与 boxplot() 的比较

grouped_bar 和 boxplot 都可视化来自多个数据集的分类数据。tick_labels 和 positions 的基本 API 是相同的，因此您可以轻松切换：将所有单独值绘制为 grouped_bar，或将每个类别的统计分布绘制为 boxplot。

grouped_bar(values, positions=..., tick_labels=...)
boxplot(values, positions=..., tick_labels=...)

使用 matplotlib.pyplot.grouped_bar 的示例#

锥形图

锥形图