oaustegard/charting

Charting: Python Static Visualizations

Select the optimal Python charting library and produce clean, publication-quality output.

Library Selection Framework

Choose the library based on what the visualization represents, not habit.

Seaborn — DEFAULT for statistical/analytical charts

Seaborn wraps matplotlib with better defaults, tighter pandas integration, and fewer lines of code. Reach for seaborn first when the data lives in a DataFrame and the goal is analytical.

Use for: distributions (histograms, KDEs, violin plots, ECDFs), categorical comparisons (box plots, swarm plots, strip plots, bar plots), correlation (heatmaps, pair plots, regression plots), grouped/faceted views (FacetGrid, catplot, relplot).

Why: Automatic axis labeling from column names, coherent color palettes, built-in aggregation with confidence intervals, and hue/col/row faceting with minimal code.

Practical rule: If the code would call plt.bar(), plt.hist(), plt.scatter(), or build a heatmap with plt.imshow() — use the seaborn equivalent instead. It will look better with less effort.

Matplotlib — fine-grained control and non-standard layouts

Drop to raw matplotlib only when seaborn doesn't support the chart type or when pixel-level layout control is required.

Use for: custom multi-panel figures mixing chart types, unusual annotations (arrows, shaded regions, custom legends), non-standard axes (polar, broken axes, insets), animations, image overlays, or any layout where the default seaborn API is insufficient.

Combine with seaborn: Seaborn plots return matplotlib Axes objects. Apply matplotlib customization on top of seaborn output rather than rebuilding from scratch.

Graphviz — graph/network structures

Graphviz operates in a fundamentally different domain: nodes and edges, not x/y data.

Use for: dependency trees, flowcharts, state machines, org charts, entity-relationship diagrams, DAGs, call graphs, any directed or undirected graph structure.

Python interface: Use the graphviz Python package (installed). Create graphviz.Digraph() or graphviz.Graph(), add nodes/edges, render to PNG/SVG/PDF.

import graphviz
g = graphviz.Digraph(format='png')
g.node('A', 'Start')
g.node('B', 'Process')
g.edge('A', 'B')
g.render('/home/claude/output', cleanup=True)

Layout engines: dot (hierarchical, default), neato (spring model), fdp (force-directed), circo (circular), twopi (radial). Set via g.engine = 'neato'.

Vega-Lite — interactive browser charts

When the user wants interactive, browser-rendered visualizations (tooltips, zoom, selection, filtering) or uploads data for exploratory charting, defer to the charting-vega-lite skill. That skill handles React artifact generation with inline data islands.

Decision shortcut: Static image file → this skill. Interactive artifact → charting-vega-lite.

Quick Reference: Chart Type → Library

| Need | Library | Function | |---|---|---| | Histogram / KDE | seaborn | sns.histplot(), sns.kdeplot() | | Box / Violin / Swarm | seaborn | sns.boxplot(), sns.violinplot() | | Bar (categorical) | seaborn | sns.barplot(), sns.countplot() | | Correlation heatmap | seaborn | sns.heatmap() | | Scatter + regression | seaborn | sns.scatterplot(), sns.regplot() | | Pair plot (multi-var) | seaborn | sns.pairplot() | | Faceted grid | seaborn | sns.FacetGrid, catplot, relplot | | Time series line | seaborn | sns.lineplot() (handles CI bands) | | Custom multi-panel | matplotlib | fig, axes = plt.subplots() | | Polar / radar | matplotlib | projection='polar' | | Annotated diagrams | matplotlib | ax.annotate(), arrows, patches | | Dependency tree | graphviz | Digraph | | Flowchart / FSM | graphviz | Digraph with shape attrs | | ER diagram | graphviz | Graph with record shapes | | Network graph | graphviz | Graph with layout engine |

Production Defaults

Apply these defaults to produce clean output without per-chart fiddling.

Seaborn Setup

import seaborn as sns
import matplotlib.pyplot as plt

sns.set_theme(style="whitegrid", palette="muted", font_scale=1.1)

Style options: whitegrid (default, good for most), white (cleaner for publications), darkgrid (data-dense plots), ticks (minimal).

Figure Sizing and DPI

fig, ax = plt.subplots(figsize=(10, 6))
# Or for seaborn figure-level functions:
g = sns.catplot(..., height=6, aspect=1.5)

# Save at publication quality
plt.savefig('/home/claude/chart.png', dpi=150, bbox_inches='tight', facecolor='white')

Use dpi=150 for screen/web output, dpi=300 for print. Always use bbox_inches='tight' to avoid clipped labels.

Color Guidance

• Categorical: "muted", "Set2", "tab10" — distinct, accessible
• Sequential: "viridis", "YlOrRd", "Blues" — ordered magnitude
• Diverging: "RdBu", "coolwarm" — centered on zero/midpoint
• Avoid: "jet", "rainbow" — perceptually non-uniform, colorblind-hostile

Common Refinements

# Rotate x-labels if overlapping
plt.xticks(rotation=45, ha='right')

# Remove top/right spines for cleaner look
sns.despine()

# Thousands separator for large numbers
ax.yaxis.set_major_formatter(plt.FuncFormatter(lambda x, _: f'{x:,.0f}'))

Output Workflow

1. Create chart in /home/claude/
2. Save as PNG (default) or SVG (if user needs vector)
3. Copy to /mnt/user-data/outputs/
4. Present via present_files

Always plt.close() after saving to free memory.