---
title: "Seaborn Objects Interface"
description: "The `seaborn.objects` interface provides a modern, declarative API for building visualizations through composition. This guide covers the complete objects interface introduced in seaborn 0.12+."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/objects-interface
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:31:25.210Z
license: CC-BY-4.0
attribution: "Seaborn Objects Interface — Claudary (https://claudary.paisolsolutions.com/skills/objects-interface)"
---

# Seaborn Objects Interface
The `seaborn.objects` interface provides a modern, declarative API for building visualizations through composition. This guide covers the complete objects interface introduced in seaborn 0.12+.

## Overview

# Seaborn Objects Interface

The `seaborn.objects` interface provides a modern, declarative API for building visualizations through composition. This guide covers the complete objects interface introduced in seaborn 0.12+.

## Core Concept

The objects interface separates **what you want to show** (data and mappings) from **how to show it** (marks, stats, and moves). Build plots by:

1. Creating a `Plot` object with data and aesthetic mappings
2. Adding layers with `.add()` combining marks and statistical transformations
3. Customizing with `.scale()`, `.label()`, `.limit()`, `.theme()`, etc.
4. Rendering with `.show()` or `.save()`

## Basic Usage

```python
from seaborn import objects as so
import pandas as pd

# Create plot with data and mappings
p = so.Plot(data=df, x='x_var', y='y_var')

# Add mark (visual representation)
p = p.add(so.Dot())

# Display (automatic in Jupyter)
p.show()
```

## Plot Class

The `Plot` class is the foundation of the objects interface.

### Initialization

```python
so.Plot(data=None, x=None, y=None, color=None, alpha=None,
        fill=None, fillalpha=None, fillcolor=None, marker=None,
        pointsize=None, stroke=None, text=None, **variables)
```

**Parameters:**
- `data` - DataFrame or dict of data vectors
- `x, y` - Variables for position
- `color` - Variable for color encoding
- `alpha` - Variable for transparency
- `marker` - Variable for marker shape
- `pointsize` - Variable for point size
- `stroke` - Variable for line width
- `text` - Variable for text labels
- `**variables` - Additional mappings using property names

**Examples:**
```python
# Basic mapping
so.Plot(df, x='total_bill', y='tip')

# Multiple mappings
so.Plot(df, x='total_bill', y='tip', color='day', pointsize='size')

# All variables in Plot
p = so.Plot(df, x='x', y='y', color='cat')
p.add(so.Dot())  # Uses all mappings

# Some variables in add()
p = so.Plot(df, x='x', y='y')
p.add(so.Dot(), color='cat')  # Only this layer uses color
```

### Methods

#### add()

Add a layer to the plot with mark and optional stat/move.

```python
Plot.add(mark, *transforms, orient=None, legend=True, data=None,
         **variables)
```

**Parameters:**
- `mark` - Mark object defining visual representation
- `*transforms` - Stat and/or Move objects for data transformation
- `orient` - "x", "y", or "v"/"h" for orientation
- `legend` - Include in legend (True/False)
- `data` - Override data for this layer
- `**variables` - Override or add variable mappings

**Examples:**
```python
# Simple mark
p.add(so.Dot())

# Mark with stat
p.add(so.Line(), so.PolyFit(order=2))

# Mark with multiple transforms
p.add(so.Bar(), so.Agg(), so.Dodge())

# Layer-specific mappings
p.add(so.Dot(), color='category')
p.add(so.Line(), so.Agg(), color='category')

# Layer-specific data
p.add(so.Dot())
p.add(so.Line(), data=summary_df)
```

#### facet()

Create subplots from categorical variables.

```python
Plot.facet(col=None, row=None, order=None, wrap=None)
```

**Parameters:**
- `col` - Variable for column facets
- `row` - Variable for row facets
- `order` - Dict with facet orders (keys: variable names)
- `wrap` - Wrap columns after this many

**Example:**
```python
p.facet(col='time', row='sex')
p.facet(col='category', wrap=3)
p.facet(col='day', order={'day': ['Thur', 'Fri', 'Sat', 'Sun']})
```

#### pair()

Create pairwise subplots for multiple variables.

```python
Plot.pair(x=None, y=None, wrap=None, cross=True)
```

**Parameters:**
- `x` - Variables for x-axis pairings
- `y` - Variables for y-axis pairings (if None, uses x)
- `wrap` - Wrap after this many columns
- `cross` - Include all x/y combinations (vs. only diagonal)

