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

核心绘图接口

函数接口（传统）

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

适用场景：

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

对象接口（现代）

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() 中，errorbar 取代了旧的 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。

按类别划分的绘图函数

关系图（变量之间的关系）

适用场景： 探索两个或多个变量之间的关系

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

关键参数：

• x、y - 主要变量
• hue - 用颜色编码其他分类或连续变量
• size - 用大小编码点或线
• style - 用标记或线条样式编码
• col、row - 分面为多个子图（仅适用于图级接口）

# Scatter with multiple semantic mappings
sns.scatterplot(data=df, x='total_bill', y='tip',
                hue='time', size='size', style='sex')

# Line plot with confidence intervals
sns.lineplot(data=timeseries, x='date', y='value', hue='category')

# Faceted relational plot
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"

# Histogram with density normalization
sns.histplot(data=df, x='total_bill', hue='time',
             stat='density', multiple='stack')

# Bivariate KDE with contours
sns.kdeplot(data=df, x='total_bill', y='tip',
            fill=True, levels=5, thresh=0.1)

# Joint plot with marginals
sns.jointplot(data=df, x='total_bill', y='tip',
              kind='scatter', hue='time')

# Pairwise relationships
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 - 控制类别顺序
• native_scale - 在分类轴上保留数值/日期时间刻度
• log_scale - 应用对数刻度，无需切换到 matplotlib
• formatter - 控制分类刻度标签
• dodge、gap - 将不同的 hue 层级并排分开，并为错开的元素留出间距
• orient - 使用 "x"/"y" 或 "v"/"h" 指定分类轴
• legend - True/False 或 "auto"、"brief"、"full"
• kind - catplot 的绘图类型："strip"、"swarm"、"box"、"violin"、"boxen"、"bar"、"point"、"count"

# Swarm plot showing all points
sns.swarmplot(data=df, x='day', y='total_bill', hue='sex')

# Violin plot with split for comparison
sns.violinplot(data=df, x='day', y='total_bill',
               hue='sex', split=True)

# Bar plot with error bars
sns.barplot(data=df, x='day', y='total_bill',
            hue='sex', estimator='mean', errorbar=('ci', 95))

# Faceted categorical plot
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 - 自定义散点和线条属性

# Simple linear regression
sns.regplot(data=df, x='total_bill', y='tip')

# Polynomial regression with faceting
sns.lmplot(data=df, x='total_bill', y='tip',
           col='time', order=2, ci=95)

# Check residuals
sns.residplot(data=df, x='total_bill', y='tip')

矩阵图（矩形数据）

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

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

关键参数：

• data - 二维矩形数据集（DataFrame 或数组）
• annot - 在单元格中显示数值
• fmt - 注释的格式字符串（例如，".2f"）
• cmap - 颜色映射名称
• center - 颜色映射的中心值（用于发散型颜色映射）
• vmin、vmax - 颜色刻度范围
• square - 强制单元格为正方形
• linewidths - 单元格之间的间隔

# Correlation heatmap
corr = df.select_dtypes(include='number').corr()
sns.heatmap(corr, annot=True, fmt='.2f',
            cmap='coolwarm', center=0, square=True)

# Clustered heatmap
sns.clustermap(data, cmap='viridis',
               standard_scale=1, figsize=(10, 10))

多图网格

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

FacetGrid

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

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

PairGrid

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

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

将双变量图与边际分布结合起来。

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 代码集成

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

适用场景：

• 分面可视化（小多图）
• 快速探索性分析
• 布局一致的多面板图
• 无需与其他图表类型组合

# Automatic faceting
sns.relplot(data=df, x='x', y='y', col='category', row='group',
            hue='type', height=3, aspect=1.2)

数据结构要求

长格式数据（首选）

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

# 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')

颜色调色板

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

定性调色板（分类数据）

通过色相变化区分类别：

