v0.13.0 (2023年9月)#

这是一个重大版本，包含许多重要的新功能和变化。亮点是对 seaborn 的分类绘图功能进行了重大改进，赋予了它们许多新功能，并更好地将它们的 API 与库的其他部分对齐。还提供了对 polars 等替代数据框库的临时支持，为 objects.Plot 引入了新的主题和显示配置系统，以及许多较小的错误修复和增强功能。

建议进行更新，但鼓励用户仔细检查使用分类函数的现有代码的输出，并且他们应该注意一些弃用和有意更改的默认图表外观（请参见下面的 API 和 Defaults 标签的注释）。

分类图的主要增强功能#

Seaborn 的 分类函数 已针对此版本进行了完全重写。这提供了机会来解决一些长期存在的怪癖，以及添加许多虽小但非常需要的功能和增强。

支持数值和日期时间数据#

|功能|

分类函数历来将 所有 数据视为分类数据，即使数据具有数值或日期时间类型。现在可以通过新的 native_scale 参数来控制这一点。默认值仍然是 False，以保留现有行为。但如果设置 native_scale=True，值将按照其他 seaborn 或 matplotlib 函数的方式处理。元素宽度将根据分类轴上两个唯一值之间的最小距离来确定。

此外，虽然 seaborn 之前在内部确定分类值到顺序位置的映射，但现在这一任务被委托给了 matplotlib。这一变化对用户来说应该基本上是透明的，但在大多数情况下，分类图（即使使用 native_scale=False）将更好地与其他 seaborn 或 matplotlib 函数添加的艺术家对齐，并且 matplotlib 的交互机制将更好地工作。

颜色默认值和规范的更改#

API |默认值|

分类函数现在更像 seaborn 的其他部分，即它们将生成一个以单一主色为主的图，除非分配了 hue 变量。以前，会有一个隐含的冗余颜色映射（例如，箱线图中的每个箱子都会从默认调色板中获得单独的颜色）。要保留之前的行为，请显式分配一个冗余的 hue 变量（例如，boxplot(data, x="x", y="y", hue="x")）。

两个相关的特殊颜色规范已被弃用，但它们将继续工作（带有警告）一个发布周期：

  • 传递一个 palette 而不显式分配 hue 不再被支持（请改为添加一个显式冗余的 hue 分配）。

  • 在分配 hue 时传递 color 以生成渐变不再支持（请改用 palette="dark:{color}" 或 palette="light:{color}"）。

最后，与其他 seaborn 函数一样，默认调色板现在取决于变量类型，数值数据将使用顺序调色板。要保留之前的行为，请传递一个定性调色板的名称（例如，palette="deep" 表示 seaborn 的默认调色板）。相应地，这些函数增加了一个参数来控制数值颜色映射（hue_norm）。

其他功能、增强和更改#

以下更新适用于多个分类功能。

  • |功能| 所有函数现在接受一个 legend 参数，该参数可以是布尔值（用于抑制图例）或 {"auto", "brief", "full"} 之一，以控制数值颜色映射中图例显示的信息量。

  • |功能| 所有函数现在都接受一个可调用的 formatter 参数，用于控制数据的字符串表示。

  • |功能| 所有绘制实心区域的函数现在都接受一个布尔型 fill 参数，当设置为 False 时，将绘制线性艺术元素。

  • |功能| 所有支持躲避的功能现在都有一个额外的 gap 参数，可以设置为非零值以在躲避的元素之间留出空间。

  • |功能| boxplot(), boxenplot(), 和 violinplot() 函数现在支持一个单独的 linecolor 参数。

  • |增强| dodge 的默认值已从 True 更改为 "auto"。使用 "auto" 时，只有在至少有一组元素会重叠时，元素才会躲避。

  • |增强| 当图形的值轴具有非线性刻度时，统计操作（例如 pointplot() 中的聚合或 violinplot() 中的核密度拟合）现在在该刻度空间中应用。

  • |增强| 所有函数现在都接受一个 log_scale 参数。使用单个参数时，这将设置“值”轴（与分类轴相对）的比例。一个元组将直接设置每个轴（尽管设置对数尺度的分类轴也需要 native_scale=True）。

  • |增强| orient 参数现在接受 "x"/"y" 来指定分类轴，与对象接口匹配。

  • |增强| 分类函数通常更尊重用户提供的额外 matplotlib 关键字参数。

  • API 使用 "gray" 选择一个自动的灰色值来补充主调色板现在已被弃用，取而代之的是 "auto"。