**Example:**
```python
# Pairs of all variables
p = so.Plot(df).pair(x=['a', 'b', 'c'])
p.add(so.Dot())

# Rectangular grid
p = so.Plot(df).pair(x=['a', 'b'], y=['c', 'd'])
p.add(so.Dot(), alpha=0.5)
```

#### scale()

Customize how data maps to visual properties.

```python
Plot.scale(**scales)
```

**Parameters:** Keyword arguments with property names and Scale objects

**Example:**
```python
p.scale(
    x=so.Continuous().tick(every=5),
    y=so.Continuous().label(like='{x:.1f}'),
    color=so.Nominal(['#1f77b4', '#ff7f0e', '#2ca02c']),
    pointsize=(5, 10)  # Shorthand for range
)
```

#### limit()

Set axis limits.

```python
Plot.limit(x=None, y=None)
```

**Parameters:**
- `x` - Tuple of (min, max) for x-axis
- `y` - Tuple of (min, max) for y-axis

**Example:**
```python
p.limit(x=(0, 100), y=(0, 50))
```

#### label()

Set axis labels and titles.

```python
Plot.label(x=None, y=None, color=None, title=None, **labels)
```

**Parameters:** Keyword arguments with property names and label strings

**Example:**
```python
p.label(
    x='Total Bill ($)',
    y='Tip Amount ($)',
    color='Day of Week',
    title='Restaurant Tips Analysis'
)
```

#### theme()

Apply matplotlib style settings.

```python
Plot.theme(config, **kwargs)
```

**Parameters:**
- `config` - Dict of rcParams or seaborn theme dict
- `**kwargs` - Individual rcParams

**Example:**
```python
# Seaborn theme
p.theme({**sns.axes_style('whitegrid'), **sns.plotting_context('talk')})

# Custom rcParams
p.theme({'axes.facecolor': 'white', 'axes.grid': True})

# Individual parameters
p.theme(axes_facecolor='white', font_scale=1.2)
```

#### layout()

Configure subplot layout.

```python
Plot.layout(size=None, extent=None, engine=None)
```

**Parameters:**
- `size` - (width, height) in inches
- `extent` - (left, bottom, right, top) for subplots
- `engine` - "tight", "constrained", or None

**Example:**
```python
p.layout(size=(10, 6), engine='constrained')
```

#### share()

Control axis sharing across facets.

```python
Plot.share(x=None, y=None)
```

**Parameters:**
- `x` - Share x-axis: True, False, or "col"/"row"
- `y` - Share y-axis: True, False, or "col"/"row"

**Example:**
```python
p.share(x=True, y=False)  # Share x across all, independent y
p.share(x='col')  # Share x within columns only
```

#### on()

Plot on existing matplotlib figure or axes.

```python
Plot.on(target)
```

**Parameters:**
- `target` - matplotlib Figure or Axes object

**Example:**
```python
import matplotlib.pyplot as plt

fig, axes = plt.subplots(2, 2, figsize=(10, 10))
so.Plot(df, x='x', y='y').add(so.Dot()).on(axes[0, 0])
so.Plot(df, x='x', y='z').add(so.Line()).on(axes[0, 1])
```

#### show()

Render and display the plot.

```python
Plot.show(**kwargs)
```

**Parameters:** Passed to `matplotlib.pyplot.show()`

#### save()

Save the plot to file.

```python
Plot.save(filename, **kwargs)
```

**Parameters:**
- `filename` - Output filename
- `**kwargs` - Passed to `matplotlib.figure.Figure.savefig()`

**Example:**
```python
p.save('plot.png', dpi=300, bbox_inches='tight')
p.save('plot.pdf')
```

## Mark Objects

Marks define how data is visually represented.

### Dot

Points/markers for individual observations.

```python
so.Dot(artist_kws=None, **kwargs)
```

**Properties:**
- `color` - Fill color
- `alpha` - Transparency
- `fillcolor` - Alternate color property
- `fillalpha` - Alternate alpha property
- `edgecolor` - Edge color
- `edgealpha` - Edge transparency
- `edgewidth` - Edge line width
- `marker` - Marker style
- `pointsize` - Marker size
- `stroke` - Edge width

**Example:**
```python
so.Plot(df, x='x', y='y').add(so.Dot(color='blue', pointsize=10))
so.Plot(df, x='x', y='y', color='cat').add(so.Dot(alpha=0.5))
```

### Line

Lines connecting observations.

