# Seaborn

> Seaborn 是一个 Python 可视化库，用于创建出版级质量的统计图形。当用户需要进行面向数据集的绑图、多变量分析、自动统计估计以及用最少代码创建复杂多面板图形时使用。触发词：Seaborn绑图、统计可视化、数据可视化、seaborn、统计图形、分布图、热力图、分类图、回归图、pairplot、heatmap。

- Skill: `kscz0000/seaborn` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/seaborn`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/seaborn/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: BSD-3-Clause license
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/seaborn

---


# Seaborn 统计可视化

## 何时使用

- 需要直接从表格数据集创建出版级质量的统计图形
- 正在探索多变量关系、分布或分组比较，且绑图代码量最少
- 想要使用 Seaborn 面向数据集的 API 和统计默认设置（基于 matplotlib）

## 概述

Seaborn 是一个 Python 可视化库，用于创建出版级质量的统计图形。本技能适用于面向数据集的绑图、多变量分析、自动统计估计以及用最少代码创建复杂多面板图形。

## 设计理念

Seaborn 遵循以下核心原则：

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

## 快速入门

```python
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。通过链式方法指定数据映射、标记、变换和比例来构建可视化。

**何时使用：**
- 复杂的分层可视化
- 需要对变换进行精细控制时
- 构建自定义图表类型
- 程序化图表生成

```python
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())
)
```

## 按类别分类的绑图函数

### 关系图（变量间关系）

**用途：** 探索两个或多个变量之间的关系

- `scatterplot()` - 将单个观测值显示为点
- `lineplot()` - 显示趋势和变化（自动聚合并计算置信区间）
- `relplot()` - 带自动分面的图形级接口

**关键参数：**
- `x`, `y` - 主变量
- `hue` - 额外分类/连续变量的颜色编码
- `size` - 点/线大小编码
- `style` - 标记/线样式编码
- `col`, `row` - 分面为多个子图（仅限图形级）

```python
# 带多个语义映射的散点图
sns.scatterplot(data=df, x='total_bill', y='tip',
                hue='time', size='size', style='sex')

# 带置信区间的折线图
sns.lineplot(data=timeseries, x='date', y='value', hue='category')

# 分面关系图
sns.relplot(data=df, x='total_bill', y='tip',
            col='time', row='sex', hue='smoker', kind='scatter')
```

### 分布图（单变量和双变量分布）

**用途：** 理解数据分布、形状和概率密度

- `histplot()` - 基于柱状的频率分布，支持灵活分箱
- `kdeplot()` - 使用高斯核的平滑密度估计
- `ecdfplot()` - 经验累积分布（无需调参）
- `rugplot()` - 单个观测值的刻度标记
- `displot()` - 单变量和双变量分布的图形级接口
- `jointplot()` - 带边缘分布的双变量图
- `pairplot()` - 数据集中成对关系的矩阵图

**关键参数：**
- `x`, `y` - 变量（单变量时 y 可选）
- `hue` - 按类别分离分布
- `stat` - 归一化方式："count"、"frequency"、"probability"、"density"
- `bins` / `binwidth` - 直方图分箱控制
- `bw_adjust` - KDE 带宽乘数（值越大越平滑）
- `fill` - 填充曲线下方区域
- `multiple` - 处理 hue 的方式："layer"、"stack"、"dodge"、"fill"

```python
# 带密度归一化的直方图
sns.histplot(data=df, x='total_bill', hue='time',
             stat='density', multiple='stack')

# 带等高线的双变量 KDE
sns.kdeplot(data=df, x='total_bill', y='tip',
            fill=True, levels=5, thresh=0.1)

# 带边缘分布的联合图
sns.jointplot(data=df, x='total_bill', y='tip',
              kind='scatter', hue='time')

# 成对关系图
sns.pairplot(data=df, hue='species', corner=True)
```

### 分类图（跨类别比较）

**用途：** 比较离散类别间的分布或统计量

**分类散点图：**
- `stripplot()` - 带抖动的点，显示所有观测值
- `swarmplot()` - 不重叠的点（蜂群算法）

**分布比较：**
- `boxplot()` - 四分位数和异常值
- `violinplot()` - KDE + 四分位数信息
- `boxenplot()` - 增强型箱线图，适用于较大数据集

**统计估计：**
- `barplot()` - 均值/聚合值及置信区间
- `pointplot()` - 点估计及连接线
- `countplot()` - 每个类别的观测计数

**图形级：**
- `catplot()` - 分面分类图（设置 `kind` 参数）