以下更新是针对特定功能的。

  • API |功能| 在 pointplot() 中，现在使用单个 matplotlib.lines.Line2D 艺术家，而不是为点添加单独的 matplotlib.collections.PathCollection 艺术家。因此，现在可以传递额外的关键字参数以完全自定义线条和标记的外观；此外，图例表示也得到了改进。因此，以前仅允许部分自定义的参数（scale、join 和 errwidth）现在已被弃用。旧参数现在将触发详细的警告消息，并提供调整现有代码的说明。

  • API |功能| violinplot() 中的带宽规范现在更好地与 kdeplot() 对齐，因为 bw 参数现在已被弃用，取而代之的是 bw_method 和 bw_adjust。

  • API |增强| 在 boxenplot() 中，箱线图现在在每个尾部使用单独的补丁艺术家绘制。这可能对与底层艺术家交互的代码产生影响，但它为低透明度/未填充的图表生成更好的结果，并支持适当的面积/密度缩放。

  • API |增强| 在 barplot() 中，errcolor 和 errwidth 参数现在已被弃用，取而代之的是更通用的 err_kws 字典。现有参数将继续工作两个版本。

  • API 在 violinplot() 中，scale 和 scale_hue 参数已重命名为 density_norm 和 common_norm，以提高清晰度并反映出在 catplot() 中，现在对色调和分面变量都应用了共同的标准化。

  • API 在 boxenplot() 中，scale 参数已被重命名为 width_method，这是为了在 seaborn 参数中消除 “scale” 含义的混淆而进行的一项更广泛的努力。

  • |默认值| |增强| 当将一个向量传递给 barplot() 或 pointplot() 的 data 参数时，将为向量中的每个条目绘制一个条形或点，而不是绘制一个单一的聚合值。要保留之前的行为，请将向量分配给 y 变量。

  • |默认值| |增强| 在 boxplot() 中，默认的离群点标记现在遵循 matplotlib 的 rcparams，因此可以进行全局自定义。

  • |默认值| |增强| 在使用 violinplot() 时，如果设置 split=True 和 inner="box"，现在会为每个分割的小提琴图绘制一个单独的迷你箱形图。

  • |默认值| |增强| 在 boxenplot() 中，所有图现在都使用一致的亮度渐变来表示不同的箱形级别。这导致现有图形的外观发生变化，但减少了误导结果的可能性。

  • |默认值| |增强| boxenplot() 中的 "area" 缩放现在近似于基础观测值的密度，包括非对称分布。这导致使用 width_method="area" 的图形的外观发生了显著变化，尽管现有的行为定义不明确。

  • |功能| 在 countplot() 中，新的 stat 参数可以用于应用归一化（例如显示 "百分比" 或 "比例"）。

  • |功能| violinplot() 中的 split 参数现在更加通用，可以设置为 True 而不管 hue 变量的级别数量（甚至在没有 hue 的情况下）。这对于显示半小提琴图可能最有用。

  • |功能| 在 violinplot() 中，新的 inner_kws 参数允许对内部艺术家进行额外控制。

  • |增强| 在 catplot() 中不再需要使用 DataFrame，因为现在可以直接传递数据向量。

  • |增强| 在 boxplot() 中，构成每个箱线图的艺术家现在被打包在一个 BoxPlotContainer 中，以便于绘图后的访问。

支持替代的数据框库#

  • |功能| 现在几乎所有函数/对象都使用 数据帧交换协议 来接受来自 pandas 以外库的 DataFrame 对象（例如 polars）。请注意，seaborn 仍会在内部将数据对象转换为 pandas，但此功能将简化其他数据帧库用户的使用代码 (#3369)。

改进了对象接口的配置#

其他更新#

  • |增强| 改进了关系和分类函数的图例显示，以更好地表示用户的额外关键字参数 (#3467)。

  • |增强| 在 ecdfplot() 中，stat="percent" 现在是一个有效选项 (#3336)。

  • |增强| 现在在任何统计操作之前，会丢弃超出比例变换域的数据值（例如，对数比例下的非正值）(#3488)。

  • |增强| 在 histplot() 中，选择默认的箱范围时，现在会忽略无穷值 (#3488)。

  • |增强| 现在可以根据轴的比例在适当的范围内进行统计的通用支持；以前对此的支持是零散的，最多只能用于对数比例 (#3440)。

  • |增强| 更新了 load_dataset() 以使用与 pyiodide 更兼容的方法 (#3234)。

  • API 现在不推荐使用数组类型的调色板。这之前没有被记录为支持的功能，但在一些地方它意外地工作了 (#3452)。

  • API |修复| 在 histplot() 中，binwidth 参数的处理方式已更改，使得当该值不能均匀分割区间范围时，实际的区间宽度将仅近似等于请求的宽度。这修复了一个问题，即由于浮点误差，最大数据值有时会被丢弃 (#3489)。

  • |修复| 在使用非线性比例时修复了 objects.Bar 和 objects.Bars 的宽度 (#3217)。

  • |修复| 解决了 matplotlib 中的一个问题，该问题导致在提供 labels 时 move_legend() 返回错误结果 (#3454)。

  • |修复| 修复了在 v0.12.0 中引入的一个错误，该错误导致 histplot() 添加了一个多余的空 BarContainer (#3246)。

  • |修复| 修复了一个错误，其中 objects.Plot.on() 会覆盖图形的布局引擎 (#3216)。

  • |修复| 修复了在v0.12.0中引入的错误，当使用元组列表作为关键字参数dashes调用:func:lineplot`时，会导致TypeError (:pr:`3316)。

  • |修复| 修复了 PairGrid 中的一个错误，当输入的数据框具有列多索引时会导致异常 (#3407)。

  • |修复| 在使用 pandas 可空 dtypes 时改进了一些边缘情况 (#3394)。