```python
so.Line(artist_kws=None, **kwargs)
```

**Properties:**
- `color` - Line color
- `alpha` - Transparency
- `linewidth` - Line width
- `linestyle` - Line style ("-", "--", "-.", ":")
- `marker` - Marker at data points
- `pointsize` - Marker size
- `edgecolor` - Marker edge color
- `edgewidth` - Marker edge width

**Example:**
```python
so.Plot(df, x='x', y='y').add(so.Line())
so.Plot(df, x='x', y='y', color='cat').add(so.Line(linewidth=2))
```

### Path

Like Line but connects points in data order (not sorted by x).

```python
so.Path(artist_kws=None, **kwargs)
```

Properties same as `Line`.

**Example:**
```python
# For trajectories, loops, etc.
so.Plot(trajectory_df, x='x', y='y').add(so.Path())
```

### Bar

Rectangular bars.

```python
so.Bar(artist_kws=None, **kwargs)
```

**Properties:**
- `color` - Fill color
- `alpha` - Transparency
- `edgecolor` - Edge color
- `edgealpha` - Edge transparency
- `edgewidth` - Edge line width
- `width` - Bar width (data units)

**Example:**
```python
so.Plot(df, x='category', y='value').add(so.Bar())
so.Plot(df, x='x', y='y').add(so.Bar(color='#1f77b4', width=0.5))
```

### Bars

Multiple bars (for aggregated data with error bars).

```python
so.Bars(artist_kws=None, **kwargs)
```

Properties same as `Bar`. Used with `Agg()` or `Est()` stats.

**Example:**
```python
so.Plot(df, x='category', y='value').add(so.Bars(), so.Agg())
```

### Area

Filled area between line and baseline.

```python
so.Area(artist_kws=None, **kwargs)
```

**Properties:**
- `color` - Fill color
- `alpha` - Transparency
- `edgecolor` - Edge color
- `edgealpha` - Edge transparency
- `edgewidth` - Edge line width
- `baseline` - Baseline value (default: 0)

**Example:**
```python
so.Plot(df, x='x', y='y').add(so.Area(alpha=0.3))
so.Plot(df, x='x', y='y', color='cat').add(so.Area())
```

### Band

Filled band between two lines (for ranges/intervals).

```python
so.Band(artist_kws=None, **kwargs)
```

Properties same as `Area`. Requires `ymin` and `ymax` mappings or used with `Est()` stat.

**Example:**
```python
so.Plot(df, x='x', ymin='lower', ymax='upper').add(so.Band())
so.Plot(df, x='x', y='y').add(so.Band(), so.Est())
```

### Range

Line with markers at endpoints (for ranges).

```python
so.Range(artist_kws=None, **kwargs)
```

**Properties:**
- `color` - Line and marker color
- `alpha` - Transparency
- `linewidth` - Line width
- `marker` - Marker style at endpoints
- `pointsize` - Marker size
- `edgewidth` - Marker edge width

**Example:**
```python
so.Plot(df, x='x', y='y').add(so.Range(), so.Est())
```

### Dash

Short horizontal/vertical lines (for distribution marks).

```python
so.Dash(artist_kws=None, **kwargs)
```

**Properties:**
- `color` - Line color
- `alpha` - Transparency
- `linewidth` - Line width
- `width` - Dash length (data units)

**Example:**
```python
so.Plot(df, x='category', y='value').add(so.Dash())
```

### Text

Text labels at data points.

```python
so.Text(artist_kws=None, **kwargs)
```

**Properties:**
- `color` - Text color
- `alpha` - Transparency
- `fontsize` - Font size
- `halign` - Horizontal alignment: "left", "center", "right"
- `valign` - Vertical alignment: "bottom", "center", "top"
- `offset` - (x, y) offset from point

Requires `text` mapping.

**Example:**
```python
so.Plot(df, x='x', y='y', text='label').add(so.Text())
so.Plot(df, x='x', y='y', text='value').add(so.Text(fontsize=10, offset=(0, 5)))
```

## Stat Objects

Stats transform data before rendering. Compose with marks in `.add()`.

### Agg

Aggregate observations by group.

```python
so.Agg(func='mean')
```

**Parameters:**
- `func` - Aggregation function: "mean", "median", "sum", "min", "max", "count", or callable

**Example:**
```python
so.Plot(df, x='category', y='value').add(so.Bar(), so.Agg('mean'))
so.Plot(df, x='x', y='y', color='group').add(so.Line(), so.Agg('median'))
```

