plotly

name	plotly
description	A high-level interactive graphing library for Python. Ideal for web-based visualizations, 3D plots, and complex interactive dashboards. Built on plotly.js, it allows users to zoom, pan, and hover over data points in a browser-based environment. Use for interactive charts, web applications, Jupyter notebooks, 3D data visualization, geographic maps, financial charts, animations, time-series analysis, and building production-ready dashboards with Dash.
version	5.18
license	MIT

Plotly - Interactive Visualization

Plotly provides a wide range of interactive charts. Its "Plotly Express" API is designed for speed and ease of use with tidy DataFrames, while "Graph Objects" offers low-level control over every trace and attribute.

When to Use

• Creating interactive charts for web applications or Jupyter notebooks
• Visualizing 3D data (surfaces, scatter, mesh)
• Geographic maps (scatter on maps, choropleths) with Mapbox integration
• Financial charts (candlestick, OHLC)
• Exploring large datasets where zooming into specific regions is required
• Creating animations (time-series sliders)
• Building production-ready dashboards (via Dash)

Reference Documentation

Official docs: https://plotly.com/python/
Plotly Express: https://plotly.com/python/plotly-express/
Search patterns: px.scatter, go.Figure, fig.update_layout, fig.write_html, px.choropleth

Core Principles

Plotly Express (px) vs. Graph Objects (go)

Feature	Plotly Express (px)	Graph Objects (go)
Complexity	High-level, concise.	Low-level, verbose.
Data Format	Tidy (long-form) DataFrames.	Lists, Arrays, Dicts, or DataFrames.
Customization	Good (using update_*).	Maximum / Full control.
Speed of Dev	Very fast.	Slower.

Use Plotly For

• Interactive exploration (hover, zoom)
• 3D and Geospatial visualization
• Exporting to standalone interactive HTML files
• Integration with Dash

Do NOT Use For

