alterlab-seaborn

name	alterlab-seaborn
description	Builds statistical plots with the seaborn Python library and pandas DataFrame integration, on attractive matplotlib-based defaults. Use for quick exploration of distributions, relationships, and categorical comparisons — box plots, violin plots, swarm/strip plots, KDE/histograms, pair plots, joint plots, regression plots, correlation heatmaps, and faceted small multiples (relplot/displot/catplot/lmplot). For interactive/hover/zoom charts defer to alterlab-plotly; for exact journal/manuscript styling (column widths, point fonts, CMYK, vector export) defer to alterlab-scientific-viz; for low-level custom matplotlib figures defer to alterlab-matplotlib (seaborn integrates with it for fine-tuning). Part of the AlterLab Academic Skills suite.
license	MIT
allowed-tools	Read Write Edit Bash(python:*)
compatibility	Requires the seaborn and pandas Python libraries (pip install seaborn pandas); no API key or external service needed
metadata	{"skill-author":"AlterLab","version":"1.0.0"}

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. Route elsewhere when the need differs:

• Interactive charts (hover, zoom, HTML dashboards) → alterlab-plotly
• Exact journal/manuscript styling (column widths, point fonts, CMYK, vector export) → alterlab-scientific-viz
• Low-level custom plotting → alterlab-matplotlib (seaborn integrates with it for fine-tuning)

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). Two API points that bite on this version: pass palette= only together with hue= (palette-without-hue is deprecated, removed in 0.14), and style error bars via err_kws={...} rather than the removed-in-0.15 errcolor/errwidth/scale/join keywords.

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.