research-copilot 0.1.0

package/lib/skills/builtin/seaborn/references/objects_interface.md

@@ -0,0 +1,964 @@
+# 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 direction (data units or proportion)
+- `height` - Jitter in y direction
+- `seed` - Random seed
+
+**Example:**
+```python
+so.Plot(df, x='category', y='value').add(so.Dot(), so.Jitter())
+so.Plot(df, x='cat', y='val').add(so.Dot(), so.Jitter(width=0.2))
+```
+
+### Shift
+
+Shift positions by constant amount.
+
+```python
+so.Shift(x=0, y=0)
+```
+
+**Parameters:**
+- `x` - Shift in x direction (data units)
+- `y` - Shift in y direction
+
+**Example:**
+```python
+so.Plot(df, x='x', y='y').add(so.Dot(), so.Shift(x=1))
+```
+
+### Norm
+
+Normalize values.
+
+```python
+so.Norm(func='max', where=None, by=None, percent=False)
+```
+
+**Parameters:**
+- `func` - Normalization: "max", "sum", "area", or callable
+- `where` - Apply to which axis: "x", "y", or None
+- `by` - Grouping variables for separate normalization
+- `percent` - Show as percentage
+
+**Example:**
+```python
+so.Plot(df, x='x', y='y', color='group').add(so.Area(), so.Norm())
+```
+
+## Scale Objects
+
+Scales control how data values map to visual properties.
+
+### Continuous
+
+For numeric data.
+
+```python
+so.Continuous(values=None, norm=None, trans=None)
+```
+
+**Methods:**
+- `.tick(at=None, every=None, between=None, minor=None)` - Configure ticks
+- `.label(like=None, base=None, unit=None)` - Format labels
+
+**Parameters:**
+- `values` - Explicit value range (min, max)
+- `norm` - Normalization function
+- `trans` - Transformation: "log", "sqrt", "symlog", "logit", "pow10", or callable
+
+**Example:**
+```python
+p.scale(
+    x=so.Continuous().tick(every=10),
+    y=so.Continuous(trans='log').tick(at=[1, 10, 100]),
+    color=so.Continuous(values=(0, 1)),
+    pointsize=(5, 20)  # Shorthand for Continuous range
+)
+```
+
+### Nominal
+
+For categorical data.
+
+```python
+so.Nominal(values=None, order=None)
+```
+
+**Parameters:**
+- `values` - Explicit values (e.g., colors, markers)
+- `order` - Category order
+
+**Example:**
+```python
+p.scale(
+    color=so.Nominal(['#1f77b4', '#ff7f0e', '#2ca02c']),
+    marker=so.Nominal(['o', 's', '^']),
+    x=so.Nominal(order=['Low', 'Medium', 'High'])
+)
+```
+
+### Temporal
+
+For datetime data.
+
+```python
+so.Temporal(values=None, trans=None)
+```
+
+**Methods:**
+- `.tick(every=None, between=None)` - Configure ticks
+- `.label(concise=False)` - Format labels
+
+**Example:**
+```python
+p.scale(x=so.Temporal().tick(every=('month', 1)).label(concise=True))
+```
+
+## Complete Examples
+
+### Layered Plot with Statistics
+
+```python
+(
+    so.Plot(df, x='total_bill', y='tip', color='time')
+    .add(so.Dot(), alpha=0.5)
+    .add(so.Line(), so.PolyFit(order=2))
+    .scale(color=so.Nominal(['#1f77b4', '#ff7f0e']))
+    .label(x='Total Bill ($)', y='Tip ($)', title='Tips Analysis')
+    .theme({**sns.axes_style('whitegrid')})
+)
+```
+
+### Faceted Distribution
+
+```python
+(
+    so.Plot(df, x='measurement', color='treatment')
+    .facet(col='timepoint', wrap=3)
+    .add(so.Area(alpha=0.5), so.KDE())
+    .add(so.Dot(), so.Jitter(width=0.1), y=0)
+    .scale(x=so.Continuous().tick(every=5))
+    .label(x='Measurement (units)', title='Treatment Effects Over Time')
+    .share(x=True, y=False)
+)
+```
+
+### Grouped Bar Chart
+
+```python
+(
+    so.Plot(df, x='category', y='value', color='group')
+    .add(so.Bar(), so.Agg('mean'), so.Dodge())
+    .add(so.Range(), so.Est(errorbar='se'), so.Dodge())
+    .scale(color=so.Nominal(order=['A', 'B', 'C']))
+    .label(y='Mean Value', title='Comparison by Category and Group')
+)
+```
+
+### Complex Multi-Layer
+
+```python
+(
+    so.Plot(df, x='date', y='value')
+    .add(so.Dot(color='gray', pointsize=3), alpha=0.3)
+    .add(so.Line(color='blue', linewidth=2), so.Agg('mean'))
+    .add(so.Band(color='blue', alpha=0.2), so.Est(errorbar=('ci', 95)))
+    .facet(col='sensor', row='location')
+    .scale(
+        x=so.Temporal().label(concise=True),
+        y=so.Continuous().tick(every=10)
+    )
+    .label(
+        x='Date',
+        y='Measurement',
+        title='Sensor Measurements by Location'
+    )
+    .layout(size=(12, 8), engine='constrained')
+)
+```
+
+## Migration from Function Interface
+
+### Scatter Plot
+
+**Function interface:**
+```python
+sns.scatterplot(data=df, x='x', y='y', hue='category', size='value')
+```
+
+**Objects interface:**
+```python
+so.Plot(df, x='x', y='y', color='category', pointsize='value').add(so.Dot())
+```
+
+### Line Plot with CI
+
+**Function interface:**
+```python
+sns.lineplot(data=df, x='time', y='measurement', hue='group', errorbar='ci')
+```
+
+**Objects interface:**
+```python
+(
+    so.Plot(df, x='time', y='measurement', color='group')
+    .add(so.Line(), so.Est())
+)
+```
+
+### Histogram
+
+**Function interface:**
+```python
+sns.histplot(data=df, x='value', hue='category', stat='density', kde=True)
+```
+
+**Objects interface:**
+```python
+(
+    so.Plot(df, x='value', color='category')
+    .add(so.Bars(), so.Hist(stat='density'))
+    .add(so.Line(), so.KDE())
+)
+```
+
+### Bar Plot with Error Bars
+
+**Function interface:**
+```python
+sns.barplot(data=df, x='category', y='value', hue='group', errorbar='ci')
+```
+
+**Objects interface:**
+```python
+(
+    so.Plot(df, x='category', y='value', color='group')
+    .add(so.Bar(), so.Agg(), so.Dodge())
+    .add(so.Range(), so.Est(), so.Dodge())
+)
+```
+
+## Tips and Best Practices
+
+1. **Method chaining**: Each method returns a new Plot object, enabling fluent chaining
+2. **Layer composition**: Combine multiple `.add()` calls to overlay different marks
+3. **Transform order**: In `.add(mark, stat, move)`, stat applies first, then move
+4. **Variable priority**: Layer-specific mappings override Plot-level mappings
+5. **Scale shortcuts**: Use tuples for simple ranges: `color=(min, max)` vs full Scale object
+6. **Jupyter rendering**: Plots render automatically when returned; use `.show()` otherwise
+7. **Saving**: Use `.save()` rather than `plt.savefig()` for proper handling
+8. **Matplotlib access**: Use `.on(ax)` to integrate with matplotlib figures