alterlab-seaborn

Seaborn Statistical Visualization

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

1. Dataset-oriented — work directly with DataFrames and named variables, not abstract coordinates.
2. Semantic mapping — automatically translate data values into visual properties (color, size, style).
3. Statistical awareness — built-in aggregation, error estimation, and confidence intervals.
4. Aesthetic defaults — publication-ready themes and palettes out of the box.
5. 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

1. 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(...). See references/data_palettes_theming.md.
2. Pick the plot category for your variable types (see routing below).
3. Encode extra dimensions with hue, size, style semantic mappings.
4. Choose axes-level vs figure-level: axes-level (scatterplot, boxplot, heatmap, …) plug into custom matplotlib layouts via ax=; figure-level (relplot, displot, catplot, lmplot, …) own the whole figure and facet via col/row.
5. Theme and save with set_theme/set_context and savefig(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", with center=0).
• set_theme(style=..., context=..., palette=...); styles whitegrid/ticks/…; contexts paper→talk→poster scale 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/barplot auto-compute mean + CI — override with errorbar= and estimator=.
• Combine with matplotlib (ax.set(...), axhline, tight_layout) for fine-tuning; save at dpi=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 modern seaborn.objects API.
• references/examples.md — scenario-based worked examples and code patterns.