seaborn.violinplot

seaborn.violinplot(data=None, *, x=None, y=None, hue=None, order=None, hue_order=None, orient=None, color=None, palette=None, saturation=0.75, fill=True, inner='box', split=False, width=0.8, dodge='auto', gap=0, linewidth=None, linecolor='auto', cut=2, gridsize=100, bw_method='scott', bw_adjust=1, density_norm='area', common_norm=False, hue_norm=None, formatter=None, log_scale=None, native_scale=False, legend='auto', scale=<deprecated>, scale_hue=<deprecated>, bw=<deprecated>, inner_kws=None, ax=None, **kwargs)

绘制一个代表 KDE 的补丁，并添加观察值或箱线图统计信息。

小提琴图与箱线图有类似的作用。它显示了根据一个（或多个）变量进行分组后数据点的分布。与箱线图不同，每个小提琴图都是使用对潜在分布的核密度估计绘制的。

有关更多信息，请参阅 教程。

注意

默认情况下，此函数将一个变量视为分类变量，并在相关轴上以序数位置（0、1、…n）绘制数据。从版本 0.13.0 开始，可以通过设置 native_scale=True 来禁用此功能。

参数：

dataDataFrame、Series、dict、array 或 array 列表

用于绘图的数据集。如果 x 和 y 不存在，则将其解释为宽格式。否则，预计它将是长格式。

x、y、hue在 data 中的变量名称或向量数据

用于绘制长格式数据的输入。请参阅示例以了解解释。

order、hue_order字符串列表

以其绘制分类级别的顺序；否则，级别将从数据对象中推断出来。

orient“v” | “h” | “x” | “y”

绘图的方向（垂直或水平）。这通常是根据输入变量的类型推断出来的，但当 x 和 y 都是数值或绘制宽格式数据时，可以使用它来消除歧义。

v0.13.0 版本中的更改: 添加了 ‘x’/’y’ 作为选项，等效于 ‘v’/’h’。

colormatplotlib 颜色

绘图中元素的单一颜色。

palette调色板名称、列表或字典

用于 hue 变量的不同级别的颜色。应该是可以被 color_palette() 解释的东西，或一个将色调级别映射到 matplotlib 颜色的字典。

saturation浮点数

绘制填充颜色的原始饱和度的比例。大的色块通常使用不饱和的颜色看起来更好，但如果希望颜色与输入值完全匹配，则将其设置为 1。

fill布尔值

如果为 True，则使用实心色块。否则，以线框形式绘制。

v0.13.0 版本中的新增功能。

inner {“box”, “quart”, “point”, “stick”, None}

小提琴内部数据的表示形式。以下之一

• "box"：绘制一个微型箱线图

• "quart"：显示数据的四分位数

• "point" 或 "stick"：显示每个观察值

split布尔值

显示一个未镜像的分布，在使用 hue 时交替显示两侧。

v0.13.0 版本中的更改: 以前，此选项需要一个 hue 变量，且该变量恰好具有两个级别。

width浮点数

分配给方向轴上每个元素的宽度。当 native_scale=True 时，它相对于本机尺度中两个值之间的最小距离。

dodge“auto” 或布尔值

当使用色调映射时，元素是否应该沿方向轴缩小和移动以消除重叠。如果为 "auto"，则当方向变量与分类变量交叉时设置为 True，否则设置为 False。

0.13.0 版本中的更改: 添加了 "auto" 模式作为新的默认模式。

gap浮点数

沿方向轴收缩此比例因子以在躲避的元素之间添加间隙。

v0.13.0 版本中的新增功能。

linewidth浮点数

构成绘图元素的线的宽度。

linecolor颜色

当 fill 为 True 时，用于线元素的颜色。

v0.13.0 版本中的新增功能。

cutfloat

密度延伸到极端数据点之外的距离，以带宽为单位。设置为 0 表示将小提琴限制在数据范围内。

gridsizeint

用于评估 KDE 的离散网格中的点数。

bw_method{“scott”, “silverman”, float}

计算核带宽时使用的参考规则名称或比例因子。实际核大小将通过将比例因子乘以每组数据中的标准差来确定。

v0.13.0 版本中的新增功能。

bw_adjust: float

用于调整带宽的因子，以实现更多或更少的平滑效果。

v0.13.0 版本中的新增功能。

density_norm{“area”, “count”, “width”}

用于对每个密度进行归一化以确定小提琴宽度的方法。如果为 area，每个小提琴将具有相同的面积。如果为 count，宽度将与观察次数成正比。如果为 width，每个小提琴将具有相同的宽度。

v0.13.0 版本中的新增功能。

common_normbool

当 True 时，对所有小提琴的密度进行归一化。

v0.13.0 版本中的新增功能。

hue_norm元组或 matplotlib.colors.Normalize 对象

当 hue 为数值时，应用于 hue 变量的颜色映射的数据单位归一化。如果 hue 为类别，则不相关。

版本 v0.12.0 中新增。

formatter可调用对象

用于将类别数据转换为字符串的函数。影响分组和刻度标签。

