Alterlab Plotly

---
name: alterlab-plotly
description: Builds INTERACTIVE charts with the Plotly Python library (plotly.express / graph_objects) — hover tooltips, zoom/pan, animations, rangesliders, 3D rotation, and standalone HTML/web-embeddable output. Use when a chart must be interactive or web-embedded, for dashboards (incl. Dash), exploratory data analysis, or rotatable 3D plots. For static publication figures defer to alterlab-matplotlib (or alterlab-scientific-viz for journal formatting); for static statistical charts (heatmaps, distributions) defer to alterlab-seaborn; for diagrams/schematics defer to alterlab-scientific-schematics or alterlab-mermaid. Part of the AlterLab Academic Skills suite.
license: MIT
allowed-tools: Read Write Edit Bash(python:*)
compatibility: Requires the plotly Python library, version >= 6 (current 7.1 as of 2026-09) — uv pip install plotly; static image export (PNG/PDF/SVG) additionally needs kaleido >= 1 plus a Chrome/Chromium install (run plotly_get_chrome); Dash apps need dash
metadata:
    skill-author: AlterLab
    version: "1.1.0"
    last_updated: "2026-09-23"
---

# Plotly

Python graphing library for creating interactive, publication-quality visualizations with 40+ chart types. Examples target plotly >= 6 and run on plotly 7.1 (plotly.js 4); see "Plotly 7 changes" below if you are upgrading older code.

## When to Use This Skill

Use this skill when the chart must be explored or shared interactively:
- Hover tooltips, zoom/pan, legend toggling, rangesliders, dropdowns, or animation frames
- Standalone HTML or web-embedded figures, and Dash dashboards
- Rotatable 3D plots (surface, scatter3d, mesh, volume)
- Exploratory analysis where readers need to inspect individual points

### Does NOT Trigger

| Scenario | Use Instead |
|----------|-------------|
| Static, print-ready figure with no interactivity | `alterlab-matplotlib` |
| Journal-formatted multi-panel figure (column widths, Okabe-Ito palette, significance stars) | `alterlab-scientific-viz` |
| Quick static statistical plot from a DataFrame (heatmap, pair plot, distributions) | `alterlab-seaborn` |
| Flowchart, pathway, or architecture diagram | `alterlab-scientific-schematics` / `alterlab-mermaid` |

## Quick Start

Install Plotly:
```bash
uv pip install plotly
```

Basic usage with Plotly Express (high-level API):
```python
import plotly.express as px
import pandas as pd

df = pd.DataFrame({
    'x': [1, 2, 3, 4],
    'y': [10, 11, 12, 13]
})

fig = px.scatter(df, x='x', y='y', title='My First Plot')
fig.show()
```

## Choosing Between APIs

### Use Plotly Express (px)
For quick, standard visualizations with sensible defaults:
- Working with pandas DataFrames
- Creating common chart types (scatter, line, bar, histogram, etc.)
- Need automatic color encoding and legends
- Want minimal code (1-5 lines)

See [references/plotly-express.md](references/plotly-express.md) for complete guide.

### Use Graph Objects (go)
For fine-grained control and custom visualizations:
- Chart types not in Plotly Express (3D mesh, isosurface, complex financial charts)
- Building complex multi-trace figures from scratch
- Need precise control over individual components
- Creating specialized visualizations with custom shapes and annotations

See [references/graph-objects.md](references/graph-objects.md) for complete guide.

**Note:** Plotly Express returns graph objects Figure, so you can combine approaches:
```python
fig = px.scatter(df, x='x', y='y')
fig.update_layout(title='Custom Title')  # Use go methods on px figure
fig.add_hline(y=10)                     # Add shapes
```

## Core Capabilities

### 1. Chart Types

Plotly supports 40+ chart types organized into categories:

**Basic Charts:** scatter, line, bar, pie, area, bubble

**Statistical Charts:** histogram, box plot, violin, distribution, error bars

**Scientific Charts:** heatmap, contour, ternary, image display

**Financial Charts:** candlestick, OHLC, waterfall, funnel, time series

**Maps:** scatter maps, choropleth, density maps (geographic, MapLibre-backed; the `*_mapbox` functions and traces were removed in plotly 7)

**3D Charts:** scatter3d, surface, mesh, cone, volume

**Specialized:** sunburst, treemap, sankey, parallel coordinates, gauge

For detailed examples and usage of all chart types, see [references/chart-types.md](references/chart-types.md).

### 2. Layouts and Styling

**Subplots:** Create multi-plot figures with shared axes:
```python
from plotly.subplots import make_subplots
import plotly.graph_objects as go

fig = make_subplots(rows=2, cols=2, subplot_titles=('A', 'B', 'C', 'D'))
fig.add_trace(go.Scatter(x=[1, 2], y=[3, 4]), row=1, col=1)
```

**Templates:** Apply coordinated styling:
```python
fig = px.scatter(df, x='x', y='y', template='plotly_dark')
# Built-in: plotly_white, plotly_dark, ggplot2, seaborn, simple_white
```

**Customization:** Control every aspect of appearance:
- Colors (discrete sequences, continuous scales)
- Fonts and text
- Axes (ranges, ticks, grids)
- Legends
- Margins and sizing
- Annotations and shapes

For complete layout and styling options, see [references/layouts-styling.md](references/layouts-styling.md).

### 3. Interactivity

Built-in interactive features:
- Hover tooltips with customizable data
- Pan and zoom
- Legend toggling
- Box/lasso selection
- Rangesliders for time series
- Buttons and dropdowns
- Animations

```python
# Custom hover template
fig.update_traces(
    hovertemplate='<b>%{x}</b><br>Value: %{y:.2f}<extra></extra>'
)

# Add rangeslider
fig.update_xaxes(rangeslider_visible=True)

# Animations
fig = px.scatter(df, x='x', y='y', animation_frame='year')
```