**关键参数：**
- `x`, `y` - 变量（通常一个为分类变量）
- `hue` - 额外分类分组
- `order`, `hue_order` - 控制类别顺序
- `dodge` - 将 hue 层级并排分离
- `orient` - "v"（垂直）或 "h"（水平）
- `kind` - catplot 的图表类型："strip"、"swarm"、"box"、"violin"、"bar"、"point"

```python
# 显示所有点的蜂群图
sns.swarmplot(data=df, x='day', y='total_bill', hue='sex')

# 带分割比较的小提琴图
sns.violinplot(data=df, x='day', y='total_bill',
               hue='sex', split=True)

# 带误差条的柱状图
sns.barplot(data=df, x='day', y='total_bill',
            hue='sex', estimator='mean', errorbar='ci')

# 分面分类图
sns.catplot(data=df, x='day', y='total_bill',
            col='time', kind='box')
```

### 回归图（线性关系）

**用途：** 可视化线性回归和残差

- `regplot()` - 坐标轴级回归图，包含散点 + 拟合线
- `lmplot()` - 图形级，支持分面
- `residplot()` - 用于评估模型拟合的残差图

**关键参数：**
- `x`, `y` - 回归变量
- `order` - 多项式回归阶数
- `logistic` - 拟合逻辑回归
- `robust` - 使用稳健回归（对异常值不敏感）
- `ci` - 置信区间宽度（默认 95）
- `scatter_kws`, `line_kws` - 自定义散点和线条属性

```python
# 简单线性回归
sns.regplot(data=df, x='total_bill', y='tip')

# 带分面的多项式回归
sns.lmplot(data=df, x='total_bill', y='tip',
           col='time', order=2, ci=95)

# 检查残差
sns.residplot(data=df, x='total_bill', y='tip')
```

### 矩阵图（矩形数据）

**用途：** 可视化矩阵、相关性和网格结构数据

- `heatmap()` - 带注释的颜色编码矩阵
- `clustermap()` - 层次聚类热力图

**关键参数：**
- `data` - 二维矩形数据集（DataFrame 或数组）
- `annot` - 在单元格中显示数值
- `fmt` - 注释格式字符串（如 ".2f"）
- `cmap` - 调色板名称
- `center` - 调色板中心的值（用于发散调色板）
- `vmin`, `vmax` - 颜色范围限制
- `square` - 强制正方形单元格
- `linewidths` - 单元格间间隙

```python
# 相关性热力图
corr = df.corr()
sns.heatmap(corr, annot=True, fmt='.2f',
            cmap='coolwarm', center=0, square=True)

# 聚类热力图
sns.clustermap(data, cmap='viridis',
               standard_scale=1, figsize=(10, 10))
```

## 多图网格

Seaborn 提供网格对象用于创建复杂的多面板图形：

### FacetGrid

基于分类变量创建子图。通过图形级函数（`relplot`、`displot`、`catplot`）调用时最有用，但也可直接用于自定义图表。

```python
g = sns.FacetGrid(df, col='time', row='sex', hue='smoker')
g.map(sns.scatterplot, 'total_bill', 'tip')
g.add_legend()
```

### PairGrid

显示数据集中所有变量之间的成对关系。

```python
g = sns.PairGrid(df, hue='species')
g.map_upper(sns.scatterplot)
g.map_lower(sns.kdeplot)
g.map_diag(sns.histplot)
g.add_legend()
```

### JointGrid

将双变量图与边缘分布结合。

```python
g = sns.JointGrid(data=df, x='total_bill', y='tip')
g.plot_joint(sns.scatterplot)
g.plot_marginals(sns.histplot)
```

## 图形级与坐标轴级函数

理解这一区别对于有效使用 Seaborn 至关重要：

### 坐标轴级函数

- 绑制到单个 matplotlib `Axes` 对象
- 易于集成到复杂的 matplotlib 图形中
- 接受 `ax=` 参数进行精确定位
- 返回 `Axes` 对象
- 示例：`scatterplot`、`histplot`、`boxplot`、`regplot`、`heatmap`

**何时使用：**
- 构建自定义多图布局
- 组合不同图表类型
- 需要 matplotlib 级别的控制
- 与现有 matplotlib 代码集成

```python
fig, axes = plt.subplots(2, 2, figsize=(10, 10))
sns.scatterplot(data=df, x='x', y='y', ax=axes[0, 0])
sns.histplot(data=df, x='x', ax=axes[0, 1])
sns.boxplot(data=df, x='cat', y='y', ax=axes[1, 0])
sns.kdeplot(data=df, x='x', y='y', ax=axes[1, 1])
```

### 图形级函数

