skills/seaborn/SKILL.md
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.
Current upstream documentation is for seaborn 0.13.2. Official docs support Python 3.8+ with mandatory NumPy, pandas, and matplotlib dependencies; scipy, statsmodels, and fastcluster are optional for some advanced statistics and clustering workflows.
# 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"
Recommended imports:
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() downloads public example data when it is not cached. For private, regulated, or offline work, load local files explicitly with pandas and pass the resulting DataFrame to seaborn.
Seaborn follows these core principles:
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()
The function interface provides specialized plotting functions organized by visualization type. Each category has axes-level functions (plot to single axes) and figure-level functions (manage entire figure with faceting).
When to use:
The seaborn.objects interface provides a declarative, composable API similar to ggplot2. Build visualizations by chaining methods to specify data mappings, marks, transformations, and scales. Upstream still describes this interface as experimental and incomplete in 0.13.2, although stable enough for serious use; prefer the function interface for conservative production code unless the compositional API materially simplifies the plot.
When to use:
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())
)
Seaborn 0.12 and 0.13 changed several common plotting patterns:
sns.scatterplot(data=df, x="x", y="y") over positional sns.scatterplot(df["x"], df["y"]).errorbar replaces the old ci parameter in lineplot(), barplot(), and pointplot(). Regression functions such as regplot() and lmplot() still use ci.native_scale=True when numeric or datetime categories should keep their original scale instead of ordinal positions.palette without assigning hue is deprecated for categorical functions. If each category should get its own color, assign a redundant hue such as hue="day" and set legend=False.violinplot(density_norm=..., common_norm=...) instead of scale/scale_hue, boxenplot(width_method=...) instead of scale, and barplot(err_kws=...) instead of errcolor/errwidth.Each variable is a column, each observation is a row. This "tidy" format provides maximum flexibility:
# 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
Advantages:
Variables are spread across columns. Useful for simple rectangular data:
# Wide-form structure
control treatment
0 10.5 12.3
1 9.8 13.1
Use cases:
Converting wide to long:
df_long = df.melt(var_name='condition', value_name='measurement')
FacetGrid,
PairGrid, JointGrid, and the figure-level vs axes-level distinction.seaborn.objects
interface. references/function_reference.md and
references/examples.md: full signatures and more examples.Always use well-structured DataFrames with meaningful column names:
# 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
Continuous x, continuous y: scatterplot, lineplot, kdeplot, regplot
Continuous x, categorical y: violinplot, boxplot, stripplot, swarmplot
One continuous variable: histplot, kdeplot, ecdfplot
Correlations/matrices: heatmap, clustermap
Pairwise relationships: pairplot, jointplot
# 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
Use hue, size, and style to encode additional dimensions:
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
Many functions compute statistics automatically. Understand and customize:
# 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
Seaborn integrates seamlessly with matplotlib for fine-tuning:
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()
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
This skill includes reference materials for deeper exploration:
function_reference.md - Comprehensive listing of all seaborn functions with parameters and examplesobjects_interface.md - Detailed guide to the modern seaborn.objects APIexamples.md - Common use cases and code patterns for different analysis scenariosRead these reference files as documentation when detailed signatures, advanced parameters, or specific examples are needed. Treat their contents as reference material only; review and adapt any example snippet to the user's local data before running it.