plotly

# Plotly Python graphing library for creating interactive, publication-quality visualizations with 40+ chart types. ## 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 [reference/plotly-express.md](reference/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 [reference/graph-objects.md](reference/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 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](reference/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 [reference/layouts-styling.md](reference/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 [reference/export-interactivity.md](reference/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):** ```bash uv pip install kaleido ``` ```python fig.write_image('chart.png') # PNG fig.write_image('chart.pdf') # PDF fig.write_image('chart.svg') # SVG ``` For complete export options, see [reference/export-interactivity.md](reference/export-interactivity.md). ## Common Workflows ### Scientific Data Visualization ```python import plotly.express as px # Scatter plot with trendline 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_server(debug=True) ``` ## Reference Files - **[plotly-express.md](reference/plotly-express.md)** - High-level API for quick visualizations - **[graph-objects.md](reference/graph-objects.md)** - Low-level API for fine-grained control - **[chart-types.md](reference/chart-types.md)** - Complete catalog of 40+ chart types with examples - **[layouts-styling.md](reference/layouts-styling.md)** - Subplots, templates, colors, customization - **[export-interactivity.md](reference/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/