Plotly

Biblioteca de gráficos Python para criar visualizações interativas de qualidade de publicação com mais de 40 tipos de gráficos.

Quando Usar

• Você precisa de gráficos interativos com "hover" (passar o mouse), zoom, pan (arrastar) ou incorporação na web.
• Você está construindo dashboards, notebooks de análise exploratória ou apresentações que se beneficiam de rica interação.
• Você quer escolher entre Plotly Express e Graph Objects para a mesma tarefa de visualização.

Início Rápido

Instale o Plotly:

uv pip install plotly

Uso básico com Plotly Express (API de alto nível):

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

Escolhendo Entre APIs

Use Plotly Express (px)

Para visualizações rápidas e padrão com configurações sensatas:

• Trabalhando com DataFrames do pandas
• Criando tipos de gráficos comuns (dispersão, linha, barra, histograma, etc.)
• Necessidade de codificação automática de cores e legendas
• Quer código mínimo (1-5 linhas)

Veja reference/plotly-express.md para o guia completo.

Use Graph Objects (go)

Para controle detalhado e visualizações personalizadas:

• Tipos de gráficos não presentes no Plotly Express (malha 3D, isosuperfície, gráficos financeiros complexos)
• Construindo figuras complexas com múltiplos traços do zero
• Necessidade de controle preciso sobre componentes individuais
• Criando visualizações especializadas com formas e anotações personalizadas

Veja reference/graph-objects.md para o guia completo.

Nota: Plotly Express retorna um objeto Figure do graph objects, então você pode combinar abordagens:

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

Capacidades Principais

1. Tipos de Gráficos

Plotly suporta mais de 40 tipos de gráficos organizados em categorias:

Gráficos Básicos: dispersão, linha, barra, pizza, área, bolha

Gráficos Estatísticos: histograma, box plot, violino, distribuição, barras de erro

Gráficos Científicos: heatmap, contorno, ternário, exibição de imagem

Gráficos Financeiros: candlestick, OHLC, waterfall, funnel, séries temporais

Mapas: mapas de dispersão, coropléticos, mapas de densidade (visualização geográfica)

Gráficos 3D: scatter3d, superfície, malha, cone, volume

Especializados: sunburst, treemap, sankey, coordenadas paralelas, gauge

Para exemplos detalhados e uso de todos os tipos de gráficos, veja reference/chart-types.md.

2. Layouts e Estilização

Subplots: Crie figuras com múltiplos gráficos e eixos compartilhados:

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: Aplique estilização coordenada:

fig = px.scatter(df, x='x', y='y', template='plotly_dark')
# Built-in: plotly_white, plotly_dark, ggplot2, seaborn, simple_white

Personalização: Controle todos os aspectos da aparência:

• Cores (sequências discretas, escalas contínuas)
• Fontes e texto
• Eixos (intervalos, ticks, grades)
• Legendas
• Margens e dimensionamento
• Anotações e formas

Para opções completas de layout e estilização, veja reference/layouts-styling.md.

3. Interatividade

Recursos interativos integrados:

• Tooltips de "hover" com dados personalizáveis
• Pan e zoom
• Alternância de legendas
• Seleção por caixa/laço (lasso)
• Rangesliders para séries temporais
• Botões e dropdowns
• Animações

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

Para o guia completo de interatividade, veja reference/export-interactivity.md.

4. Opções de Exportação

HTML Interativo:

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

Imagens Estáticas (requer kaleido):

uv pip install kaleido

fig.write_image('chart.png')   # PNG
fig.write_image('chart.pdf')   # PDF
fig.write_image('chart.svg')   # SVG

Para opções completas de exportação, veja reference/export-interactivity.md.

Fluxos de Trabalho Comuns

Visualização de Dados Científicos

import plotly.express as px

# Gráfico de dispersão com linha de tendência
fig = px.scatter(df, x='temperature', y='yield', trendline='ols')

# Heatmap a partir de matriz
fig = px.imshow(correlation_matrix, text_auto=True, color_continuous_scale='RdBu')


…