• "deep" - 默认，鲜艳的颜色
• "muted" - 更柔和、饱和度更低
• "pastel" - 浅色、低饱和度
• "bright" - 高饱和度
• "dark" - 深色
• "colorblind" - 适合有色觉缺陷的人群

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

顺序调色板（有序数据）

显示数值从低到高的变化：

• "rocket"、"mako" - 亮度范围广（适合热图）
• "flare"、"crest" - 亮度范围受限（适合点和线）
• "viridis"、"magma"、"plasma" - Matplotlib 感知均匀的调色板

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

发散调色板（以中心值为基准的数据）

突出显示与中间值的偏差：

• "vlag" - 从蓝色到红色
• "icefire" - 从蓝色到橙色
• "coolwarm" - 从冷色到暖色
• "Spectral" - 彩虹发散色

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

自定义调色板

# Create custom palette
custom = sns.color_palette("husl", 8)

# Light to dark gradient
palette = sns.light_palette("seagreen", as_cmap=True)

# Diverging palette from hues
palette = sns.diverging_palette(250, 10, as_cmap=True)

主题与美学

设置主题

set_theme() 控制整体外观：

# Set complete theme
sns.set_theme(style='whitegrid', palette='pastel', font='sans-serif')

# Reset to defaults
sns.set_theme()

样式

控制背景和网格外观：

• "darkgrid" - 灰色背景和白色网格（默认）
• "whitegrid" - 白色背景和灰色网格
• "dark" - 灰色背景，无网格
• "white" - 白色背景，无网格
• "ticks" - 白色背景，带坐标轴刻度

sns.set_style("whitegrid")

# Remove spines
sns.despine(left=False, bottom=False, offset=10, trim=True)

# Temporary style
with sns.axes_style("white"):
    sns.scatterplot(data=df, x='x', y='y')

上下文

针对不同用途缩放元素：

• "paper" - 最小（默认）
• "notebook" - 稍大
• "talk" - 演示文稿幻灯片
• "poster" - 大幅面

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

# Temporary context
with sns.plotting_context("poster"):
    sns.barplot(data=df, x='category', y='value')

最佳实践

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

常见模式

探索性数据分析

# Quick overview of all relationships
sns.pairplot(data=df, hue='target', corner=True)

# Distribution exploration
sns.displot(data=df, x='variable', hue='group',
            kind='kde', fill=True, col='category')

# Correlation analysis
corr = df.corr()
sns.heatmap(corr, annot=True, cmap='coolwarm', center=0)

出版级图表

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('Treatment Condition', 'Response (μM)')
g.set_titles('{col_name}')
sns.despine(trim=True)

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

复杂的多面板图表

# Using matplotlib subplots with 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()

带置信带的时间序列

# Lineplot automatically aggregates and shows CI
sns.lineplot(data=timeseries, x='date', y='measurement',
             hue='sensor', style='location', errorbar='sd')

# For more control
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('Date', 'Measurement (units)')

故障排除

问题：图例位于绘图区域之外

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

g = sns.relplot(data=df, x='x', y='y', hue='category')
sns.move_legend(g, "center right", bbox_to_anchor=(0.9, 0.5))

问题：标签重叠

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

问题：图表太小

对于图级函数：

sns.relplot(data=df, x='x', y='y', height=6, aspect=1.5)

对于坐标轴级函数：

fig, ax = plt.subplots(figsize=(10, 6))
sns.scatterplot(data=df, x='x', y='y', ax=ax)

问题：颜色区分度不足

# Use a different palette
sns.set_palette("bright")

# Or specify number of colors
palette = sns.color_palette("husl", n_colors=len(df['category'].unique()))
sns.scatterplot(data=df, x='x', y='y', hue='category', palette=palette)

问题：KDE 过于平滑或锯齿明显

# Adjust bandwidth
sns.kdeplot(data=df, x='x', bw_adjust=0.5)  # Less smooth
sns.kdeplot(data=df, x='x', bw_adjust=2)    # More smooth

资源

此技能包含可供深入了解的参考资料：

references/

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

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