Skip to content
Research Agent Skillsby Kalaris Labs
Install
Visualization and Presentationv1.3AdaptedBSD-3-Clause license

seaborn

Statistical visualization with pandas integration. Use for quick exploration of distributions, relationships, and categorical comparisons with attractive defaults. Best for box plots, violin plots, pair plots, heatmaps. Built on matplotlib. For interactive plots use plotly; for publication styling use scientific-visualization.

Install this skill

Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.

skills.sh CLI (Recommended)
npx skills add KalarisLabs/research-agent-skills --skill seaborn
uvx (Python tool runner)
uvx research-agent-skills install seaborn

Documentation & Instructions

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.

Environment and Installation

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.

Design Philosophy

Seaborn follows these core principles:

  1. Dataset-oriented: Work directly with DataFrames and named variables rather than abstract coordinates
  2. Semantic mapping: Automatically translate data values into visual properties (colors, sizes, styles)
  3. Statistical awareness: Built-in aggregation, error estimation, and confidence intervals
  4. Aesthetic defaults: Publication-ready themes and color palettes out of the box
  5. Matplotlib integration: Full compatibility with matplotlib customization when needed

Quick Start

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

Core Plotting Interfaces

Function Interface (Traditional)

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:

  • Quick exploratory analysis
  • Single-purpose visualizations
  • When you need a specific plot type

Objects Interface (Modern)

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:

  • Complex layered visualizations
  • When you need fine-grained control over transformations
  • Building custom plot types
  • Programmatic plot generation
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())
)

Current API Notes

Seaborn 0.12 and 0.13 changed several common plotting patterns:

  • Most plotting functions now require keyword arguments for variables. Prefer 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.
  • Categorical plots were rewritten in 0.13. Use native_scale=True when numeric or datetime categories should keep their original scale instead of ordinal positions.
  • Passing 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.
  • Prefer renamed parameters: violinplot(density_norm=..., common_norm=...) instead of scale/scale_hue, boxenplot(width_method=...) instead of scale, and barplot(err_kws=...) instead of errcolor/errwidth.

Data Structure Requirements

Long-Form Data (Preferred)

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:

  • Works with all seaborn functions
  • Easy to remap variables to visual properties
  • Supports arbitrary complexity
  • Natural for DataFrame operations

Wide-Form Data

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:

  • Simple time series
  • Correlation matrices
  • Heatmaps
  • Quick plots of array data

Converting wide to long:

df_long = df.melt(var_name='condition', value_name='measurement')

Plotting Functions, Grids, Palettes, and Patterns

Best Practices

1. Data Preparation

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

2. Choose the Right Plot Type

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

3. Use Figure-Level Functions for Faceting

# 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. Leverage Semantic Mappings

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

5. Control Statistical Estimation

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

6. Combine with Matplotlib

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

7. Save High-Quality Figures

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

Resources

This skill includes reference materials for deeper exploration:

references/

  • function_reference.md - Comprehensive listing of all seaborn functions with parameters and examples
  • objects_interface.md - Detailed guide to the modern seaborn.objects API
  • examples.md - Common use cases and code patterns for different analysis scenarios

Read 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.

Agent operating procedure

  1. Check the environment. Confirm the data source, the message each figure must convey, and the target medium (journal, poster, slides).
  2. Pin down the inputs. Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.
  3. Run a small version first. Render one figure at final size and check legibility before producing the full set.
  4. Execute the full task using the instructions and references above.
  5. Validate the result. Axes, units and error bars are labeled and defined; colours are colour-blind safe; numbers match the underlying data.
  6. Report. State what was run (versions, commands, parameters), what was checked, and what is still uncertain.
If this happens Do this
Text is unreadable at final size Increase font sizes or simplify the panel rather than shrinking it.
A function, flag or endpoint in these instructions is missing in the installed version Check the installed version's own documentation (help(), --help, official docs), adapt, and tell the user. Never invent an API.
A required input, identifier or parameter is ambiguous Ask the user, or state the assumption explicitly before running.

Integrity rules

  • Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.
  • Never alter data to improve a figure's appearance; apply image adjustments uniformly and disclose them.
  • Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.
  • Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.

Related skills

  • matplotlib: Low-level plotting library for full customization.
  • dask: Distributed computing for larger-than-RAM pandas/NumPy workflows.
  • scientific-visualization: Create and audit truthful, accessible, publication-ready scientific figures with Matplotlib, Seaborn, or Plotly.

Trigger Prompts & Evaluation Corpus

These evaluation prompts test that the agent correctly selects seaborn for relevant tasks and leaves it out for near misses.

Should trigger (3)

  • should trigger

    “Can you make a pair plot of my iris dataframe colored by species?”

    expects Uses sns.pairplot(data=df, hue='species') with keyword arguments, mentions optional diag_kind or corner settings, and checks that axes are labeled and colors are distinguishable (colorblind-safe palette).

  • should trigger

    “I have expression_counts.csv with columns sample_id, condition (control/treated/rescue), gene, log2_expr. I want to compare log2_expr across the three conditions for each gene, with individual points visible, and I keep getting a FutureWarning about 'palette' without 'hue' when I run sns.boxplot(x='condition', y='log2_expr', data=df, palette='Set2'). Fix it and show the distributions.”

    expects Loads the CSV locally with pandas, explains that in seaborn 0.13 passing palette without hue is deprecated and fixes it by setting hue='condition' with legend=False. Uses keyword arguments, overlays a stripplot or swarmplot for individual points, and may facet by gene with a figure-level function. Labels axes with units.

  • should trigger

    “I've got a table of 40 patient biomarkers and I want to see which ones move together and group similar ones, as a color-coded grid I can drop into a lab meeting slide. What should I do?”

    expects Recommends computing a correlation matrix with pandas and plotting it with sns.heatmap or sns.clustermap, with a diverging colormap centered at 0, annotated or readable labels, and a note about the correlation method chosen. Checks legibility at slide size and asks or states assumptions about missing data.

Near misses (2)

  • near miss

    “I need an interactive scatter plot of my UMAP embedding where I can hover over points to see cell IDs and zoom into clusters, exported as an HTML file.”

    expects Should not use seaborn since it produces static matplotlib figures; recommends plotly (e.g., plotly.express.scatter with hover_data) and writing to HTML.

  • near miss

    “I'm building a custom figure in matplotlib with a hand-placed inset axes, a broken y-axis, and custom annotation arrows, then exporting to SVG for Illustrator. How do I position everything precisely?”

    expects Should defer to matplotlib for low-level control of axes placement, inset axes, annotations, and SVG export, rather than seaborn's high-level statistical plotting.