alterlab-plotly
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.
How do I install this agent skill?
npx skills add https://github.com/alterlab-ieu/alterlab-academic-skills --skill alterlab-plotlyIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The alterlab-plotly skill is a legitimate and secure toolkit for generating interactive visualizations using the industry-standard Plotly library. It provides safe code examples, uses trusted dependencies, and refers to official documentation without any malicious patterns.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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 |
Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-matplotlib) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.
Quick Start
Run Plotly without installing anything: uv resolves it per call, with no virtualenv (uv pip install fails outside one). Add --with pandas for DataFrames and --with statsmodels for OLS/LOWESS trendlines:
uv run --python ">=3.11" --with plotly --with pandas python make_chart.py
Basic usage with Plotly Express (high-level API):
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 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 for complete guide.
Note: Plotly Express returns graph objects Figure, so you can combine approaches:
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.
2. Layouts and Styling
Subplots: Create multi-plot figures with shared axes:
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:
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.
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
# 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.
4. Export Options
Interactive HTML:
fig.write_html('chart.html') # Full standalone
fig.write_html('chart.html', include_plotlyjs='cdn') # Smaller file
Static Images (requires kaleido >= 1 and Chrome):
uv run --python ">=3.11" --with plotly --with kaleido python make_chart.py
uv run --python ">=3.11" --with plotly --with kaleido plotly_get_chrome # one-time: installs a Chrome build if the machine has none
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.
5. Reporting the Result
When the chart is built in a script, the reply must still show how: quote the few lines that make it — the px/go call with its key arguments (e.g. trendline, hover_data/hovertemplate) and the export call with its arguments (fig.write_html(path, include_plotlyjs=...), fig.to_html(...) or fig.write_image(...)) — and give the path of every file written. Describing the chart in prose is not enough for someone who has to rebuild or adjust it.
Common Workflows
Scientific Data Visualization
import plotly.express as px
# Scatter plot with trendline (trendline='ols'/'lowess' requires statsmodels:
# add --with statsmodels to the uv run line)
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
# 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
# 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
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):
uv run --python ">=3.11" --with dash python app.py
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_mapboxand thego.*mapboxtraces are gone — usepx.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, andcreate_ternary_contourremain. - Static export supports only Kaleido >= 1 (no Orca), and the
engine=argument towrite_image/to_imagewas removed. - Color strings:
rgb()/rgba()with 0–1 fractional channels andhsv()are no longer supported; newer forms such asrgba(255 0 0 / 0.5),#ff0000aa, andoklch()now work. - New
go.Quivertrace for vector fields.
Reference Files
- plotly-express.md - High-level API for quick visualizations
- graph-objects.md - Low-level API for fine-grained control
- chart-types.md - Complete catalog of 40+ chart types with examples
- layouts-styling.md - Subplots, templates, colors, customization
- 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/
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/alterlab-ieu/alterlab-academic-skills/alterlab-plotly">View alterlab-plotly on skillZs</a>