- 管理整个图形，包括所有子图
- 通过 `col` 和 `row` 参数内置分面
- 返回 `FacetGrid`、`JointGrid` 或 `PairGrid` 对象
- 使用 `height` 和 `aspect` 控制大小（每个子图）
- 无法放置到现有图形中
- 示例：`relplot`、`displot`、`catplot`、`lmplot`、`jointplot`、`pairplot`

**何时使用：**
- 分面可视化（小多图）
- 快速探索性分析
- 一致的多面板布局
- 不需要与其他图表类型组合

```python
# 自动分面
sns.relplot(data=df, x='x', y='y', col='category', row='group',
            hue='type', height=3, aspect=1.2)
```

## 数据结构要求

### 长格式数据（推荐）

每个变量是一列，每个观测值是一行。这种"整洁"格式提供最大的灵活性：

```python
# 长格式结构
   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 操作的自然形式

### 宽格式数据

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

```python
# 宽格式结构
   control  treatment
0     10.5       12.3
1      9.8       13.1
```

**使用场景：**
- 简单时间序列
- 相关矩阵
- 热力图
- 数组数据的快速绑图

**宽格式转长格式：**
```python
df_long = df.melt(var_name='condition', value_name='measurement')
```

## 调色板

Seaborn 为不同数据类型提供精心设计的调色板：

### 定性调色板（分类数据）

通过色调变化区分类别：
- `"deep"` - 默认，鲜艳颜色
- `"muted"` - 柔和，低饱和度
- `"pastel"` - 浅色，去饱和
- `"bright"` - 高饱和度
- `"dark"` - 深色值
- `"colorblind"` - 色觉障碍友好

```python
sns.set_palette("colorblind")
sns.color_palette("Set2")
```

### 顺序调色板（有序数据）

显示从低到高的值变化：
- `"rocket"`、`"mako"` - 宽亮度范围（适合热力图）
- `"flare"`、`"crest"` - 限制亮度范围（适合点/线）
- `"viridis"`、`"magma"`、`"plasma"` - Matplotlib 感知均匀

```python
sns.heatmap(data, cmap='rocket')
sns.kdeplot(data=df, x='x', y='y', cmap='mako', fill=True)
```

### 发散调色板（中心化数据）

强调偏离中点的程度：
- `"vlag"` - 蓝到红
- `"icefire"` - 蓝到橙
- `"coolwarm"` - 冷到暖
- `"Spectral"` - 彩虹发散

```python
sns.heatmap(correlation_matrix, cmap='vlag', center=0)
```

### 自定义调色板

```python
# 创建自定义调色板
custom = sns.color_palette("husl", 8)

# 浅到深渐变
palette = sns.light_palette("seagreen", as_cmap=True)

# 从色调创建发散调色板
palette = sns.diverging_palette(250, 10, as_cmap=True)
```

## 主题与美学

### 设置主题

`set_theme()` 控制整体外观：

```python
# 设置完整主题
sns.set_theme(style='whitegrid', palette='pastel', font='sans-serif')

# 重置为默认
sns.set_theme()
```

### 样式

控制背景和网格外观：
- `"darkgrid"` - 灰色背景配白色网格（默认）
- `"whitegrid"` - 白色背景配灰色网格
- `"dark"` - 灰色背景，无网格
- `"white"` - 白色背景，无网格
- `"ticks"` - 白色背景配坐标轴刻度

```python
sns.set_style("whitegrid")

# 移除边框
sns.despine(left=False, bottom=False, offset=10, trim=True)

# 临时样式
with sns.axes_style("white"):
    sns.scatterplot(data=df, x='x', y='y')
```

### 上下文

针对不同使用场景缩放元素：
- `"paper"` - 最小（默认）
- `"notebook"` - 稍大
- `"talk"` - 演示幻灯片
- `"poster"` - 大幅面

```python
sns.set_context("talk", font_scale=1.2)

# 临时上下文
with sns.plotting_context("poster"):
    sns.barplot(data=df, x='category', y='value')
```

## 最佳实践

### 1. 数据准备

始终使用结构良好的 DataFrame 和有意义的列名：

```python
# 推荐：DataFrame 中的命名列
df = pd.DataFrame({'bill': bills, 'tip': tips, 'day': days})
sns.scatterplot(data=df, x='bill', y='tip', hue='day')

# 避免：未命名数组
sns.scatterplot(x=x_array, y=y_array)  # 会丢失坐标轴标签
```

### 2. 选择正确的图表类型

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

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

```python
# 推荐：使用图形级函数自动分面
sns.relplot(data=df, x='x', y='y', col='category', col_wrap=3)

