Matplotlib

Visão Geral

Matplotlib é a biblioteca fundamental de visualização do Python para criar gráficos estáticos, animados e interativos. Esta habilidade fornece orientação sobre como usar o matplotlib de forma eficaz, cobrindo tanto a interface pyplot (estilo MATLAB) quanto a API orientada a objetos (Figure/Axes), juntamente com as melhores práticas para criar visualizações de qualidade para publicação.

Quando Usar Esta Habilidade

Esta habilidade deve ser usada quando:

• Criar qualquer tipo de gráfico ou diagrama (linha, dispersão, barra, histograma, mapa de calor, contorno, etc.)
• Gerar visualizações científicas ou estatísticas
• Personalizar a aparência dos gráficos (cores, estilos, rótulos, legendas)
• Criar figuras com múltiplos painéis com subplots
• Exportar visualizações para vários formatos (PNG, PDF, SVG, etc.)
• Construir gráficos interativos ou animações
• Trabalhar com visualizações 3D
• Integrar gráficos em notebooks Jupyter ou aplicações GUI

Configuração

Para trabalho em projetos, instale o Matplotlib com uv:

uv add "matplotlib==3.11.2" numpy scipy

Para interatividade em notebooks:

uv add "matplotlib==3.11.2" ipympl

Em seguida, habilite o backend de widgets no Jupyter com %matplotlib widget ou %matplotlib ipympl.

O alvo é Matplotlib 3.11.2 (Python 3.11+), revisado em 2026-10-01. Os scripts empacotados e exemplos representativos foram executados usando Agg e saída PNG/PDF/SVG. Janelas GUI, widgets Jupyter e LaTeX externo dependem do ambiente e não foram exercitados. Exemplos de fragmentos assumem importações e dados nomeados; adapte-os e valide-os antes de usar. Verifique as alterações da API 3.11 ao migrar código antigo: use tick_labels e orientation para box plots, mpl.colormaps[name] para mapas de cores e rotule linhas de contorno em vez de contourf.

A saída de arquivo não requer GUI. Use MPLBACKEND=Agg para scripts em lote ou selecione Agg antes de importar pyplot. A saída interativa requer um toolkit GUI instalado, como PySide6 (QtAgg) ou Tk funcional (TkAgg); plt.ioff() não remove os requisitos de thread da GUI. Veja backends.

Conceitos Principais

A Hierarquia do Matplotlib

Matplotlib usa uma estrutura hierárquica de objetos:

1. Figure - O contêiner de nível superior para todos os elementos do gráfico
2. Axes - A área de plotagem real onde os dados são exibidos (uma Figure pode conter múltiplos Axes)
3. Artist - Tudo o que é visível na figura (linhas, texto, ticks, etc.)
4. Axis - Os objetos de linha numérica (eixo x, eixo y) que gerenciam ticks e rótulos

Duas Interfaces

1. Interface pyplot (Implícita, estilo MATLAB)

import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4])
plt.ylabel('some numbers')
plt.show()

• Conveniente para gráficos rápidos e simples
• Mantém o estado automaticamente
• Bom para trabalho interativo e scripts simples

2. Interface Orientada a Objetos (Explícita)

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4])
ax.set_ylabel('some numbers')
plt.show()

• Recomendada para a maioria dos casos de uso
• Controle mais explícito sobre figura e eixos
• Melhor para figuras complexas com múltiplos subplots
• Mais fácil de manter e depurar

Fluxos de Trabalho Comuns

1. Criação de Gráfico Básico

Fluxo de trabalho de gráfico único:

import matplotlib.pyplot as plt
import numpy as np

# Create figure and axes (OO interface - RECOMMENDED)
fig, ax = plt.subplots(figsize=(10, 6))

# Generate and plot data
x = np.linspace(0, 2*np.pi, 100)
ax.plot(x, np.sin(x), label='sin(x)')
ax.plot(x, np.cos(x), label='cos(x)')

# Customize
ax.set_xlabel('x')
ax.set_ylabel('y')
ax.set_title('Trigonometric Functions')
ax.legend()
ax.grid(True, alpha=0.3)

# Save and/or display
fig.savefig('plot.png', dpi=300, bbox_inches='tight')
plt.show()

2. Múltiplos Subplots

Criando layouts de subplot:

# Método 1: Grade regular
fig, axes = plt.subplots(2, 2, figsize=(12, 10))
axes[0, 0].plot(x, y1)
axes[0, 1].scatter(x, y2)
axes[1, 0].bar(categories, values)
axes[1, 1].hist(data, bins=30)

# Método 2: Layout de mosaico (mais flexível)
fig, axes = plt.subplot_mosaic([['left', 'right_top'],
                                 ['left', 'right_bottom']],
                                figsize=(10, 8))
axes['left'].plot(x, y)
axes['right_top'].scatter(x, y)
axes['right_bottom'].hist(data)

# Método 3: GridSpec (controle máximo)
from matplotlib.gridspec import GridSpec
fig = plt.figure(figsize=(12, 8))
gs = GridSpec(3, 3, figure=fig)

…