Plotly

Plotly

Python graphing library for creating interactive, publication-quality visualizations with 40+ chart types.

Quick Start

Install Plotly:

uv pip install plotly

Basic usage with Plotly Express (high-level API):

import plotly.express as pximport 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 reference/plotly-express.md [blocked] 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 reference/graph-objects.md [blocked] 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 figurefig.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 visualization)

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

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

For detailed examples and usage of all chart types, see reference/chart-types.md [blocked].

2. Layouts and Styling

Subplots: Create multi-plot figures with shared axes:

from plotly.subplots import make_subplotsimport 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 reference/layouts-styling.md [blocked].

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 templatefig.update_traces(    hovertemplate='<b>%{x}</b><br>Value: %{y:.2f}<extra></extra>')
# Add rangesliderfig.update_xaxes(rangeslider_visible=True)
# Animationsfig = px.scatter(df, x='x', y='y', animation_frame='year')

For complete interactivity guide, see reference/export-interactivity.md [blocked].

4. Export Options

Interactive HTML:

fig.write_html('chart.html')                       # Full standalonefig.write_html('chart.html', include_plotlyjs='cdn')  # Smaller file

Static Images (requires kaleido):

uv pip install kaleido

fig.write_image('chart.png')   # PNGfig.write_image('chart.pdf')   # PDFfig.write_image('chart.svg')   # SVG

For complete export options, see reference/export-interactivity.md [blocked].

Common Workflows

Scientific Data Visualization

import plotly.express as px
# Scatter plot with trendlinefig = px.scatter(df, x='temperature', y='yield', trendline='ols')
# Heatmap from matrixfig = px.imshow(correlation_matrix, text_auto=True, color_continuous_scale='RdBu')
# 3D surface plotimport plotly.graph_objects as gofig = go.Figure(data=[go.Surface(z=z_data, x=x_data, y=y_data)])

Statistical Analysis

# Distribution comparisonfig = px.histogram(df, x='values', color='group', marginal='box', nbins=30)
# Box plot with all pointsfig = px.box(df, x='category', y='value', points='all')
# Violin plotfig = px.violin(df, x='group', y='measurement', box=True)

Time Series and Financial

# Time series with rangesliderfig = px.line(df, x='date', y='price')fig.update_xaxes(rangeslider_visible=True)
# Candlestick chartimport plotly.graph_objects as gofig = 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_subplotsimport 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 pip install dash

import dashfrom dash import dcc, htmlimport 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_server(debug=True)

Reference Files

• plotly-express.md [blocked] - High-level API for quick visualizations
• graph-objects.md [blocked] - Low-level API for fine-grained control
• chart-types.md [blocked] - Complete catalog of 40+ chart types with examples
• layouts-styling.md [blocked] - Subplots, templates, colors, customization
• export-interactivity.md [blocked] - 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/