# 不推荐：手动创建子图进行简单分面
```

### 4. 利用语义映射

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

```python
sns.scatterplot(data=df, x='x', y='y',
                hue='category',      # 按类别着色
                size='importance',   # 按连续变量调整大小
                style='type')        # 按类型设置标记样式
```

### 5. 控制统计估计

许多函数自动计算统计量。理解并自定义：

```python
# lineplot 默认计算均值和 95% 置信区间
sns.lineplot(data=df, x='time', y='value',
             errorbar='sd')  # 改用标准差

# barplot 默认计算均值
sns.barplot(data=df, x='category', y='value',
            estimator='median',  # 改用中位数
            errorbar=('ci', 95))  # 自助法置信区间
```

### 6. 与 Matplotlib 结合

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

```python
ax = sns.scatterplot(data=df, x='x', y='y')
ax.set(xlabel='自定义 X 标签', ylabel='自定义 Y 标签',
       title='自定义标题')
ax.axhline(y=0, color='r', linestyle='--')
plt.tight_layout()
```

### 7. 保存高质量图形

```python
fig = sns.relplot(data=df, x='x', y='y', col='group')
fig.savefig('figure.png', dpi=300, bbox_inches='tight')
fig.savefig('figure.pdf')  # 出版物用矢量格式
```

## 常见模式

### 探索性数据分析

```python
# 快速查看所有关系
sns.pairplot(data=df, hue='target', corner=True)

# 分布探索
sns.displot(data=df, x='variable', hue='group',
            kind='kde', fill=True, col='category')

# 相关性分析
corr = df.corr()
sns.heatmap(corr, annot=True, cmap='coolwarm', center=0)
```

### 出版级图形

```python
sns.set_theme(style='ticks', context='paper', font_scale=1.1)

g = sns.catplot(data=df, x='treatment', y='response',
                col='cell_line', kind='box', height=3, aspect=1.2)
g.set_axis_labels('处理条件', '响应值 (μM)')
g.set_titles('{col_name}')
sns.despine(trim=True)

g.savefig('figure.pdf', dpi=300, bbox_inches='tight')
```

### 复杂多面板图形

```python
# 使用 matplotlib 子图配合 seaborn
fig, axes = plt.subplots(2, 2, figsize=(12, 10))

sns.scatterplot(data=df, x='x1', y='y', hue='group', ax=axes[0, 0])
sns.histplot(data=df, x='x1', hue='group', ax=axes[0, 1])
sns.violinplot(data=df, x='group', y='y', ax=axes[1, 0])
sns.heatmap(df.pivot_table(values='y', index='x1', columns='x2'),
            ax=axes[1, 1], cmap='viridis')

plt.tight_layout()
```

### 带置信带的时间序列

```python
# lineplot 自动聚合并显示置信区间
sns.lineplot(data=timeseries, x='date', y='measurement',
             hue='sensor', style='location', errorbar='sd')

# 更多控制
g = sns.relplot(data=timeseries, x='date', y='measurement',
                col='location', hue='sensor', kind='line',
                height=4, aspect=1.5, errorbar=('ci', 95))
g.set_axis_labels('日期', '测量值 (单位)')
```

## 故障排除

### 问题：图例在绑图区域外

图形级函数默认将图例放在外部。要移到内部：

```python
g = sns.relplot(data=df, x='x', y='y', hue='category')
g._legend.set_bbox_to_anchor((0.9, 0.5))  # 调整位置
```

### 问题：标签重叠

```python
plt.xticks(rotation=45, ha='right')
plt.tight_layout()
```

### 问题：图形太小

图形级函数：
```python
sns.relplot(data=df, x='x', y='y', height=6, aspect=1.5)
```

坐标轴级函数：
```python
fig, ax = plt.subplots(figsize=(10, 6))
sns.scatterplot(data=df, x='x', y='y', ax=ax)
```

### 问题：颜色区分度不够

```python
# 使用不同调色板
sns.set_palette("bright")

# 或指定颜色数量
palette = sns.color_palette("husl", n_colors=len(df['category'].unique()))
sns.scatterplot(data=df, x='x', y='y', hue='category', palette=palette)
```

### 问题：KDE 太平滑或太锯齿

```python
# 调整带宽
sns.kdeplot(data=df, x='x', bw_adjust=0.5)  # 更不平滑
sns.kdeplot(data=df, x='x', bw_adjust=2)    # 更平滑
```

## 资源

本技能包含用于深入探索的参考材料：

### references/

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

根据需要加载参考文件以获取详细的函数签名、高级参数或特定示例。

## 局限性

- 仅当任务明确符合上述描述的范围时使用本技能
- 不要将输出替代为环境特定的验证、测试或专家审查
- 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清