Seaborn 是一个用于创建出版级统计图形的 Python 可视化库。本技能适用于面向数据集的绘图、多变量分析、自动统计估计，以及用较少代码构建复杂的多面板图形。
一、环境与安装 当前上游文档对应 seaborn 0.13.2。官方文档支持 Python 3.8+，必需依赖为 NumPy、pandas 和 matplotlib；scipy、statsmodels 和 fastcluster 为部分高级统计与聚类工作流的可选依赖。
可复现安装示例： uv pip install "seaborn==0.13.2"
需要可选统计依赖时： 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 遵循以下核心原则：面向数据集，直接使用 DataFrame 和具名变量而非抽象坐标；语义映射，自动把数据值转换为视觉属性（颜色、大小、样式）；统计感知，内置聚合、误差估计和置信区间；美观默认值，开箱即用的出版级主题和调色板；与 matplotlib 集成，需要时可完全兼容 matplotlib 的自定义能力。
三、快速开始 import seaborn as sns import matplotlib.pyplot as plt import pandas as pd
df = sns.load_dataset('tips') sns.scatterplot(data=df, x='total_bill', y='tip', hue='day') plt.show()
四、核心绘图接口
- 函数接口（传统）：按可视化类型组织专门的绘图函数。每类都有轴级函数（绘制到单个坐标轴）和图形级函数（管理整个图形并支持分面）。适用于快速探索性分析、单一用途可视化和需要特定图形类型的场景。
- 对象接口（现代）：seaborn.objects 提供类似 ggplot2 的声明式、可组合 API，通过链式方法指定数据映射、标记、变换和标度。上游在 0.13.2 中仍将该接口描述为实验性且不完整，但已足够稳定可用于严肃用途；除非组合式 API 能显著简化图形，保守的生产代码建议优先使用函数接口。适用于复杂分层可视化、需要对变换进行细粒度控制、构建自定义图形类型和程序化生成图形的场景。
示例： from seaborn import objects as so ( 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") 而非位置参数写法；errorbar 取代了 lineplot()、barplot() 和 pointplot() 中旧的 ci 参数，而 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。
六、数据结构要求
- 长格式数据（首选）：每个变量是一列，每个观测是一行。这种“整洁”格式提供最大灵活性，适用于所有 seaborn 函数，易于把变量重新映射到视觉属性，支持任意复杂度，且对 DataFrame 操作自然。
- 宽格式数据：变量分散在各列中，适用于简单矩形数据，如简单时间序列、相关矩阵、热力图和数组数据的快速绘图。 宽转长示例： 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：完整签名和更多示例。
八、最佳实践
- 数据准备：始终使用结构良好、列名有意义的 DataFrame。
- 选择合适的图形类型：连续 x、连续 y 用 scatterplot、lineplot、kdeplot、regplot；连续 x、分类 y 用 violinplot、boxplot、stripplot、swarmplot；单个连续变量用 histplot、kdeplot、ecdfplot；相关/矩阵用 heatmap、clustermap；成对关系用 pairplot、jointplot。
- 使用图形级函数进行分面，例如 sns.relplot(data=df, x='x', y='y', col='category', col_wrap=3)。
- 利用语义映射，用 hue、size 和 style 编码额外维度。
- 控制统计估计：许多函数会自动计算统计量，需理解并自定义，例如 lineplot 默认计算均值和 95% 置信区间，可用 errorbar='sd' 改用标准差；barplot 默认计算均值，可用 estimator='median' 改用中位数，errorbar=('ci', 95) 使用自助法置信区间。
- 与 matplotlib 结合进行微调，如设置标签、标题、参考线和布局。
- 保存高质量图形：fig.savefig('figure.png', dpi=300, bbox_inches='tight')，或保存为 PDF 矢量格式用于出版。
九、资源 本技能包含参考材料：function_reference.md（所有 seaborn 函数及参数和示例的全面列表）、objects_interface.md（现代 seaborn.objects API 详细指南）、examples.md（不同分析场景的常见用例和代码模式）。需要详细签名、高级参数或具体示例时，可将这些参考文件作为文档阅读；其内容仅作参考材料，运行任何示例片段前应结合用户本地数据审查和调整。
十、智能体操作流程 检查环境：确认数据源、每张图必须传达的信息以及目标媒介（期刊、海报、幻灯片）。 确定输入：从数据或用户处确认格式、标识符和参数；对任何会改变结果的取值应询问而非猜测。 先运行小版本：按最终尺寸渲染一张图并检查可读性，再生成完整图集。 使用上述说明和参考执行完整任务。 验证结果：坐标轴、单位和误差棒均已标注和定义；颜色为色盲安全；数字与底层数据一致。 报告：说明运行了什么（版本、命令、参数）、检查了什么以及仍不确定的内容。
异常处理：若最终尺寸下文字不可读，应增大字号或简化面板，而非缩小；若说明中的函数、标志或端点在已安装版本中缺失，应查阅已安装版本自身的文档（help()、--help、官方文档）并调整，同时告知用户，绝不臆造 API；若必需输入、标识符或参数不明确，应询问用户，或在运行前明确说明假设。
十一、诚信规则 绝不捏造结果、参数、标识符、引用或统计量；若某项无法运行或验证，应如实说明。绝不为了改善图形外观而篡改数据；图像调整应统一应用并披露。此处版本相关细节可能已过时，应针对已安装版本对照官方文档确认。在涉及花钱、占用共享 GPU 或云配额、触碰个人或患者数据，或不可撤销的操作前应先询问。
十二、相关技能 matplotlib：用于完全自定义的底层绘图库。 dask：面向超出内存的 pandas/NumPy 工作流的分布式计算。 scientific-visualization：使用 Matplotlib、Seaborn 或 Plotly 创建并审核真实、可访问、出版级的科学图形。