v0.13.0 版本中的新增功能。

log_scale布尔值或数字，或布尔值或数字对

将轴刻度设置为对数。单个值设置绘图中任何数值轴的数据轴。一对值独立设置每个轴。数值被解释为所需的基数（默认值为 10）。当 None 或 False 时，seaborn 委托给现有轴刻度。

v0.13.0 版本中的新增功能。

native_scalebool

当为 True 时，类别轴上的数值或日期时间值将保持其原始缩放，而不是转换为固定索引。

v0.13.0 版本中的新增功能。

legend“auto”, “brief”, “full”, or False

如何绘制图例。如果为 “brief”，则数值 hue 和 size 变量将用均匀间隔值的样本表示。如果为 “full”，每个组将在图例中获得一个条目。如果为 “auto”，将根据级别数量选择简要或完整表示。如果为 False，不会添加图例数据，也不会绘制图例。

v0.13.0 版本中的新增功能。

scale{“area”, “count”, “width”}

自 v0.13.0 版本起已弃用： 请参见 density_norm。

scale_huebool

自 v0.13.0 版本起已弃用： 请参见 common_norm。

bw{‘scott’, ‘silverman’, float}

自 v0.13.0 版本起已弃用： 请参见 bw_method 和 bw_adjust。

inner_kws键值映射字典

传递给“内部”绘图的关键字参数，传递给以下其中一个

• matplotlib.collections.LineCollection（使用 inner="stick"）

• matplotlib.axes.Axes.scatter()（使用 inner="point"）

• matplotlib.axes.Axes.plot()（使用 inner="quart" 或 inner="box"）

此外，使用 inner="box" 时，关键字 box_width、whis_width 和 marker 会针对“箱线图”组件进行特殊处理。

v0.13.0 版本中的新增功能。

axmatplotlib Axes

用于绘制图形的 Axes 对象，否则使用当前 Axes。

kwargs键值映射

传递给小提琴补丁的关键字参数，传递给 matplotlib.axes.Axes.fill_between()。

返回:

axmatplotlib Axes

返回绘制了图形的 Axes 对象。

另请参见

boxplot

具有类似 API 的传统箱线图。

stripplot

一个散点图，其中一个变量是类别。可以与其他绘图结合使用以显示每个观察值。

swarmplot

一个类别散点图，其中点不重叠。可以与其他绘图结合使用以显示每个观察值。

catplot

将类别图与 FacetGrid 结合使用。

示例

默认的小提琴图以两种方式表示分布：一个显示对称核密度估计 (KDE) 的补丁，以及箱线图的四分位数/须线。

df = sns.load_dataset("titanic")
sns.violinplot(x=df["age"])

在双变量图中，一个变量将“分组”，以便绘制多个小提琴。

sns.violinplot(data=df, x="age", y="class")

默认情况下，绘图的方向由变量类型决定，优先按类别变量分组。

sns.violinplot(data=df, x="class", y="age", hue="alive")

传递 fill=False 绘制线艺小提琴。

sns.violinplot(data=df, x="class", y="age", hue="alive", fill=False)

绘制“分割”小提琴以占用更少的空间，并且只显示数据四分位数。

sns.violinplot(data=df, x="class", y="age", hue="alive", split=True, inner="quart")

在错开的小提琴之间添加一个小间隙。

sns.violinplot(data=df, x="class", y="age", hue="alive", split=True, gap=.1, inner="quart")

从版本 0.13.0 开始，可以“分割”单个小提琴。

sns.violinplot(data=df, x="class", y="age", split=True, inner="quart")

通过设置 inner="stick" 或 inner="point" 来表示分布内的每个观察值。

sns.violinplot(data=df, x="age", y="deck", inner="point")

将每个小提琴的宽度归一化为表示观察次数。

sns.violinplot(data=df, x="age", y="deck", inner="point", density_norm="count")

默认情况下，KDE 将平滑到观察数据的极值之外；设置 cut=0 以阻止这种情况。

sns.violinplot(data=df, x="age", y="alive", cut=0, inner="stick")

bw_adjust 参数控制平滑程度。

sns.violinplot(data=df, x="age", y="alive", bw_adjust=.5, inner="stick")

默认情况下，小提琴在类别刻度上的固定位置绘制，即使分组变量是数值。从版本 0.13.0 开始，传递 native_scale=True 参数以保留两个轴上的原始刻度。

sns.violinplot(x=df["age"].round(-1) + 5, y=df["fare"], native_scale=True)

使用类别刻度时，formatter 参数接受一个函数来定义类别。

decades = lambda x: f"{int(x)}–{int(x + 10)}"
sns.violinplot(x=df["age"].round(-1), y=df["fare"], formatter=decades)

默认情况下，“内部”表示随 linewidth 和 linecolor 参数进行缩放。

sns.violinplot(data=df, x="age", linewidth=1, linecolor="k")

使用 inner_kws 将参数直接传递给内部绘图函数。

sns.violinplot(data=df, x="age", inner_kws=dict(box_width=15, whis_width=2, color=".8"))