• Publication-quality static LaTeX plots (use Matplotlib)
• Very large static image generation (Matplotlib is faster)
• Low-memory environments (Plotly's JSON-based figures are memory-heavy)

Quick Reference

Installation

pip install plotly pandas

Standard Imports

import plotly.express as px
import plotly.graph_objects as go
import pandas as pd
import numpy as np

Basic Pattern - Plotly Express

import plotly.express as px

# Load data
df = px.data.iris()

# Create interactive scatter plot
fig = px.scatter(df, x="sepal_width", y="sepal_length", 
                 color="species", size="petal_length",
                 hover_data=['petal_width'])

# Display
fig.show()

Critical Rules

✅ DO

• Use Plotly Express first - 90% of tasks are easier with px
• Prefer Tidy Data - Ensure one row per observation for easy mapping to colors/axes
• Use update_layout - Cleanly modify titles, fonts, and background colors
• Save as HTML - Use fig.write_html("plot.html") to share interactive charts
• Leverage Hover Data - Add context to points without cluttering the plot
• Set Figure Templates - Use template="plotly_dark" or "ggplot2" for instant style
• Use marginal_x/y - In px.scatter, quickly add histograms or boxplots to margins

❌ DON'T

• Pass huge datasets to the browser - Plotting >50k points can lag the UI; use datashader or decimation
• Manual looping with go - If px can do it, don't use a for-loop to add traces in go
• Forget to set axis labels - px uses column names; rename them in the DataFrame for better labels
• Over-animate - Smooth animations are cool, but too many moving parts distract from the data

Anti-Patterns (NEVER)

# ❌ BAD: Over-complicating a simple plot with Graph Objects
fig = go.Figure()
for species in df['species'].unique():
    sub = df[df['species'] == species]
    fig.add_trace(go.Scatter(x=sub['sepal_w'], y=sub['sepal_l'], name=species))

# ✅ GOOD: Use Plotly Express (One line, automatic legend/colors)
fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species")

# ❌ BAD: Mixing list-style data with DataFrame-style data in px
px.scatter(x=[1,2,3], y=df['column']) # Can lead to alignment issues

# ✅ GOOD: Stick to the DataFrame
px.scatter(df, x="column_a", y="column_b")

Plotly Express (px) Deep Dive

Statistical Charts

# Boxplot with points
fig = px.box(df, x="day", y="total_bill", color="smoker", points="all")

# Violin plot with box inside
fig = px.violin(df, x="day", y="total_bill", color="sex", box=True, points="all")

# Heatmap (Density Contour)
fig = px.density_heatmap(df, x="total_bill", y="tip", marginal_x="histogram", marginal_y="histogram")

Time Series and Faceting

df = px.data.stocks()
# Multiple lines from wide data
fig = px.line(df, x='date', y=["GOOG", "AAPL", "AMZN"], title="Tech Stocks")

# Faceting (Subplots by category)
df = px.data.tips()
fig = px.scatter(df, x="total_bill", y="tip", color="smoker", 
                 facet_col="day", facet_row="time")

3D Visualization

Scatter, Lines, and Surfaces

# 3D Scatter
fig = px.scatter_3d(df, x='sepal_length', y='sepal_width', z='petal_width', color='species')

# 3D Surface (Using Graph Objects)
z_data = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/api_docs/mt_bruno_elevation.csv')
fig = go.Figure(data=[go.Surface(z=z_data.values)])
fig.update_layout(title='Mt Bruno Elevation', autosize=False,
                  width=500, height=500, margin=dict(l=65, r=50, b=65, t=90))

Geospatial Analysis

Maps and Choropleths

# Scatter on a map
df = px.data.gapminder().query("year == 2007")
fig = px.scatter_geo(df, locations="iso_alpha", color="continent",
                     hover_name="country", size="pop",
                     projection="natural earth")

# Detailed Mapbox Choropleth (Needs token or use open-street-map)
fig = px.choropleth_mapbox(df, geojson=counties, locations='fips', color='unemp',
                           color_continuous_scale="Viridis",
                           mapbox_style="carto-positron",
                           zoom=3, center = {"lat": 37.0902, "lon": -95.7129})

Layout and Styling (fig.update_*)

Fine-tuning the appearance

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

# Global layout updates
fig.update_layout(
    title="Custom Styled Plot",
    xaxis_title="Dimension X",
    yaxis_title="Dimension Y",
    font=dict(family="Courier New, monospace", size=18, color="RebeccaPurple"),
    legend=dict(yanchor="top", y=0.99, xanchor="left", x=0.01),
    plot_bgcolor="white"
)

# Axis specific updates
fig.update_xaxes(showgrid=True, gridwidth=1, gridcolor='LightPink')
fig.update_yaxes(zeroline=True, zerolinewidth=2, zerolinecolor='Black')

Advanced Interaction: Animations

df = px.data.gapminder()
fig = px.scatter(df, x="gdpPercap", y="lifeExp", animation_frame="year", 
                 animation_group="country",
                 size="pop", color="continent", hover_name="country",
                 log_x=True, size_max=55, range_x=[100, 100000], range_y=[25, 90])

Practical Workflows

1. Interactive Scientific Report Export

def create_interactive_report(df, filename="report.html"):
    """Generates a multi-chart HTML report."""
    fig1 = px.scatter(df, x="A", y="B", color="C")
    fig2 = px.histogram(df, x="A", color="C")
    
    with open(filename, 'a') as f:
        f.write(fig1.to_html(full_html=False, include_plotlyjs='cdn'))
        f.write(fig2.to_html(full_html=False, include_plotlyjs='cdn'))

# Useful for sharing findings with non-technical stakeholders

2. Financial Dashboard Fragment (Candlestick)

import pandas as pd
from datetime import datetime

df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv')

fig = go.Figure(data=[go.Candlestick(x=df['Date'],
                open=df['AAPL.Open'],
                high=df['AAPL.High'],
                low=df['AAPL.Low'],
                close=df['AAPL.Close'])])

# Remove rangeslider for cleaner look
fig.update_layout(xaxis_rangeslider_visible=False)

3. Mixing Subplots with go.Figure

from plotly.subplots import make_subplots

fig = make_subplots(rows=1, cols=2, subplot_titles=("Plot A", "Plot B"))

fig.add_trace(go.Scatter(x=[1, 2, 3], y=[4, 5, 6]), row=1, col=1)
fig.add_trace(go.Bar(x=[1, 2, 3], y=[2, 3, 5]), row=1, col=2)

fig.update_layout(height=600, width=800, title_text="Side-by-Side Comparison")

Performance Optimization

WebGL for Large Datasets

# For scatter plots with >10,000 points, use Scattergl (Graph Objects)
# or tell px to use webgl (available in newer versions)
fig = px.scatter(df, x="large_x", y="large_y", render_mode="webgl")

# WebGL drastically improves performance by using the GPU for rendering.

Common Pitfalls and Solutions

JSON Overhead in Notebooks

# ❌ Problem: Notebook file size explodes to 50MB
# ✅ Solution: Display as static image (requires kaleido) or use a different renderer
# fig.show(renderer="png") # Static
# OR: Clear output after viewing

Axis Scaling in Animations

# ❌ Problem: Axes jump around during animation
# ✅ Solution: Manually fix the ranges
fig = px.scatter(df, x="x", y="y", animation_frame="time",
                 range_x=[0, 100], range_y=[0, 100])

Handling Missing Categories in Legend

# ❌ Problem: Colors change when filtering data because categories disappear
# ✅ Solution: Pass a category_orders dictionary
fig = px.scatter(df, x="x", y="y", color="category",
                 category_orders={"category": ["A", "B", "C", "D"]})

Best Practices

1. Use Plotly Express first - Start with px for 90% of tasks; only use go when you need fine-grained control
2. Work with tidy DataFrames - Ensure one row per observation for easy mapping to visual attributes
3. Use update_layout for styling - Cleanly modify titles, fonts, and background colors without recreating figures
4. Save as HTML for sharing - Use fig.write_html("plot.html") to share interactive charts with stakeholders
5. Leverage hover data - Add context to points without cluttering the plot
6. Set figure templates - Use template="plotly_dark" or "ggplot2" for instant professional styling
7. Use marginal plots - In px.scatter, use marginal_x and marginal_y to quickly add histograms or boxplots
8. Optimize for large datasets - Use WebGL rendering or datashader for datasets with >50k points
9. Fix axis ranges in animations - Use range_x and range_y to prevent axes from jumping during animations
10. Set category orders - Use category_orders to maintain consistent colors when filtering data

Plotly bridges the gap between static analysis and interactive discovery. It is the best tool for moving scientific insights from a notebook to the web.