seaborn

Seaborn 统计可视化

概述

Seaborn 是一个 Python 可视化库，可用于创建适合发表的统计图形。使用此技能可通过少量代码绘制面向数据集的图表、进行多变量分析、自动统计估算，以及创建复杂的多面板图形。

环境与安装

当前上游文档针对 seaborn 0.13.2。官方文档支持 Python 3.8+，并要求安装 NumPy、pandas 和 matplotlib；在某些高级统计和聚类工作流中，scipy、statsmodels 和 fastcluster 为可选依赖。

# Reproducible install for examples in this skill
uv pip install "seaborn==0.13.2"

# Include optional statistical dependencies when needed
uv pip install "seaborn[stats]==0.13.2"

推荐导入方式：

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns
import seaborn.objects as so

sns.load_dataset() 会下载公开示例数据（如果数据尚未缓存）。对于私有、受监管或离线工作，请使用 pandas 显式加载本地文件，并将生成的 DataFrame 传递给 seaborn。

设计理念

Seaborn 遵循以下核心原则：

1. 面向数据集：直接使用 DataFrame 和命名变量，而非抽象坐标
2. 语义映射：自动将数据值映射为视觉属性（颜色、大小、样式）
3. 统计感知：内置聚合、误差估算和置信区间
4. 美观的默认设置：开箱即用的适合发表的主题和调色板
5. 与 matplotlib 集成：需要时可完全兼容 matplotlib 自定义设置

快速入门

import seaborn as sns
import matplotlib.pyplot as plt
import pandas as pd

# Load example dataset
df = sns.load_dataset('tips')

# Create a simple visualization
sns.scatterplot(data=df, x='total_bill', y='tip', hue='day')
plt.show()

核心绘图接口

函数接口（传统）

函数接口提供按可视化类型组织的专用绘图函数。每个类别都包含 坐标轴级 函数（在单个坐标轴上绘图）和 图形级 函数（通过分面管理整个图形）。

适用场景：

• 快速探索性分析
• 单一用途的可视化
• 需要特定图表类型时

Objects 接口（现代）

seaborn.objects 接口提供了一种声明式、可组合的 API，类似 ggplot2。通过链式调用方法来构建可视化，以指定数据映射、标记、变换和刻度。上游文档仍将此接口描述为 0.13.2 中实验性且不完整的接口，尽管它已足以用于严肃的工作；除非组合式 API 能显著简化图表，否则在保守的生产代码中优先使用函数接口。

适用场景：

• 复杂的分层可视化
• 需要精细控制变换时
• 构建自定义图表类型
• 以编程方式生成图表

from seaborn import objects as so

# Declarative syntax
(
    so.Plot(data=df, x='total_bill', y='tip')
    .add(so.Dot(), color='day')
    .add(so.Line(), so.PolyFit())
)

当前 API 注意事项

Seaborn 0.12 和 0.13 更改了几种常见的绘图模式：

• 现在大多数绘图函数都要求变量使用关键字参数。优先使用 sns.scatterplot(data=df, x="x", y="y")，而不是位置参数形式的 sns.scatterplot(df["x"], df["y"])。
• lineplot()、barplot() 和 pointplot() 中的旧参数 ci 已由 errorbar 取代。regplot() 和 lmplot() 等回归函数仍使用 ci。
• 分类图在 0.13 中经过重写。如果数值或日期时间类别应保留其原始刻度，而不是使用序数位置，请使用 native_scale=True。
• 在分类函数中，不指定 hue 就传入 palette 已弃用。如果每个类别都应使用不同颜色，请指定冗余的 hue（例如 hue="day"），并设置 legend=False。
• 优先使用重命名后的参数：使用 violinplot(density_norm=..., common_norm=...) 代替 scale/scale_hue，使用 boxenplot(width_method=...) 代替 scale，并使用 barplot(err_kws=...) 代替 errcolor/errwidth。

数据结构要求

长格式数据（推荐）

每个变量对应一列，每条观测对应一行。这种“整洁”格式具有最大的灵活性：

# Long-form structure
   subject  condition  measurement
0        1    control         10.5
1        1  treatment         12.3
2        2    control          9.8
3        2  treatment         13.1

优点：

• 适用于所有 seaborn 函数
• 易于将变量重新映射到视觉属性
• 支持任意复杂度
• 适用于 DataFrame 操作

宽格式数据

变量分布在多个列中。适用于简单的矩形数据：

# Wide-form structure
   control  treatment
0     10.5       12.3
1      9.8       13.1

使用场景：

• 简单的时间序列
• 相关矩阵
• 热图
• 快速绘制数组数据

将宽格式转换为长格式：

df_long = df.melt(var_name='condition', value_name='measurement')

绘图函数、网格、调色板和图案