For complete interactivity guide, see [references/export-interactivity.md](references/export-interactivity.md).

### 4. Export Options

**Interactive HTML:**
```python
fig.write_html('chart.html')                       # Full standalone
fig.write_html('chart.html', include_plotlyjs='cdn')  # Smaller file
```

**Static Images (requires kaleido >= 1 and Chrome):**
```bash
uv pip install kaleido
plotly_get_chrome    # one-time: installs a Chrome build if the machine has none
```

```python
fig.write_image('chart.png', scale=3)   # PNG (700x500 default size -> 2100x1500 px)
fig.write_image('chart.pdf')            # PDF
fig.write_image('chart.svg')            # SVG
```

Without Chrome, `write_image` raises "Kaleido requires Google Chrome to be installed". Set export defaults with `plotly.io.defaults` (e.g. `pio.defaults.default_scale = 2`); the old `pio.kaleido.scope` settings no longer exist.

For complete export options, see [references/export-interactivity.md](references/export-interactivity.md).

## Common Workflows

### Scientific Data Visualization

```python
import plotly.express as px

# Scatter plot with trendline (trendline='ols'/'lowess' requires statsmodels:
#   uv pip install statsmodels)
fig = px.scatter(df, x='temperature', y='yield', trendline='ols')

# Heatmap from matrix
fig = px.imshow(correlation_matrix, text_auto=True, color_continuous_scale='RdBu')

# 3D surface plot
import plotly.graph_objects as go
fig = go.Figure(data=[go.Surface(z=z_data, x=x_data, y=y_data)])
```

### Statistical Analysis

```python
# Distribution comparison
fig = px.histogram(df, x='values', color='group', marginal='box', nbins=30)

# Box plot with all points
fig = px.box(df, x='category', y='value', points='all')

# Violin plot
fig = px.violin(df, x='group', y='measurement', box=True)
```

### Time Series and Financial

```python
# Time series with rangeslider
fig = px.line(df, x='date', y='price')
fig.update_xaxes(rangeslider_visible=True)

# Candlestick chart
import plotly.graph_objects as go
fig = go.Figure(data=[go.Candlestick(
    x=df['date'],
    open=df['open'],
    high=df['high'],
    low=df['low'],
    close=df['close']
)])
```

### Multi-Plot Dashboards

```python
from plotly.subplots import make_subplots
import plotly.graph_objects as go

fig = make_subplots(
    rows=2, cols=2,
    subplot_titles=('Scatter', 'Bar', 'Histogram', 'Box'),
    specs=[[{'type': 'scatter'}, {'type': 'bar'}],
           [{'type': 'histogram'}, {'type': 'box'}]]
)

fig.add_trace(go.Scatter(x=[1, 2, 3], y=[4, 5, 6]), row=1, col=1)
fig.add_trace(go.Bar(x=['A', 'B'], y=[1, 2]), row=1, col=2)
fig.add_trace(go.Histogram(x=data), row=2, col=1)
fig.add_trace(go.Box(y=data), row=2, col=2)

fig.update_layout(height=800, showlegend=False)
```

## Integration with Dash

For interactive web applications, use Dash (Plotly's web app framework):

```bash
uv pip install dash
```

```python
import dash
from dash import dcc, html
import plotly.express as px

app = dash.Dash(__name__)

fig = px.scatter(df, x='x', y='y')

app.layout = html.Div([
    html.H1('Dashboard'),
    dcc.Graph(figure=fig)
])

app.run(debug=True)  # Dash >= 3 (current 4.x): run_server() was removed; use app.run()
```

## Plotly 7 changes (August 2026)

Plotly 7.0 moved to plotly.js 4 and removed long-deprecated APIs. When older code fails:
- `px.scatter_mapbox` / `density_mapbox` / `choropleth_mapbox` / `line_mapbox` and the `go.*mapbox` traces are gone — use `px.scatter_map`, `px.density_map`, `px.choropleth_map`, `px.line_map` (MapLibre, `map_style=`, no token).
- Deprecated figure-factory functions were removed (`create_annotated_heatmap`, `create_distplot`, `create_gantt`, `create_facet_grid`, `create_scatterplotmatrix`, `create_violin`, `create_candlestick`, `create_ohlc`, and others). Use Plotly Express instead: `px.imshow(z, text_auto=True)`, `px.histogram(..., marginal='rug')`, `px.timeline`, `px.scatter_matrix`, `px.violin`, `go.Candlestick`/`go.Ohlc`. `ff.create_dendrogram`, `create_quiver`, `create_streamline`, `create_table`, `create_trisurf`, and `create_ternary_contour` remain.
- Static export supports only Kaleido >= 1 (no Orca), and the `engine=` argument to `write_image`/`to_image` was removed.
- Color strings: `rgb()`/`rgba()` with 0–1 fractional channels and `hsv()` are no longer supported; newer forms such as `rgba(255 0 0 / 0.5)`, `#ff0000aa`, and `oklch()` now work.
- New `go.Quiver` trace for vector fields.

## Reference Files

- **[plotly-express.md](references/plotly-express.md)** - High-level API for quick visualizations
- **[graph-objects.md](references/graph-objects.md)** - Low-level API for fine-grained control
- **[chart-types.md](references/chart-types.md)** - Complete catalog of 40+ chart types with examples
- **[layouts-styling.md](references/layouts-styling.md)** - Subplots, templates, colors, customization
- **[export-interactivity.md](references/export-interactivity.md)** - Export options and interactive features

## Additional Resources

- Official documentation: https://plotly.com/python/
- API reference: https://plotly.com/python-api-reference/
- Community forum: https://community.plotly.com/