### Est

Estimate central tendency with error intervals.

```python
so.Est(func='mean', errorbar=('ci', 95), n_boot=1000, seed=None)
```

**Parameters:**
- `func` - Estimator: "mean", "median", "sum", or callable
- `errorbar` - Error representation:
  - `("ci", level)` - Confidence interval via bootstrap
  - `("pi", level)` - Percentile interval
  - `("se", scale)` - Standard error scaled by factor
  - `"sd"` - Standard deviation
- `n_boot` - Bootstrap iterations
- `seed` - Random seed

**Example:**
```python
so.Plot(df, x='category', y='value').add(so.Bar(), so.Est())
so.Plot(df, x='x', y='y').add(so.Line(), so.Est(errorbar='sd'))
so.Plot(df, x='x', y='y').add(so.Line(), so.Est(errorbar=('ci', 95)))
so.Plot(df, x='x', y='y').add(so.Band(), so.Est())
```

### Hist

Bin observations and count/aggregate.

```python
so.Hist(stat='count', bins='auto', binwidth=None, binrange=None,
        common_norm=True, common_bins=True, cumulative=False)
```

**Parameters:**
- `stat` - "count", "density", "probability", "percent", "frequency"
- `bins` - Number of bins, bin method, or edges
- `binwidth` - Width of bins
- `binrange` - (min, max) range for binning
- `common_norm` - Normalize across groups together
- `common_bins` - Use same bins for all groups
- `cumulative` - Cumulative histogram

**Example:**
```python
so.Plot(df, x='value').add(so.Bars(), so.Hist())
so.Plot(df, x='value').add(so.Bars(), so.Hist(bins=20, stat='density'))
so.Plot(df, x='value', color='group').add(so.Area(), so.Hist(cumulative=True))
```

### KDE

Kernel density estimate.

```python
so.KDE(bw_method='scott', bw_adjust=1, gridsize=200,
       cut=3, cumulative=False)
```

**Parameters:**
- `bw_method` - Bandwidth method: "scott", "silverman", or scalar
- `bw_adjust` - Bandwidth multiplier
- `gridsize` - Resolution of density curve
- `cut` - Extension beyond data range (in bandwidth units)
- `cumulative` - Cumulative density

**Example:**
```python
so.Plot(df, x='value').add(so.Line(), so.KDE())
so.Plot(df, x='value', color='group').add(so.Area(alpha=0.5), so.KDE())
so.Plot(df, x='x', y='y').add(so.Line(), so.KDE(bw_adjust=0.5))
```

### Count

Count observations per group.

```python
so.Count()
```

**Example:**
```python
so.Plot(df, x='category').add(so.Bar(), so.Count())
```

### PolyFit

Polynomial regression fit.

```python
so.PolyFit(order=1)
```

**Parameters:**
- `order` - Polynomial order (1 = linear, 2 = quadratic, etc.)

**Example:**
```python
so.Plot(df, x='x', y='y').add(so.Dot())
so.Plot(df, x='x', y='y').add(so.Line(), so.PolyFit(order=2))
```

### Perc

Compute percentiles.

```python
so.Perc(k=5, method='linear')
```

**Parameters:**
- `k` - Number of percentile intervals
- `method` - Interpolation method

**Example:**
```python
so.Plot(df, x='x', y='y').add(so.Band(), so.Perc())
```

## Move Objects

Moves adjust positions to resolve overlaps or create specific layouts.

### Dodge

Shift positions side-by-side.

```python
so.Dodge(empty='keep', gap=0)
```

**Parameters:**
- `empty` - How to handle empty groups: "keep", "drop", "fill"
- `gap` - Gap between dodged elements (proportion)

**Example:**
```python
so.Plot(df, x='category', y='value', color='group').add(so.Bar(), so.Dodge())
so.Plot(df, x='cat', y='val', color='hue').add(so.Dot(), so.Dodge(gap=0.1))
```

### Stack

Stack marks vertically.

```python
so.Stack()
```

**Example:**
```python
so.Plot(df, x='x', y='y', color='category').add(so.Bar(), so.Stack())
so.Plot(df, x='x', y='y', color='group').add(so.Area(), so.Stack())
```

### Jitter

Add random noise to positions.

```python
so.Jitter(width=None, height=None, seed=None)
```

**Parameters:**
- `width` - Jitter in x di

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/objects-interface) · https://claudary.paisolsolutions.com