Overview
Seaborn is a Python visualization library for creating publication-quality statistical graphics. Use this skill for dataset-oriented plotting, multivariate analysis, automatic statistical estimation, and complex multi-panel figures with minimal code.
When to Use This Skill
Use seaborn for quick, attractive statistical graphics straight from a pandas DataFrame: distributions, relationships, categorical comparisons, correlation heatmaps, and faceted small multiples.
Does NOT Trigger
| Scenario | Use Instead |
|---|---|
| Interactive chart with hover, zoom, or an HTML dashboard | alterlab-plotly |
| Exact journal/manuscript styling (column widths, point fonts, CMYK, vector export) | alterlab-scientific-viz |
| Low-level control of individual artists or layouts beyond FacetGrid/PairGrid | alterlab-matplotlib (seaborn axes-level plots accept ax= for this) |
| A full exploratory-data-analysis report on a data file (structure, quality, summary statistics) | alterlab-eda |
| Choosing and running the statistical test behind a comparison | alterlab-statistical-analysis |
Design Philosophy
- Dataset-oriented — work directly with DataFrames and named variables, not abstract coordinates.
- Semantic mapping — automatically translate data values into visual properties (color, size, style).
- Statistical awareness — built-in aggregation, error estimation, and confidence intervals.
- Aesthetic defaults — publication-ready themes and palettes out of the box.
- Matplotlib integration — full compatibility with matplotlib customization when needed.
Quick Start
Examples target seaborn ≥ 0.13 (verified on 0.13.2, still the current release in September 2026). Two API points that bite on this version: pass palette= only together with hue= (palette-without-hue is deprecated and slated for removal in v0.14), and style error bars via err_kws={...} rather than the deprecated errcolor/errwidth/scale/join keywords (slated for removal in v0.15).
With matplotlib 3.11 every plotting function still works, but boxplot (and catplot(kind="box")) emits a vert MatplotlibDeprecationWarning and heatmap a set_bad PendingDeprecationWarning. Both come from seaborn's internals and are harmless for now; matplotlib 3.13 is scheduled to remove vert, so pin matplotlib<3.13 in environments that depend on sns.boxplot until a seaborn release addresses it.
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()
Core Workflow
- Shape the data as long-form ("tidy") — one column per variable, one row per observation. This works with every seaborn function. Reshape wide data with
df.melt(...). Seereferences/data_palettes_theming.md. - Pick the plot category for your variable types (see routing below).
- Encode extra dimensions with
hue,size,stylesemantic mappings. - Choose axes-level vs figure-level: axes-level (
scatterplot,boxplot,heatmap, …) plug into custom matplotlib layouts viaax=; figure-level (relplot,displot,catplot,lmplot, …) own the whole figure and facet viacol/row. - Theme and save with
set_theme/set_contextandsavefig(dpi=300, bbox_inches='tight')(PDF for vector).
Plot Category Routing
Choose the category, then see references/plotting_functions.md for parameters and code for each.
| Goal | Category | Key functions |
|---|---|---|
| How variables relate | Relational | scatterplot, lineplot, relplot |
| Spread / shape / density | Distribution | histplot, kdeplot, ecdfplot, displot, jointplot, pairplot |
| Compare across categories | Categorical | stripplot, swarmplot, boxplot, violinplot, barplot, pointplot, countplot, catplot |
| Linear relationships / residuals | Regression | regplot, lmplot, residplot |
| Matrices / correlations | Matrix | heatmap, clustermap |
| Custom multi-panel grids | Grids | FacetGrid, PairGrid, JointGrid |
The modern declarative seaborn.objects interface (ggplot2-like, composable) is best for complex layered or programmatic plots — see references/objects_interface.md.
Color and Theming (essentials)
- Qualitative palettes for categories (
"colorblind","deep","muted"); sequential for ordered data ("rocket","viridis"); diverging for centered data ("vlag","coolwarm", withcenter=0). set_theme(style=..., context=..., palette=...); styleswhitegrid/ticks/…; contextspaper→talk→posterscale element sizes.
Full palette and theming reference: references/data_palettes_theming.md.
Best Practices (essentials)
- Plot from named DataFrame columns (preserves axis labels); use figure-level functions for faceting; encode extra dimensions with
hue/size/style. - Know what each function estimates:
lineplot/barplotauto-compute mean + CI — override witherrorbar=andestimator=. - Combine with matplotlib (
ax.set(...),axhline,tight_layout) for fine-tuning; save atdpi=300, and PDF for publications.
Full best-practices, common patterns, and troubleshooting (legend placement, overlapping labels, figure sizing, palette distinctness, KDE bandwidth): references/best_practices_and_troubleshooting.md.
Reference Index
references/plotting_functions.md— every plot category with parameters and code (relational, distribution, categorical, regression, matrix, multi-plot grids, figure-vs-axes-level).references/data_palettes_theming.md— long/wide data structure, color palettes (qualitative/sequential/diverging/custom), and theming (set_theme, styles, contexts).references/best_practices_and_troubleshooting.md— best practices, common patterns (EDA, publication figures, multi-panel, time series), and troubleshooting.references/function_reference.md— comprehensive function signatures, parameters, and examples.references/objects_interface.md— detailed guide to the modernseaborn.objectsAPI.references/examples.md— scenario-based worked examples and code patterns.