• references/plotting_functions.md：按类别划分的关系图、分布图、分类图、回归图和矩阵图。
• references/grids_and_levels.md：FacetGrid、 PairGrid、JointGrid，以及图级函数与坐标轴级函数的区别。
• references/palettes_and_theming.md：调色板 选择（包括对色盲友好的选项）、主题、上下文和样式。
• references/patterns_and_troubleshooting.md： 常见用法和 seaborn 错误的实际含义。
• references/objects_interface.md：seaborn.objects 接口。references/function_reference.md 和 references/examples.md：完整的函数签名和更多示例。

最佳实践

1. 准备数据

始终使用结构良好的 DataFrame，并为列设置有意义的名称：

# Good: Named columns in DataFrame
df = pd.DataFrame({'bill': bills, 'tip': tips, 'day': days})
sns.scatterplot(data=df, x='bill', y='tip', hue='day')

# Avoid: Unnamed arrays
sns.scatterplot(x=x_array, y=y_array)  # Loses axis labels

2. 选择合适的图表类型

连续 x，连续 y： scatterplot、lineplot、kdeplot、regplot 连续 x，分类 y： violinplot、boxplot、stripplot、swarmplot 单个连续变量： histplot、kdeplot、ecdfplot 相关性／矩阵： heatmap、clustermap 成对关系： pairplot、jointplot

3. 使用图级函数进行分面

# Instead of manual subplot creation
sns.relplot(data=df, x='x', y='y', col='category', col_wrap=3)

# Not: Creating subplots manually for simple faceting

4. 利用语义映射

使用 hue、size 和 style 编码额外维度：

sns.scatterplot(data=df, x='x', y='y',
                hue='category',      # Color by category
                size='importance',    # Size by continuous variable
                style='type')         # Marker style by type

5. 控制统计估计

许多函数会自动计算统计数据。请了解并自定义这些计算：

# Lineplot computes mean and 95% CI by default
sns.lineplot(data=df, x='time', y='value',
             errorbar='sd')  # Use standard deviation instead

# Barplot computes mean by default
sns.barplot(data=df, x='category', y='value',
            estimator='median',  # Use median instead
            errorbar=('ci', 95))  # Bootstrapped CI

6. 与 Matplotlib 结合使用

Seaborn 可与 matplotlib 无缝集成，便于进行精细调整：

ax = sns.scatterplot(data=df, x='x', y='y')
ax.set(xlabel='Custom X Label', ylabel='Custom Y Label',
       title='Custom Title')
ax.axhline(y=0, color='r', linestyle='--')
plt.tight_layout()

7. 保存高质量图表

fig = sns.relplot(data=df, x='x', y='y', col='group')
fig.savefig('figure.png', dpi=300, bbox_inches='tight')
fig.savefig('figure.pdf')  # Vector format for publications

资源

此技能包含可供深入探索的参考资料：

references/

• function_reference.md - seaborn 所有函数及其参数和示例的综合列表
• objects_interface.md - 现代 seaborn.objects API 的详细指南
• examples.md - 适用于不同分析场景的常见用例和代码模式

需要详细的函数签名、高级参数或具体示例时，请将这些参考文件作为文档阅读。这些内容仅供参考；运行任何示例代码片段前，请先检查并根据用户的本地数据进行调整。

Agent 操作流程

1. 检查环境。 确认数据源、每张图必须传达的信息，以及目标媒介（期刊、海报、幻灯片）。
2. 明确输入。 确认数据或用户提供的格式、标识符和参数。任何会改变结果的值都应询问，而非猜测。
3. 先运行小规模版本。 按最终尺寸渲染一张图，并在生成完整图集前检查其可读性。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 坐标轴、单位和误差线均已标注和定义；颜色对色盲友好；数值与底层数据一致。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果发生这种情况	请这样做
最终尺寸下文字无法辨读	增大字号或简化面板，而不是缩小字号。
这些说明中提到的函数、标志或端点在已安装版本中不存在	查看已安装版本自己的文档（help()、--help、官方文档），调整做法，并告知用户。绝不编造 API。
必需的输入、标识符或参数存在歧义	询问用户，或在运行前明确说明所作的假设。

诚信规则

• 绝不编造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 绝不为了改善图表外观而修改数据；应统一应用图像调整并披露这些调整。
• 此处与版本相关的细节可能已过时：请对照已安装版本的官方文档进行确认。
• 对于需要付费、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，务必先询问。

相关技能

• matplotlib：用于完全自定义的底层绘图库。
• dask：用于处理数据规模超过内存的 pandas/NumPy 工作流的分布式计算工具。
• scientific-visualization：使用 Matplotlib、Seaborn 或 Plotly 创建并审核真实、易访问、可用于发表的科学图表。