domains / data / interactive-visualization / plotly

plotly

Skill card

combined

The first two copies (Vibe-Skills and agentic-awesome-skills) are nearly identical, providing a standard, general-purpose guide to Plotly with code examples for Express and Graph Objects. The third copy (medical-research-skills) adds specific version constraints and a generic 'checklist-driven' execution model. The fourth copy (Auto-Empirical-Research-Skills) is distinct: it mandates a 'file-first' execution protocol for research pipelines (writing scripts to specific directories before execution) and explicitly forbids the use of Kaleido for static image export due to environment constraints, recommending plotnine instead. This creates a conflict with the other copies, which recommend installing Kaleido for static exports. Because the fourth copy contains a critical environmental constraint and workflow protocol that the others lack, and the others contain general code examples the fourth copy omits in favor of reference files, they must be combined to provide a complete and non-contradictory instruction set.

Repositories

Other copies

Combined skill

---
name: plotly
description: Interactive scientific and statistical data visualization library for Python. Use when creating charts, plots, or visualizations including scatter plots, line charts, bar charts, heatmaps, 3D plots, geographic maps, statistical distributions, financial charts, and dashboards. Supports both quick visualizations (Plotly Express) and fine-grained customization (graph objects). Outputs interactive HTML or static images (PNG, PDF, SVG).
---

# Plotly

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

## When to Use
- You need interactive charts with hover, zoom, pan, or web embedding.
- You are building dashboards, exploratory analysis notebooks, or presentations that benefit from rich interaction.
- You want to choose between Plotly Express and Graph Objects for the same visualization task.
- **Research Workflows:** If operating within a strict research pipeline (e.g., DAAF), follow the File-First Execution Protocol below.

## 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)

### 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

**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:** scatter, line, bar, pie, area, bubble
- **Statistical:** histogram, box plot, violin, distribution, error bars
- **Scientific:** heatmap, contour, ternary, image display
- **Financial:** candlestick, OHLC, waterfall, funnel, time series
- **Maps:** scatter maps, choropleth, density maps
- **3D:** scatter3d, surface, mesh, cone, volume
- **Specialized:** sunburst, treemap, sankey, parallel coordinates, gauge

### 2. Layouts and Styling
- **Subplots:** Use `make_subplots` for multi-plot figures with shared axes.
- **Templates:** Apply coordinated styling (e.g., `plotly_dark`, `ggplot2`).
- **Customization:** Control colors, fonts, axes, legends, margins, and annotations.

### 3. Interactivity
- Hover tooltips, pan/zoom, legend toggling.
- Box/lasso selection.
- Rangesliders for time series.
- Buttons, dropdowns, and animations.

### 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:**
*Conflict Resolution:* 
- **General Use:** Install Kaleido (`uv pip install kaleido`) and use `fig.write_image('chart.png')` for PNG, PDF, or SVG.
- **Research/DAAF Environments:** Kaleido may be unavailable due to heavy dependencies. In these contexts, **do not** attempt static image export with Plotly. Use `plotnine` or other static libraries for publication figures, and restrict Plotly to HTML output.

## Common Workflows

### Scientific Data Visualization
```python
# 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')
```

### 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')
```

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

## File-First Execution in Research Workflows

**Important:** In data research pipelines (e.g., DAAF), all visualizations are generated through **script files**, not interactively, to ensure auditability and reproducibility.

**The Pattern:**
1. Write plot code FIRST to `scripts/stage8_analysis/{step}_{plot-name}.py`.
2. Execute via Bash with automatic output capture wrapper script.
3. Validation results get automatically embedded in scripts as comments.
4. If failed, create versioned copy for fixes.

*Note: This protocol applies only to specific research environments. For general use, direct execution or notebook cells are acceptable.*

## Dependencies
- `plotly>=5.0`
- `pandas>=1.5` (recommended)
- `kaleido>=0.2` (optional, for static export in general environments)
- `dash>=2.0` (optional, for web apps)