Primeiros Passos
Instalação e Primeiro Gráfico
Matplotlib é a base dos gráficos em Python. pyplot é a interface baseada em estado (como MATLAB). Sempre chame plt.show() para renderizar a figura num script; em notebooks Jupyter a figura é renderizada automaticamente quando a célula termina.
# install
pip install matplotlib
import matplotlib.pyplot as plt
import numpy as np
# a simple line plot
x = np.linspace(0, 10, 100)
y = np.sin(x)
plt.plot(x, y)
plt.title("Sine Wave")
plt.xlabel("x")
plt.ylabel("sin(x)")
plt.show()Interface de Estado do pyplot
A interface pyplot espelha o MATLAB: cada chamada opera na figura/eixos 'atual' acompanhada internamente. É concisa para gráficos rápidos, mas pode ficar confusa com múltiplos subplots. Use plt.gcf()/plt.gca() para acessar os objetos atuais de figura/eixos.
import matplotlib.pyplot as plt
# pyplot tracks the "current" figure and axes
plt.figure() # create a new figure
plt.plot([1, 2, 3], [4, 5, 2])
plt.title("State-based") # applies to the current axes
plt.xlim(0, 4)
plt.ylim(0, 6)
plt.show()
# plt.gcf() -> current figure, plt.gca() -> current axes
print(plt.gca())Figure e Axes (Interface OO)
A interface Orientada a Objetos (OO) é a abordagem recomendada para tudo além de um único gráfico. Você cria uma Figure (a tela inteira) e um ou mais Axes (gráficos individuais) e chama funções neles. Escala de forma limpa para subplots, eixos gêmeos e layouts complexos.
import matplotlib.pyplot as plt
import numpy as np
# object-oriented interface: explicit Figure and Axes objects
fig, ax = plt.subplots() # fig is the canvas, ax is a single Axes
x = np.linspace(0, 5, 50)
ax.plot(x, x**2, label="x^2")
ax.plot(x, x**3, label="x^3")
ax.set_title("OO Interface")
ax.set_xlabel("x")
ax.set_ylabel("y")
ax.legend()
plt.show()Imports e Convenções Comuns
plt é o apelido quase universal para pyplot e np para NumPy — quase qualquer tutorial ou biblioteca espera esses nomes. rcParams é o dicionário global de configuração: defina-o uma vez no topo do script para fixar DPI, tamanho de fonte, tamanho da figura e muitos outros padrões.
# the universal alias
import matplotlib.pyplot as plt
import numpy as np
# for the OO interface you often see
from matplotlib.figure import Figure
from matplotlib.axes import Axes
# set a global style once
plt.rcParams["figure.dpi"] = 100
plt.rcParams["font.size"] = 11
# inline backend in Jupyter (not needed in scripts)
# %matplotlib inlineBackends e plt.show()
Um backend renderiza a figura: backends interativos (TkAgg, Qt5Agg) abrem janela, os não interativos (Agg) só escrevem arquivos. Chame matplotlib.use() antes de importar pyplot. plt.show() bloqueia em scripts até as janelas fecharem; no Jupyter, %matplotlib inline embute figuras no notebook.
import matplotlib
# list available backends
print(matplotlib.rcsetup.all_backends)
# force a backend (do this BEFORE importing pyplot)
# matplotlib.use("Agg") # non-interactive, for saving files
# matplotlib.use("TkAgg") # interactive Tk window
import matplotlib.pyplot as plt
plt.plot([1, 2, 3])
# plt.show() blocks until the window is closed
plt.savefig("out.png") # saving works without any GUI backendGráficos de Linha (plot)
Gráfico de Linha Básico
plt.plot(x, y) desenha uma linha ligando os pontos (x, y) em ordem. Se você passar um único array, ele é usado como y e x assume 0..N-1. plt.grid(True) alterna as linhas de grade. Os pontos são ligados na ordem do array, então para uma curva suave ordene x primeiro.
import matplotlib.pyplot as plt
import numpy as np
x = np.arange(0, 10, 0.5)
y = x * 2
plt.plot(x, y)
plt.title("y = 2x")
plt.xlabel("x")
plt.ylabel("y")
plt.grid(True)
plt.show()Múltiplas Linhas
Cada chamada plt.plot() adiciona uma nova linha aos eixos atuais e avança automaticamente o ciclo de cores. Passe um label= em cada uma para que plt.legend() possa identificá-las. O Matplotlib ajusta os limites dos eixos automaticamente, expandindo para caber o maior intervalo.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 2 * np.pi, 100)
plt.plot(x, np.sin(x), label="sin")
plt.plot(x, np.cos(x), label="cos")
plt.plot(x, np.sin(x) + np.cos(x), label="sin+cos")
plt.legend()
plt.title("Trig Functions")
plt.show()Estilos de Linha e Marcadores
A string de formato 'cor+marcador+estilo' (ex.: 'ro--') é compacta, mas críptica. Prefira argumentos nomeados explícitos color=, marker=, linestyle= para um código legível. Estilos comuns de linha: '-' '--' ':' '-.'. Marcadores comuns: 'o' 's' '^' 'D' 'v' '+' 'x'.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 5, 20)
# format string: [color][marker][linestyle]
plt.plot(x, x, "r-") # red solid line
plt.plot(x, x*2, "go--") # green circles, dashed
plt.plot(x, x*3, "bs:") # blue squares, dotted
plt.plot(x, x*4, "k^-.") # black triangles, dash-dot
# explicit kwargs (clearer, recommended)
plt.plot(x, x*5, color="purple", marker="D",
linestyle="-.", linewidth=2, markersize=6)Cores
O Matplotlib aceita vários formatos de cor: nomes ('red'), strings hexadecimais ('#FF8800'), tuplas RGB(A), nomes Tableau ('tab:blue'), referências de ciclo ('C0'..'C9') e strings de tons de cinza ('0.5'). 'C0' pega a primeira cor do estilo atual, mantendo os gráficos consistentes com o ciclo de cores.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 1, 30)
plt.plot(x, x, color="red") # named color
plt.plot(x, x+0.2, color="#FF8800") # hex RGB
plt.plot(x, x+0.4, color=(0.1, 0.8, 0.2))# RGB tuple 0-1
plt.plot(x, x+0.6, color="C0") # cycle color 0
plt.plot(x, x+0.8, color="tab:purple") # Tableau palette
# gray shorthand: a string of float in [0,1]
plt.plot(x, x+1.0, color="0.5") # mid gray
plt.show()Espessura, Alpha e zorder
linewidth controla a espessura do traço (padrão 1.5). alpha define a transparência e é essencial quando curvas se sobrepõem, para enxergar o que está por baixo. zorder controla o empilhamento — valores maiores são desenhados depois (em cima). O zorder padrão é 2 para linhas e 1 para patches.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 10, 100)
# alpha = transparency (0 invisible, 1 opaque)
# zorder = draw order; higher draws on top
plt.fill_between(x, np.sin(x), alpha=0.3, zorder=1)
plt.plot(x, np.sin(x), linewidth=2, zorder=2)
plt.plot(x, np.cos(x), linewidth=4, alpha=0.7, zorder=3)
plt.show()Gráficos de Degraus (step/stairs)
plt.step() desenha funções degrau, úteis para sinais digitais e dados discretos; where controla onde o degrau sobe ('pre', 'post', 'mid'). plt.stairs() (3.4+) é o equivalente moderno: recebe valores y e bordas de bins separadas, e integra bem com dados tipo histograma.
import matplotlib.pyplot as plt
import numpy as np
x = np.arange(5)
y = [1, 3, 2, 4, 3]
# step: like plot but with horizontal/vertical steps
plt.step(x, y, where="post", label="post")
plt.step(x, y + 1, where="mid", label="mid")
plt.step(x, y + 2, where="pre", label="pre")
plt.legend(title="where=")
# stairs (matplotlib 3.4+): step from explicit bin edges
plt.stairs([1, 2, 1], baseline=0)
plt.show()Gráficos de Dispersão
Dispersão Básica
plt.scatter(x, y) plota pontos sem linhas de ligação. É mais lento que plt.plot(x, y, 'o') quando você tem dezenas de milhares de pontos, porque o scatter permite tamanho e cor individuais por ponto. Use plt.plot com marcador para velocidade máxima com estilo uniforme.
import matplotlib.pyplot as plt
import numpy as np
rng = np.random.default_rng(0)
x = rng.random(50)
y = rng.random(50)
plt.scatter(x, y)
plt.title("Basic Scatter")
plt.xlabel("x")
plt.ylabel("y")
plt.axis("equal") # equal aspect ratio
plt.show()Tamanho e Cor do Marcador
O argumento s é a ÁREA do marcador em pontos ao quadrado (não o raio), então um s 4x maior é só 2x o raio. O argumento c (cor) com cmap mapeia um array numérico num colormap. Use alpha < 1 quando os pontos se sobrepõem, para que a densidade fique visível.
import matplotlib.pyplot as plt
import numpy as np
rng = np.random.default_rng(1)
n = 50
x = rng.random(n)
y = rng.random(n)
sizes = rng.random(n) * 500 # area in points^2
colors = rng.random(n) # mapped to colormap
plt.scatter(x, y, s=sizes, c=colors, cmap="viridis", alpha=0.6)
plt.colorbar(label="value")
plt.title("Bubble Chart")
plt.show()Dispersão com Colormap
Passar um array 1-D para c mapeia cada ponto num colormap; plt.colorbar(sc) adiciona uma barra de cores (você precisa passar o retorno do scatter para que a barra conheça o mapeamento). vmin/vmax fixam o intervalo do colormap; sem eles, o matplotlib autoescala para o mínimo/máximo dos dados.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 10, 200)
y = np.sin(x)
c = x # color by x value
sc = plt.scatter(x, y, c=c, cmap="plasma", vmin=0, vmax=10)
cb = plt.colorbar(sc)
cb.set_label("x position")
plt.title("Colored by x")
plt.show()Transparência e Overplotting
Com muitos pontos sobrepostos, uma dispersão sólida esconde a densidade. Baixe o alpha para ~0.05 e diminua o marcador para revelar a estrutura. Para dados muito grandes (100k+ pontos), plt.hexbin ou plt.hist2d agregam em bins e são mais rápidos e mais claros que a dispersão bruta.
import matplotlib.pyplot as plt
import numpy as np
rng = np.random.default_rng(2)
n = 5000
x = rng.normal(0, 1, n)
y = rng.normal(0, 1, n)
# dense scatter: low alpha reveals density
plt.scatter(x, y, s=5, alpha=0.05, c="navy")
plt.title("Density via alpha")
# alternative: hexbin for very large datasets
plt.figure()
plt.hexbin(x, y, gridsize=40, cmap="Blues")
plt.colorbar(label="count")
plt.show()Dispersão Categórica
O Matplotlib não tem strip plot embutido, então scatter com jitter manual no eixo x é a abordagem DIY padrão. Para gráficos categóricos de qualidade de publicação (box, violin, swarm), prefira o Seaborn, que é construído sobre o Matplotlib e se integra ao estilo do plt.
import matplotlib.pyplot as plt
import numpy as np
rng = np.random.default_rng(3)
groups = ["A", "B", "C"]
data = [rng.normal(0, 1, 30),
rng.normal(2, 1, 30),
rng.normal(1, 1.5, 30)]
for i, d in enumerate(data):
# add jitter on x so points do not stack on one line
jitter = rng.uniform(-0.1, 0.1, len(d))
plt.scatter(np.full(len(d), i) + jitter, d, label=groups[i])
plt.xticks(range(len(groups)), groups)
plt.legend()
plt.show()Gráficos de Barras
Barras Verticais
plt.bar(x, height) desenha barras verticais; x pode ser strings (categórico). O BarContainer retornado permite anotar ou recolorir barras individuais. O loop com plt.text() rotula cada barra — ajuste ha/va ('center'/'bottom') e o deslocamento em y para que os rótulos fiquem logo acima da barra.
import matplotlib.pyplot as plt
categories = ["Apple", "Banana", "Cherry", "Date"]
values = [25, 40, 30, 15]
bars = plt.bar(categories, values, color="tab:blue", edgecolor="black")
# annotate each bar with its value
for bar, v in zip(bars, values):
plt.text(bar.get_x() + bar.get_width()/2, v + 1,
str(v), ha="center", va="bottom")
plt.title("Fruit Sales")
plt.ylabel("units sold")
plt.ylim(0, 50)
plt.show()Barras Horizontais
plt.barh(y, width) desenha barras horizontais — ideal para rótulos de categoria longos que se sobreporiam num gráfico vertical. Chame ax.invert_yaxis() para que o primeiro item apareça no topo, como as pessoas leem listas. A largura padrão é 0.8.
import matplotlib.pyplot as plt
items = ["Reading", "Coding", "Sleep", "Exercise"]
hours = [2, 6, 8, 1]
plt.barh(items, hours, color="tab:green")
plt.xlabel("hours per day")
plt.title("Daily Activities")
# invert so the first item appears at the top
plt.gca().invert_yaxis()
plt.show()Barras Agrupadas
Barras agrupadas colocam duas (ou mais) séries lado a lado deslocando as posições x por metade da largura da barra. O padrão x +/- w/2 com largura w as coloca encostadas. Use np.arange para posições x numéricas para que a matemática funcione, e depois rotule novamente com plt.xticks.
import matplotlib.pyplot as plt
import numpy as np
labels = ["Q1", "Q2", "Q3", "Q4"]
a = [20, 35, 30, 35]
b = [25, 32, 34, 20]
x = np.arange(len(labels))
w = 0.35
plt.bar(x - w/2, a, w, label="2023")
plt.bar(x + w/2, b, w, label="2024")
plt.xticks(x, labels)
plt.ylabel("revenue")
plt.legend()
plt.show()Barras Empilhadas
Barras empilhadas usam o argumento bottom=: cada série começa onde a anterior terminou. Para mais de duas séries, acumule: bottom = [m+w for m, w in zip(men, women)]. Barras empilhadas mostram totais e composição, mas dificultam a comparação das séries superiores entre categorias.
import matplotlib.pyplot as plt
import numpy as np
labels = ["A", "B", "C"]
men = [20, 35, 30]
women = [25, 32, 34]
plt.bar(labels, men, label="Men")
plt.bar(labels, women, bottom=men, label="Women")
plt.legend()
plt.title("Stacked Bars")
plt.show()Barras com Barras de Erro
O argumento yerr adiciona barras de erro verticais; capsize define o comprimento das pontas. Passe error_kw para estilizar as barras. Para erros assimétricos, passe yerr=[erros_inferiores, erros_superiores]. Funciona em barh (xerr) e em plt.errorbar também.
import matplotlib.pyplot as plt
import numpy as np
labels = ["A", "B", "C"]
means = [20, 35, 30]
errors = [2, 4, 3]
plt.bar(labels, means, yerr=errors, capsize=6,
color="tab:orange", edgecolor="black",
error_kw={"ecolor": "black", "linewidth": 1.5})
plt.title("Bar with Error Bars")
plt.ylabel("mean value")
plt.show()Histogramas
Histograma Básico
plt.hist(x) divide os dados em bins e desenha barras. bins pode ser um inteiro (número de bins) ou uma sequência de bordas explícitas. Por padrão, retorna contagens, então o eixo y é a frequência. O valor de retorno é (contagens, bordas_de_bin, patches), que você pode usar para personalizações adicionais.
import matplotlib.pyplot as plt
import numpy as np
rng = np.random.default_rng(0)
data = rng.normal(0, 1, 1000)
plt.hist(data, bins=30)
plt.title("Histogram")
plt.xlabel("value")
plt.ylabel("frequency")
plt.show()Escolhendo os Bins
A escolha dos bins muda drasticamente a aparência de um histograma. 'auto' usa o máximo entre as regras de Sturges e Freedman-Diaconis — um padrão sensato. Passe um array de bordas explícito para controle total e bins comparáveis entre conjuntos de dados. Bins demais escondem estrutura; bins de mais adicionam ruído.
import matplotlib.pyplot as plt
import numpy as np
rng = np.random.default_rng(1)
data = rng.normal(0, 1, 1000)
# auto bin selection (Freedman-Diaconis, Sturges, etc.)
plt.hist(data, bins="auto", alpha=0.5, label="auto")
plt.hist(data, bins=10, alpha=0.5, label="10 bins")
plt.hist(data, bins=np.arange(-4, 4, 0.25),
alpha=0.5, label="0.25 width")
plt.legend()
plt.show()Múltiplos Histogramas
Histogramas sobrepostos precisam de alpha < 1 para mostrar as duas distribuições; use cores distintas. Para mais de dois grupos, stacked=True evita bagunça, mas dificulta a comparação. Considere kdeplot (Seaborn) para curvas de densidade suaves que se sobrepõem mais limpo que histogramas.
import matplotlib.pyplot as plt
import numpy as np
rng = np.random.default_rng(2)
a = rng.normal(0, 1, 1000)
b = rng.normal(1, 1.2, 1000)
plt.hist(a, bins=30, alpha=0.6, label="A", color="tab:blue")
plt.hist(b, bins=30, alpha=0.6, label="B", color="tab:orange")
plt.legend()
plt.show()
# stacked alternative
plt.figure()
plt.hist([a, b], bins=30, stacked=True, label=["A", "B"])
plt.legend()
plt.show()Densidade / Normalizado
density=True divide as contagens por (total * largura_do_bin), de modo que as áreas das barras somem 1, produzindo uma densidade de probabilidade. Isso torna histogramas comparáveis entre tamanhos de amostra diferentes e permite sobrepor uma PDF teórica. Use weights= para ponderar amostras individuais.
import matplotlib.pyplot as plt
import numpy as np
rng = np.random.default_rng(3)
data = rng.normal(0, 1, 1000)
# density=True normalizes the area to 1 (PDF)
plt.hist(data, bins=30, density=True, alpha=0.6)
# overlay the theoretical PDF
from scipy.stats import norm
xs = np.linspace(-4, 4, 200)
plt.plot(xs, norm.pdf(xs), "r-", lw=2)
plt.title("Normalized Histogram + PDF")
plt.show()Histograma 2D
plt.hist2d divide duas variáveis numa grade 2-D e colore cada célula por contagem — o primo discreto da dispersão para dados densos. Para saída mais suave, use plt.hexbin (bins hexagonais). Ambos aceitam um cmap e retornam valores que você pode passar para o colorbar.
import matplotlib.pyplot as plt
import numpy as np
rng = np.random.default_rng(4)
x = rng.normal(0, 1, 10000)
y = x + rng.normal(0, 1, 10000)
plt.hist2d(x, y, bins=40, cmap="Blues")
plt.colorbar(label="count")
plt.title("2D Histogram")
plt.xlabel("x")
plt.ylabel("y")
plt.show()Gráficos de Pizza
Pizza Básica
plt.pie(x, labels) desenha uma pizza a partir dos valores em x. autopct formata os rótulos de porcentagem (uma string estilo printf ou uma função). startangle rotaciona o início da primeira fatia. Sempre plt.axis('equal') para que a pizza seja um círculo de verdade, não uma elipse.
import matplotlib.pyplot as plt
labels = ["Rent", "Food", "Transport", "Fun"]
sizes = [1200, 600, 300, 400]
plt.pie(sizes, labels=labels, autopct="%1.1f%%", startangle=90)
plt.title("Monthly Budget")
plt.axis("equal") # circle, not ellipse
plt.show()Explode e Sombras
explode é uma tupla do mesmo tamanho de sizes; cada valor desloca aquela fatia para fora do centro (0 = sem deslocamento). shadow=True adiciona uma sombra projetada para dar profundidade. Use explode com parcimônia para destacar uma fatia — explodir todas as fatias parece bagunçado.
import matplotlib.pyplot as plt
labels = ["A", "B", "C", "D"]
sizes = [30, 25, 25, 20]
explode = (0, 0.1, 0, 0) # pull the 2nd wedge out
plt.pie(sizes, labels=labels, explode=explode,
shadow=True, autopct="%1.0f%%",
startangle=140)
plt.title("Exploded Pie")
plt.show()Gráfico de Rosca (Donut)
Uma rosca é só uma pizza com furo: defina wedgeprops={'width': 0.4} para desenhar anéis em vez de fatias completas. O furo central pode conter um rótulo resumo via plt.text(0, 0, ...). Roscas geralmente são mais fáceis de ler que pizzas, porque o comprimento do anel codifica o valor melhor que o ângulo da fatia.
import matplotlib.pyplot as plt
labels = ["A", "B", "C"]
sizes = [40, 35, 25]
wedges, texts = plt.pie(sizes, labels=labels,
wedgeprops=dict(width=0.4, edgecolor="w"))
plt.title("Donut Chart")
# add center text
plt.text(0, 0, "Total\n100", ha="center", va="center", fontsize=14)
plt.show()Porcentagem e Ângulo Inicial
autopct pode ser uma função que recebe a porcentagem e retorna uma string, permitindo mostrar percentual e contagem absoluta. startangle + counterclock=False controlam a direção das fatias (começar no topo, ir no sentido horário — a ordem convencional de leitura). pctdistance posiciona os rótulos de porcentagem.
import matplotlib.pyplot as plt
labels = ["North", "South", "East", "West"]
sizes = [32, 24, 28, 16]
colors = ["#4C72B0", "#DD8452", "#55A868", "#C44E52"]
plt.pie(sizes, labels=labels, colors=colors,
autopct=lambda p: f"{p:.1f}%\n({p*sum(sizes)/100:.0f})",
startangle=90, counterclock=False,
pctdistance=0.75)
plt.show()Pizza Aninhada (Concêntrica)
Duas chamadas plt.pie com valores diferentes de radius e width criam anéis concêntricos, um 'sunburst' simples. O anel externo tipicamente mostra categorias de nível superior e o interno seus desdobramentos. Mantenha o raio interno menor e adicione edgecolor='w' para separar visualmente as fatias.
import matplotlib.pyplot as plt
# outer ring: regions, inner ring: sub-categories
outer = [40, 30, 30]
inner = [20, 20, 15, 15, 25, 5]
outer_labels = ["A", "B", "C"]
inner_labels = ["A1", "A2", "B1", "B2", "C1", "C2"]
plt.pie(outer, labels=outer_labels, radius=1.0,
wedgeprops=dict(width=0.3, edgecolor="w"))
plt.pie(inner, labels=inner_labels, radius=0.7,
wedgeprops=dict(width=0.3, edgecolor="w"))
plt.title("Nested Pie")
plt.show()Subplots e Layouts
plt.subplot
plt.subplot(rows, cols, index) seleciona os eixos (indexados a partir de 1) numa grade — a forma legada estilo MATLAB. O índice corre da esquerda para a direita, de cima para baixo. Ele altera os 'eixos atuais', então chamadas plt seguintes desenham ali. Prefira plt.subplots() em código novo; é mais limpo e retorna objetos Axes reais.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 5, 50)
# subplot(nrows, ncols, index) -- 1-indexed!
plt.subplot(2, 2, 1)
plt.plot(x, x)
plt.subplot(2, 2, 2)
plt.plot(x, x**2)
plt.subplot(2, 2, 3)
plt.plot(x, x**3)
plt.subplot(2, 2, 4)
plt.plot(x, np.sin(x))
plt.tight_layout()
plt.show()plt.subplots
plt.subplots(nrows, ncols) retorna (fig, axes), em que axes é um array NumPy de Axes — indexe como axes[row, col]. sharex/sharey alinham os ticks e economizam espaço. fig.suptitle() define um título no nível da figura acima de cada um dos subplots. Sempre plt.tight_layout() para evitar sobreposição de rótulos.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 2*np.pi, 100)
# one figure, 2x2 grid of Axes, shared x and y
fig, axes = plt.subplots(2, 2, figsize=(8, 6),
sharex=True, sharey=True)
axes[0, 0].plot(x, np.sin(x)); axes[0, 0].set_title("sin")
axes[0, 1].plot(x, np.cos(x)); axes[0, 1].set_title("cos")
axes[1, 0].plot(x, np.tan(x)); axes[1, 0].set_title("tan")
axes[1, 1].plot(x, -np.sin(x)); axes[1, 1].set_title("-sin")
fig.suptitle("Trig Family")
plt.tight_layout()
plt.show()GridSpec
GridSpec dá controle total sobre os tamanhos dos subplots — você pode mesclar células com fatiamento (gs[0, :] = linha inteira, gs[1:, 2] = coluna direita alta). Use width_ratios/height_ratios para colunas/linhas de tamanhos desiguais. É a ferramenta padrão para dashboards complexos.
import matplotlib.pyplot as plt
import matplotlib.gridspec as gridspec
fig = plt.figure(figsize=(8, 6))
gs = gridspec.GridSpec(3, 3, figure=fig)
ax1 = fig.add_subplot(gs[0, :]) # full top row
ax2 = fig.add_subplot(gs[1, :2]) # middle, left 2 cols
ax3 = fig.add_subplot(gs[1:, 2]) # right, spans 2 rows
ax4 = fig.add_subplot(gs[2, 0:2]) # bottom-left
ax1.set_title("wide top")
ax3.set_title("tall right")
plt.tight_layout()
plt.show()Compartilhando Eixos
sharex=True (ou sharey=True) vincula eixos, de modo que pan/zoom num atualiza os outros — ótimo para séries temporais empilhadas. Também esconde rótulos de tick redundantes nos eixos internos. Os grupos compartilhados são acessíveis via ax.get_shared_x_axes(); você pode remover um eixo do grupo para desacoplá-lo.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 10, 100)
fig, (ax1, ax2) = plt.subplots(2, 1, sharex=True)
ax1.plot(x, np.sin(x))
ax2.plot(x, np.cos(x))
# zooming on one now zooms both
ax1.set_xlim(0, 5)
# decouple later if needed
# ax2.get_shared_x_axes().remove(ax2)
fig.suptitle("Shared x-axis")
plt.show()Tight Layout e Constrained
tight_layout() ajusta o espaçamento uma vez para evitar sobreposição de rótulos, mas não sabe do fig.suptitle — passe rect para reservar espaço. layout='constrained' (ou fig=Figure(layout='constrained')) é a alternativa moderna que recalcula a cada desenho, trata suptitle e colorbars corretamente e é recomendada para código novo.
import matplotlib.pyplot as plt
# tight_layout: simple, adjusts subplot spacing
fig, axes = plt.subplots(2, 2)
for ax in axes.flat:
ax.set_xlabel("x label")
ax.set_ylabel("y label")
ax.set_title("a title")
fig.suptitle("tight_layout")
plt.tight_layout()
# leave room for suptitle
plt.tight_layout(rect=[0, 0, 1, 0.95])
plt.show()
# constrained_layout: recomputes on every draw (more robust)
fig, axes = plt.subplots(2, 2, layout="constrained")
fig.suptitle("constrained_layout")
plt.show()Legendas e Anotações
Legenda Básica
plt.legend() coleta os labels de cada artista plotado. loc define a posição dentro dos eixos ('upper right', 'lower left', 'best', ...). Para uma legenda externa, combine bbox_to_anchor=(x, y) (coordenadas em fração dos eixos) com loc para ancorar aquele canto da caixa da legenda naquele ponto.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 1, 30)
plt.plot(x, x, label="linear")
plt.plot(x, x**2, label="quadratic")
plt.plot(x, x**3, label="cubic")
plt.legend()
plt.show()
# legend outside the axes
plt.figure()
plt.plot(x, x, label="linear")
plt.plot(x, x**2, label="quadratic")
plt.legend(loc="upper left", bbox_to_anchor=(1, 1))
plt.tight_layout()
plt.show()Posição e Colunas da Legenda
ncol organiza as entradas da legenda em múltiplas colunas — útil quando há muitos rótulos curtos. frameon/framealpha/fancybox controlam a aparência da caixa. title adiciona um cabeçalho. Para um visual sem borda, defina frameon=False; costuma ficar mais limpo em publicações.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 1, 30)
for i in range(1, 6):
plt.plot(x, x**i, label=f"x^{i}")
plt.legend(loc="upper center", ncol=3, fontsize=9,
frameon=True, framealpha=0.9,
title="Powers", title_fontsize=10)
plt.title("Custom Legend")
plt.show()Anotando Pontos
ax.annotate(texto, xy, xytext) posiciona o texto em xytext e (opcionalmente) desenha uma seta até xy. xy está em coordenadas de dados por padrão. arrowprops é um dict de estilo de seta; arrowstyle='->' é o mais comum. annotate é muito mais flexível que plt.text para destaques.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 2*np.pi, 100)
y = np.sin(x)
plt.plot(x, y)
# mark and label the maximum
idx = np.argmax(y)
plt.annotate(f"max = {y[idx]:.2f}",
xy=(x[idx], y[idx]), # point to annotate
xytext=(x[idx]-1, 0.5), # text position
arrowprops=dict(arrowstyle="->"))
plt.show()Anotações com Setas
arrowprops estiliza o conector: arrowstyle ('->', '-|>', '<->'), color, lw. connectionstyle curva a seta — 'arc3,rad=0.3' faz curva, 'angle3' faz um cotovelo reto, 'bar' adiciona uma barra em T. Isso permite construir destaques claros que contornam os dados sem sobrepor curvas.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(-3, 3, 100)
plt.plot(x, x**3 - 3*x)
plt.annotate("local min", xy=(1, -2), xytext=(2, -10),
arrowprops=dict(arrowstyle="->", color="red",
lw=2, connectionstyle="arc3,rad=0.3"))
plt.annotate("local max", xy=(-1, 2), xytext=(-3, 8),
arrowprops=dict(arrowstyle="-|>", color="blue",
connectionstyle="angle3"))
plt.show()Handles Personalizados de Legenda
Quando a legenda padrão (construída dos artistas plotados) não é o que você quer, construa seus próprios handles com Line2D, Patch ou Line2D sem dados e passe handles= para legend(). Isso é essencial para legendas que combinam linhas, patches e marcadores de dispersão numa única chave.
import matplotlib.pyplot as plt
from matplotlib.lines import Line2D
from matplotlib.patches import Patch
plt.plot([1, 2, 3], [1, 4, 9], "o-", color="tab:blue")
plt.plot([1, 2, 3], [1, 8, 27], "s--", color="tab:orange")
custom = [
Line2D([0], [0], color="tab:blue", marker="o", label="squared"),
Line2D([0], [0], color="tab:orange", marker="s", ls="--", label="cubed"),
Patch(facecolor="gray", label="reference band"),
]
plt.legend(handles=custom)
plt.show()Estilos, Cores e rcParams
Estilos Embutidos
plt.style.use(nome) aplica uma aparência predefinida globalmente; plt.style.context(nome) aplica-a temporariamente dentro de um bloco with. Estilos populares: 'ggplot', 'seaborn-v0_8-*', 'bmh', 'fivethirtyeight'. Note que os estilos Seaborn foram renomeados com sufixo '-v0_8' no Matplotlib 3.6+.
import matplotlib.pyplot as plt
# list all available styles
print(plt.style.available)
# use a style globally
plt.style.use("seaborn-v0_8-whitegrid")
# or as a context manager (temporary)
with plt.style.context("dark_background"):
plt.figure()
plt.plot([1, 2, 3], [1, 4, 9])
plt.title("dark")
plt.show()
plt.plot([1, 2, 3], [9, 4, 1])
plt.title("default again")
plt.show()Colormaps
Colormaps caem em três famílias: sequenciais (viridis, plasma) para dados ordenados 0..N, divergentes (coolwarm, RdBu) para dados com ponto médio significativo (use com vmin/vmax centrados em 0), e qualitativos (Set2, tab10) para categorias distintas. Prefira maps perceptualmente uniformes como viridis — são seguros para daltônicos e legíveis na impressão.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 10, 100)
y = np.sin(x)
# sequential, diverging, qualitative
for cmap in ["viridis", "plasma", "coolwarm", "RdBu", "Set2"]:
plt.scatter(x, y, c=x, cmap=cmap, label=cmap)
plt.colorbar(label=cmap)
plt.title(cmap)
plt.show()Ciclo de Cores Personalizado
axes.prop_cycle (um objeto cycler) define a sequência de propriedades alternadas conforme você adiciona linhas. Você pode alternar color, linestyle, marker e mais — combine cycler(color=[...]) + cycler(linestyle=[...]) para avançar ambos simultaneamente. Isso dá a cada gráfico uma paleta consistente e com identidade.
import matplotlib.pyplot as plt
from cycler import cycler
# set the default color cycle for new axes
plt.rcParams["axes.prop_cycle"] = cycler(
color=["#e41a1c", "#377eb8", "#4daf4a", "#984ea3", "#ff7f00"])
for i in range(1, 6):
plt.plot([0, 1, 2], [i]*3, label=f"line {i}", lw=4)
plt.legend()
plt.title("Custom Cycle")
plt.show()rcParams
rcParams é o dicionário mestre de configuração que controla cada padrão — tamanho da figura, DPI, fontes, espessuras de linha, grade, opções de savefig. Defina os valores uma vez no topo do script para saída consistente. plt.rcParams.update({...}) define vários de uma vez. Use mpl.rcParamsFile ou um arquivo matplotlibrc para tornar os padrões permanentes.
import matplotlib.pyplot as plt
import matplotlib as mpl
# read / set individual parameters
mpl.rcParams["figure.figsize"] = (8, 4)
mpl.rcParams["figure.dpi"] = 100
mpl.rcParams["font.size"] = 12
mpl.rcParams["axes.grid"] = True
mpl.rcParams["axes.grid.which"] = "both"
mpl.rcParams["savefig.bbox"] = "tight"
# update many at once
plt.rcParams.update({
"axes.titlesize": "large",
"axes.labelsize": "medium",
"lines.linewidth": 2,
})
plt.plot([1, 2, 3])
plt.title("Configured Defaults")
plt.show()Formatos de Cor
matplotlib.colors fornece conversão (to_hex, to_rgb), listas de cores nomeadas e construção de colormaps. LinearSegmentedColormap.from_list constrói um colormap contínuo a partir de poucas cores de ancoragem. Para maps categóricos personalizados, use ListedColormap(['#aaa', '#bbb', ...]). Isso permite casar exatamente paletas de marca.
import matplotlib.pyplot as plt
import matplotlib.colors as mcolors
# all named colors
print(list(mcolors.CSS4_COLORS)[:5])
# convert between formats
print(mcolors.to_hex((0.1, 0.2, 0.5))) # #1a3380
print(mcolors.to_rgb("#ff8800")) # (1.0, 0.533, 0.0)
# make a custom colormap from a list of colors
cmap = mcolors.LinearSegmentedColormap.from_list(
"rg", ["red", "yellow", "green"])
import numpy as np
plt.imshow(np.linspace(0, 1, 256).reshape(1, -1),
cmap=cmap, aspect="auto")
plt.title("Custom Colormap")
plt.show()Configurações de Eixo
Limites (xlim / ylim)
plt.xlim/plt.ylim (ou ax.set_xlim/ax.set_ylim) definem o intervalo visível de dados. Passar None deixa um limite em autoescala, ex.: set_ylim(None, 5) fixa apenas o topo. plt.margins() adiciona preenchimento como fração do intervalo de dados, em vez de limites rígidos.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 10, 100)
plt.plot(x, np.sin(x))
# set explicit limits
plt.xlim(2, 8)
plt.ylim(-1.5, 1.5)
# or autoscale with margin
# plt.margins(x=0.05, y=0.1)
# query current limits
print(plt.xlim()) # (2.0, 8.0)
plt.show()Ticks
plt.xticks(posições) define onde os ticks aparecem; plt.xticks(posições, rótulos) também define seu texto. Passe uma lista vazia para esconder os ticks por completo. Em eixos numéricos, geralmente você deixa o MaxNLocator escolher os ticks automaticamente e só sobrescreve em eixos categóricos ou simbólicos (como múltiplos de pi).
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 2*np.pi, 100)
plt.plot(x, np.sin(x))
# set tick positions
plt.xticks([0, np.pi/2, np.pi, 3*np.pi/2, 2*np.pi])
# set positions AND labels
plt.xticks([0, np.pi/2, np.pi, 3*np.pi/2, 2*np.pi],
["0", "pi/2", "pi", "3pi/2", "2pi"])
# turn off ticks
# plt.xticks([])
plt.show()Formatação de Ticks
O módulo ticker dá controle preciso: Locators decidem ONDE os ticks vão (MultipleLocator a cada N unidades, MaxNLocator até N ticks, LogLocator para eixos log); Formatters decidem o TEXTO do rótulo (FormatStrFormatter estilo printf, FuncFormatter função arbitrária). Use locators minor para grades finas.
import matplotlib.pyplot as plt
import numpy as np
from matplotlib.ticker import MultipleLocator, FormatStrFormatter, FuncFormatter
x = np.linspace(0, 5, 100)
plt.plot(x, x**2)
ax = plt.gca()
ax.xaxis.set_major_locator(MultipleLocator(1))
ax.xaxis.set_minor_locator(MultipleLocator(0.25))
ax.yaxis.set_major_formatter(FormatStrFormatter("%.0f"))
# format with a function
ax.yaxis.set_major_formatter(
FuncFormatter(lambda v, p: f"{v/1000:.1f}k"))
plt.show()Escala Logarítmica
plt.xscale('log') / plt.yscale('log') trocam um eixo para logarítmico — essencial para dados que atravessam ordens de magnitude. 'symlog' é uma escala log com região linear perto do zero, permitindo exibir valores negativos. Use plt.grid(True, which='both') para mostrar grades major e minor (espaçadas log).
import matplotlib.pyplot as plt
import numpy as np
x = np.logspace(0, 4, 50) # 10^0 .. 10^4
plt.plot(x, x**2)
# log both axes
plt.xscale("log")
plt.yscale("log")
# symlog: log scale that handles negative/zero values
# plt.yscale("symlog", linthresh=1)
plt.title("Log-Log Plot")
plt.grid(True, which="both", ls="--", alpha=0.5)
plt.show()Proporção e Spines
ax.set_aspect('equal') garante escala igual para que círculos fiquem circulares — crítico para geometria e mapas. Spines são as linhas de borda dos eixos; esconder topo/direita ('despining') dá um visual moderno mais limpo, popularizado pelo Seaborn. Você também pode mover spines para posições arbitrárias de dados para construir eixos em cruz.
import matplotlib.pyplot as plt
import numpy as np
fig, ax = plt.subplots()
theta = np.linspace(0, 2*np.pi, 100)
ax.plot(np.cos(theta), np.sin(theta))
# equal data units on x and y (a true circle)
ax.set_aspect("equal")
# hide the top and right spines
ax.spines["top"].set_visible(False)
ax.spines["right"].set_visible(False)
# move the remaining spines to the center for a cross-hair
# ax.spines["left"].set_position(("data", 0))
# ax.spines["bottom"].set_position(("data", 0))
plt.show()Texto e Expressões Matemáticas
Texto nos Eixos
ax.text(x, y, s) posiciona texto em coordenadas de dados por padrão. Passe transform=ax.transAxes para usar coordenadas em fração dos eixos (0,0 = canto inferior esquerdo, 1,1 = superior direito), que é como se fixam rótulos num canto independentemente do intervalo dos dados. ha/va controlam o alinhamento horizontal/vertical.
import matplotlib.pyplot as plt
plt.plot([0, 1], [0, 1])
# ax.text(x, y, s) -- x, y in data coords
plt.text(0.5, 0.5, "center of plot", ha="center", va="center",
fontsize=14, color="red", rotation=30)
# align to axes fraction instead of data coords
plt.text(0.02, 0.98, "top-left", transform=plt.gca().transAxes,
ha="left", va="top", bbox=dict(boxstyle="round", fc="yellow"))
plt.show()suptitle e figtext
fig.suptitle() adiciona um título abrangendo a figura inteira (acima de cada um dos subplots); reserve espaço com tight_layout(rect=[...]) ou use layout='constrained'. fig.text(x, y, s) posiciona texto em coordenadas de fração da figura (0,0 = canto inferior esquerdo da figura), útil para rodapés e notas de fonte.
import matplotlib.pyplot as plt
fig, axes = plt.subplots(1, 2)
axes[0].plot([1, 2, 3])
axes[1].plot([3, 2, 1])
# figure-level title (above all axes)
fig.suptitle("Main Title", fontsize=16, fontweight="bold")
# arbitrary figure-coordinate text
fig.text(0.5, 0.01, "figure footer text", ha="center", fontsize=9)
plt.tight_layout(rect=[0, 0.03, 1, 0.95])
plt.show()Matemática LaTeX (mathtext)
O Matplotlib tem um motor mathtext embutido: envolva matemática parecida com LaTeX em cifrões ($...$) e use raw strings (r"..."). Comandos comuns funcionam: \frac, \sum, \int, letras gregas \alpha..\omega, sobrescritos x^2, subscritos x_i. Não é preciso instalar LaTeX externo. Use r-strings para que as barras invertidas sobrevivam no Python.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 2*np.pi, 100)
plt.plot(x, np.sin(x))
# mathtext: enclose LaTeX in dollar signs
plt.title(r"$\sin(x)$ vs $x$")
plt.xlabel(r"$x$ (radians)")
plt.ylabel(r"$\sin(x)$")
# fractions, sums, greek letters
plt.text(2, 0.5, r"$\frac{a}{b} + \sum_{i=1}^{n} x_i^2$")
plt.text(2, -0.5, r"$\alpha, \beta, \gamma, \pi, \infty$")
plt.show()Propriedades de Texto
Cada objeto de texto aceita um conjunto rico de propriedades: fontsize, fontweight ('bold'), fontstyle ('italic'), family ('serif'/'sans-serif'/'monospace'), color e um dict bbox para caixa de fundo. Os objetos de texto são retornados, então você pode alterá-los depois (útil em animações e atualizações interativas).
import matplotlib.pyplot as plt
t = plt.text(0.5, 0.5, "Styled Text",
fontsize=18, fontweight="bold",
fontstyle="italic", family="serif",
color="darkblue",
bbox=dict(boxstyle="round,pad=0.5",
facecolor="lightyellow", edgecolor="black"))
# animate or update properties later
t.set_fontsize(24)
t.set_color("crimson")
plt.show()Anotações (textcoords)
textcoords do annotate controla como xytext é interpretado: 'data' (padrão, unidades de dados), 'offset points' (pontos relativos a xy — ótimo para afastar rótulos de um ponto), 'axes fraction' (0-1 pelos eixos) ou 'figure fraction'. Misturar sistemas de coordenadas mantém os destaques legíveis conforme você dá zoom.
import matplotlib.pyplot as plt
plt.plot([1, 2, 3, 4], [1, 4, 2, 3])
# xy in data coords, xytext in points OFFSET from xy
plt.annotate("offset text", xy=(2, 4),
xytext=(15, 15), textcoords="offset points",
arrowprops=dict(arrowstyle="->"))
# xytext in axes fraction
plt.annotate("axes corner", xy=(2, 4),
xytext=(0.8, 0.8), textcoords="axes fraction",
arrowprops=dict(arrowstyle="-|>"))
plt.show()Salvando Figuras
Básico de savefig
plt.savefig(caminho) escreve a figura atual num arquivo. Crucialmente, chame-o ANTES de plt.show() — show() finaliza e pode fechar/esvaziar a figura, então salvar depois gera um arquivo em branco. A extensão do arquivo determina o formato automaticamente (.png, .pdf, .svg, .jpg).
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [4, 5, 2])
# save BEFORE plt.show() -- show() clears the figure
plt.savefig("plot.png")
plt.savefig("plot.pdf")
plt.show()Formatos
Escolha o formato pelo propósito: PNG para tela/web, PDF ou SVG (vetorial) para impressão e edição, porque escalam sem pixelização; JPG apenas para imagens fotográficas (perde nitidez em linhas e texto). Formatos vetoriais também geram arquivos bem menores para gráficos com poucos elementos. Passe format= para sobrescrever a extensão.
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [1, 4, 9])
# raster formats (pixels)
plt.savefig("plot.png") # lossless, default
plt.savefig("plot.jpg", quality=95)
plt.savefig("plot.tiff", dpi=200)
# vector formats (scale without pixelation)
plt.savefig("plot.pdf") # best for publications
plt.savefig("plot.svg") # editable in Inkscape/Illustrator
# explicit format override
plt.savefig("plot.dat", format="png")DPI e Resolução
DPI (pontos por polegada) define a resolução da saída raster: dimensões em pixels = figsize * dpi. 72-100 DPI bastam para telas; 300+ DPI são exigidos para impressão. Salve em formato vetorial (PDF/SVG) para evitar problemas de resolução por completo. Defina savefig.dpi no rcParams para saída de alta resolução consistente no script.
import matplotlib.pyplot as plt
fig, ax = plt.subplots(figsize=(6, 4))
ax.plot([1, 2, 3], [1, 4, 9])
# dpi controls pixel density: width_px = figsize[0] * dpi
plt.savefig("low.png", dpi=72) # 432 x 288 px
plt.savefig("high.png", dpi=300) # 1800 x 1200 px
# set a global default DPI
plt.rcParams["savefig.dpi"] = 300
plt.savefig("global.png")bbox_inches e Pad
Por padrão o savefig recorta no retângulo da figura, o que pode cortar rótulos e títulos perto da borda. bbox_inches='tight' expande a região salva para incluir cada um dos artistas, e pad_inches adiciona uma pequena margem em volta. Isso é quase sempre o que você quer — defina como padrão via rcParams['savefig.bbox']='tight'.
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [1, 4, 9])
plt.title("With Long Title That Might Be Cut Off")
# tight bbox trims whitespace and keeps labels inside
plt.savefig("tight.png", bbox_inches="tight", pad_inches=0.1)
# trim even more aggressively
plt.savefig("tighter.png", bbox_inches="tight", pad_inches=0)
# preview the tight bounding box
# bbox = plt.savefig("x.png", bbox_inches="tight") # returns a BboxTransparente e Facecolor
transparent=True torna o fundo da figura translúcido (canal alfa do PNG) — ideal para sobrepor gráficos em slides ou páginas web. facecolor define a cor do fundo salvo (sobrescreve a cor na tela). O fundo dos eixos é controlado separadamente por ax.set_facecolor(). Combine ambos para designs em camadas.
import matplotlib.pyplot as plt
fig, ax = plt.subplots()
ax.plot([1, 2, 3], [1, 4, 9])
ax.set_facecolor("#f0f0f0")
# transparent background (alpha channel)
plt.savefig("transparent.png", transparent=True)
# explicit figure face color
plt.savefig("colored.png", facecolor="lightblue", edgecolor="none")
# control which elements are saved
plt.savefig("full.png", facecolor=fig.get_facecolor())Gráficos 3D (mplot3d)
Configurando Eixos 3D
Crie eixos 3D com projection='3d' (via add_subplot ou subplot_kw em subplots). Todas as funções 2-D funcionam, mais os específicos de z (set_zlabel, plot_surface, scatter, etc.). O suporte 3D vem do toolkit mplot3d, que acompanha o Matplotlib e não precisa de instalação extra.
import matplotlib.pyplot as plt
import numpy as np
fig = plt.figure()
# add a 3D axes via projection
ax = fig.add_subplot(projection="3d")
# or from subplots
# fig, ax = plt.subplots(subplot_kw={"projection": "3d"})
ax.set_xlabel("X")
ax.set_ylabel("Y")
ax.set_zlabel("Z")
ax.set_title("3D Axes")
plt.show()Dispersão 3D
ax.scatter(x, y, z) em eixos 3D plota pontos no espaço; os argumentos s e c funcionam como no scatter 2-D. Adicione fig.colorbar(sc) para mostrar o mapeamento de cores. Dispersão 3D é ótima para explorar clusters, mas esteja ciente de que gráficos 3D estáticos podem esconder profundidade — rotacione interativamente ou use cor para codificar uma dimensão.
import matplotlib.pyplot as plt
import numpy as np
rng = np.random.default_rng(0)
n = 200
x = rng.normal(0, 1, n)
y = rng.normal(0, 1, n)
z = rng.normal(0, 1, n)
c = np.sqrt(x**2 + y**2 + z**2)
fig = plt.figure()
ax = fig.add_subplot(projection="3d")
sc = ax.scatter(x, y, z, c=c, cmap="viridis")
fig.colorbar(sc, label="distance from origin")
ax.set_title("3D Scatter")
plt.show()Superfície 3D
plot_surface(X, Y, Z) desenha uma superfície colorida; X, Y, Z devem ser arrays 2-D de formas compatíveis, produzidos por np.meshgrid. rstride/cstride controlam quantos pontos da grade são pulados (menor = mais suave, mais lento). cmap colore por Z; adicione um colorbar (com shrink para caber numa figura 3D).
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(-5, 5, 80)
y = np.linspace(-5, 5, 80)
X, Y = np.meshgrid(x, y)
R = np.sqrt(X**2 + Y**2)
Z = np.sin(R)
fig = plt.figure()
ax = fig.add_subplot(projection="3d")
surf = ax.plot_surface(X, Y, Z, cmap="coolwarm",
rstride=1, cstride=1,
linewidth=0, antialiased=True)
fig.colorbar(surf, shrink=0.5, aspect=10)
ax.set_title("3D Surface")
plt.show()Wireframe e Contorno 3D
plot_wireframe desenha só as linhas da grade (mais leve que uma superfície completa, bom para mostrar estrutura). ax.contourf com zdir='z' e offset projeta contornos preenchidos num plano sob a superfície — uma visualização '2D sob 3D' comum. Combine superfície + contornos projetados para gráficos de terreno ricos.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(-3, 3, 30)
y = np.linspace(-3, 3, 30)
X, Y = np.meshgrid(x, y)
Z = X * np.exp(-X**2 - Y**2)
fig = plt.figure()
ax = fig.add_subplot(projection="3d")
ax.plot_wireframe(X, Y, Z, color="black", rstride=1, cstride=1)
ax.set_title("Wireframe")
# 3D contour (filled) projected at the bottom
fig = plt.figure()
ax = fig.add_subplot(projection="3d")
ax.contourf(X, Y, Z, zdir="z", offset=-0.5, cmap="viridis")
ax.set_title("3D Contour")
plt.show()Barras 3D
ax.bar3d(x, y, z, dx, dy, dz) desenha barras retangulares nas posições (x, y), partindo da base z, com larguras dx, dy e altura dz. shade=True adiciona iluminação para dar sensação 3D. Achate os arrays de coordenadas com .ravel() ao partir de um meshgrid. Barras 3D podem ser difíceis de ler — prefira barras 2D agrupadas quando possível.
import matplotlib.pyplot as plt
import numpy as np
fig = plt.figure()
ax = fig.add_subplot(projection="3d")
x = np.arange(3)
y = np.arange(3)
X, Y = np.meshgrid(x, y)
X, Y = X.ravel(), Y.ravel()
Z = np.zeros_like(X)
dz = np.array([1, 2, 3, 2, 3, 1, 3, 1, 2])
ax.bar3d(X, Y, Z, dx=0.6, dy=0.6, dz=dz,
shade=True, color="tab:orange")
ax.set_title("3D Bar Chart")
plt.show()Gráficos de Contorno
Linhas de Contorno
plt.contour(X, Y, Z) desenha isolinhas onde Z é constante. X, Y vêm de meshgrid. levels define o número (ou valores exatos) de contornos. plt.clabel(cs) rotula cada linha com seu valor. Contornos de linha são precisos, mas esparsos; combine com contourf para regiões preenchidas.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(-3, 3, 100)
y = np.linspace(-3, 3, 100)
X, Y = np.meshgrid(x, y)
Z = np.sin(X) * np.cos(Y)
# line contours
cs = plt.contour(X, Y, Z, levels=15, colors="black", linewidths=0.8)
plt.clabel(cs, inline=True, fontsize=8)
plt.title("Contour Lines")
plt.colorbar(cs)
plt.show()Contornos Preenchidos
plt.contourf (note o 'f') preenche com cor as regiões entre níveis de contorno, dando um visual suave de mapa de calor. Como o contour, precisa de X, Y, Z em grade. levels controla a resolução. contourf é a forma padrão de visualizar campos escalares 2-D como temperatura, elevação ou densidade de probabilidade.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(-2, 2, 100)
y = np.linspace(-2, 2, 100)
X, Y = np.meshgrid(x, y)
Z = X**2 + Y**2
cf = plt.contourf(X, Y, Z, levels=20, cmap="viridis")
plt.colorbar(cf, label="Z")
plt.title("Filled Contour")
plt.xlabel("X")
plt.ylabel("Y")
plt.show()Rotulando Contornos (clabel)
plt.clabel(cs) anota as linhas de contorno com seu valor de Z; inline=True quebra a linha para caber o rótulo. fmt formata o número ('%.2f' ou uma função). Passe levels=[...] para rotular apenas isolinhas específicas. Contornos rotulados transmitem valores exatos sem precisar de barra de cores.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(-3, 3, 100)
y = np.linspace(-3, 3, 100)
X, Y = np.meshgrid(x, y)
Z = X * np.exp(-X**2 - Y**2)
cs = plt.contour(X, Y, Z, 10, colors="black")
plt.clabel(cs, inline=True, fontsize=9, fmt="%.2f")
# label only specific levels
# plt.clabel(cs, levels=[-0.1, 0, 0.1])
plt.title("Labeled Contours")
plt.show()Barra de Cores (Colorbar)
plt.colorbar(mappable) adiciona uma chave de cores — sempre passe o retorno do contour/imshow/scatter para que ela conheça o mapeamento. set_label/set_ticks personalizam-na. Em subplots, colorbars podem roubar espaço de um eixo; use o argumento ax= ou fig.colorbar(mappable, ax=axes) para controlar o posicionamento entre vários eixos.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 5, 100)
y = np.linspace(0, 5, 100)
X, Y = np.meshgrid(x, y)
Z = np.sin(X) + np.cos(Y)
cf = plt.contourf(X, Y, Z, cmap="RdBu")
# basic colorbar
cb = plt.colorbar(cf)
cb.set_label("Z value")
cb.set_ticks([-2, -1, 0, 1, 2])
# place colorbar with specific size and padding
# cb = plt.colorbar(cf, fraction=0.046, pad=0.04)
plt.title("Colorbar Example")
plt.show()meshgrid e griddata
Contour/contourf precisam de dados numa grade regular. Para amostras esparsas, use scipy.interpolate.griddata para interpolar num meshgrid (opções: 'linear', 'nearest', 'cubic'). np.mgrid[...] é uma abreviação prática de meshgrid sobre um intervalo. Plotar os pontos originais por cima mostra onde os dados são esparsos.
import matplotlib.pyplot as plt
import numpy as np
from scipy.interpolate import griddata
# scattered (x, y, z) samples
rng = np.random.default_rng(0)
pts = rng.uniform(-2, 2, (200, 2))
z = np.sin(pts[:,0]) * np.cos(pts[:,1])
# build a regular grid
grid_x, grid_y = np.mgrid[-2:2:100j, -2:2:100j]
# interpolate scattered data onto the grid
grid_z = griddata(pts, z, (grid_x, grid_y), method="cubic")
plt.contourf(grid_x, grid_y, grid_z, levels=20, cmap="plasma")
plt.scatter(pts[:,0], pts[:,1], c="white", s=5, alpha=0.5)
plt.colorbar(label="z")
plt.title("Scattered -> Grid -> Contour")
plt.show()Exibição de Imagens (imshow)
Básico de imshow
plt.imshow(arr) exibe um array 2-D como mapa de calor ou um array 3-D (H, W, 3) como imagem RGB. Por padrão, a origem é o canto superior esquerdo (origin='upper'), seguindo a convenção de imagens — defina origin='lower' para eixos estilo matemática. plt.axis('off') esconde os ticks para uma exibição limpa.
import matplotlib.pyplot as plt
import numpy as np
# a 2D array is shown as a heatmap (color = value)
rng = np.random.default_rng(0)
img = rng.random((10, 10))
plt.imshow(img, cmap="viridis")
plt.colorbar(label="value")
plt.title("imshow of a 2D array")
plt.show()
# a 3D array (H, W, 3 or 4) is shown as an RGB(A) image
rgb = rng.integers(0, 256, (50, 50, 3), dtype=np.uint8)
plt.imshow(rgb)
plt.axis("off")
plt.title("RGB image")
plt.show()Colormap e Colorbar
extent=[xmin, xmax, ymin, ymax] mapeia os pixels do array para coordenadas de dados; sem ele, o imshow usa índices de pixel. origin='lower' coloca a linha 0 embaixo (convenção matemática). aspect='auto' estica a imagem para preencher os eixos; o padrão 'equal' preserva pixels quadrados. Passe o objeto imagem para o colorbar.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(-3, 3, 200)
y = np.linspace(-3, 3, 200)
X, Y = np.meshgrid(x, y)
Z = np.sin(X**2 + Y**2) / (X**2 + Y**2 + 1)
im = plt.imshow(Z, extent=[-3, 3, -3, 3], origin="lower",
cmap="RdBu", aspect="auto")
cb = plt.colorbar(im)
cb.set_label("intensity")
plt.title("imshow with extent")
plt.show()Interpolação
interpolation controla como os pixels se misturam ao ampliar: 'none'/'nearest' mostra blocos nítidos (bom para dados brutos de pixel), 'bilinear'/'bicubic' suaviza entre pixels (bom para mapas de calor). A interpolação muda só a aparência, não os dados. Em arrays pequenos, você geralmente QUER 'nearest' para que cada célula fique visível.
import matplotlib.pyplot as plt
import numpy as np
rng = np.random.default_rng(1)
small = rng.random((5, 5))
methods = ["none", "bilinear", "bicubic", "nearest"]
fig, axes = plt.subplots(1, 4, figsize=(12, 3))
for ax, m in zip(axes, methods):
ax.imshow(small, interpolation=m, cmap="magma")
ax.set_title(m)
ax.axis("off")
plt.tight_layout()
plt.show()vmin / vmax e norm
vmin/vmax fixam o intervalo de dados mapeado no colormap (corta outliers). Para mapeamentos não lineares, use norm=: LogNorm para dados que atravessam ordens de magnitude, TwoSlopeNorm para centralizar um map divergente num ponto médio significativo (ex.: 0 para anomalias). norm e vmin/vmax são mutuamente exclusivos — passe apenas um.
import matplotlib.pyplot as plt
import numpy as np
from matplotlib.colors import LogNorm, TwoSlopeNorm
rng = np.random.default_rng(2)
Z = rng.random((50, 50)) * 1000 + 1
# clamp the colormap range
plt.imshow(Z, vmin=100, vmax=500, cmap="viridis")
plt.colorbar()
plt.title("clipped range")
plt.show()
# log-scaled colors
plt.imshow(Z, norm=LogNorm(vmin=1, vmax=1001), cmap="plasma")
plt.colorbar()
plt.title("log scale")
plt.show()
# diverging norm centered on a midpoint
# norm = TwoSlopeNorm(vmin=-1, vcenter=0, vmax=1)Exibindo Imagem de Arquivo
mpimg.imread carrega uma imagem num array NumPy (float 0-1 para PNG, 0-255 uint8 para JPEG). plt.imshow exibe; plt.imsave escreve um array de volta no disco. Imagens RGB mantêm as cores; passe cmap='gray' para imagens de um canal. Note que PIL/pillow é mais capaz para processamento de imagem não trivial.
import matplotlib.pyplot as plt
import matplotlib.image as mpimg
# read an image file into a numpy array
img = mpimg.imread("photo.png") # shape (H, W, 3) or (H, W, 4)
print(img.shape, img.dtype)
plt.imshow(img)
plt.axis("off")
plt.show()
# save the (possibly modified) array back to a file
# plt.imsave("out.png", img)
# drop the alpha channel if present
if img.shape[-1] == 4:
img = img[..., :3]Gráficos Polares
Eixos Polares
projection='polar' transforma os eixos em coordenadas polares: x é o ângulo (theta, em radianos) e y é o raio (r). Todas as funções padrão funcionam, mas operam em (theta, r). Gráficos polares são ideais para dados direcionais, funções periódicas e simetrias circulares. Defina ticks com ax.set_thetagrids e ax.set_rgrids.
import matplotlib.pyplot as plt
import numpy as np
# create a polar axes via projection
fig = plt.figure()
ax = fig.add_subplot(projection="polar")
# or from subplots
# fig, ax = plt.subplots(subplot_kw={"projection": "polar"})
theta = np.linspace(0, 2*np.pi, 100)
ax.plot(theta, np.sin(2*theta))
plt.show()Linha Polar
Num eixo polar, plot(theta, r) desenha curvas em que theta é o ângulo e r o raio. set_rmax corta o intervalo radial; set_rticks e set_thetagrids personalizam as posições dos ticks radial/angular. Gráficos de linha polares mostram funções periódicas com clareza — uma senoide fecha num loop.
import matplotlib.pyplot as plt
import numpy as np
theta = np.linspace(0, 2*np.pi, 200)
fig, ax = plt.subplots(subplot_kw={"projection": "polar"})
ax.plot(theta, 1 + np.cos(theta), label="cardioid")
ax.plot(theta, np.abs(np.sin(2*theta)), label="rose")
ax.set_rmax(2.0)
ax.set_rticks([0.5, 1.0, 1.5])
ax.set_thetagrids([0, 90, 180, 270])
ax.legend(loc="upper right")
plt.show()Radar / Gráfico de Teia
Um gráfico de radar é um gráfico de linha polar com um eixo por categoria. O truque é anexar o primeiro valor/ângulo ao fim para que a curva feche num loop, e preencher o interior com alpha. Defina xticks nos ângulos das categorias e rotule-os. Radares comparam perfis multivariados, mas podem induzir a erro — use com parcimônia.
import matplotlib.pyplot as plt
import numpy as np
labels = ["Speed", "Power", "Range", "Comfort", "Price"]
values = [8, 7, 6, 5, 9]
N = len(labels)
# close the loop
angles = np.linspace(0, 2*np.pi, N, endpoint=False).tolist()
values += values[:1]
angles += angles[:1]
fig, ax = plt.subplots(subplot_kw={"projection": "polar"})
ax.plot(angles, values, "o-")
ax.fill(angles, values, alpha=0.25)
ax.set_xticks(angles[:-1])
ax.set_xticklabels(labels)
ax.set_title("Radar Chart")
plt.show()Barras Polares (Rosa)
Um gráfico rosa (ou barra polar) usa ax.bar num eixo polar — cada barra ocupa um setor angular. Útil para histogramas direcionais como direção do vento ou distribuições de período de ondas. Pinte as barras por raio (como mostrado) para uma dimensão extra. bottom= pode empilhar ou afastar as barras do centro.
import matplotlib.pyplot as plt
import numpy as np
rng = np.random.default_rng(0)
N = 12
theta = np.linspace(0, 2*np.pi, N, endpoint=False)
widths = 2*np.pi / N
radii = rng.uniform(1, 5, N)
fig, ax = plt.subplots(subplot_kw={"projection": "polar"})
bars = ax.bar(theta, radii, width=widths, bottom=0,
edgecolor="black")
# color bars by radius
for r, bar in zip(radii, bars):
bar.set_facecolor(plt.cm.viridis(r / radii.max()))
ax.set_title("Rose Diagram")
plt.show()Configurações Polares
set_theta_zero_location('N') move 0 radianos para o topo e set_theta_direction(-1) faz os ângulos crescerem no sentido horário — a convenção de bússola. set_rlabel_position(ângulo) reposiciona os rótulos dos ticks radiais em qualquer ângulo para evitar sobreposição com os dados. Esses ajustes convertem um gráfico polar matemático num gráfico direcional/bússola.
import matplotlib.pyplot as plt
import numpy as np
fig, ax = plt.subplots(subplot_kw={"projection": "polar"})
ax.plot(np.linspace(0, 2*np.pi, 100), np.linspace(0, 1, 100))
# rotate 0 degrees to the top, go clockwise
ax.set_theta_zero_location("N")
ax.set_theta_direction(-1)
# radial limits and ticks
ax.set_rlim(0, 1.2)
ax.set_rticks([0.25, 0.5, 0.75, 1.0])
ax.set_rlabel_position(135) # move radial labels out of the way
# label directions in degrees
ax.set_thetagrids([0, 90, 180, 270], labels=["E","N","W","S"])
plt.show()Eixos Gêmeos (Twin)
twinx (Y Secundário)
ax.twinx() cria novos eixos que compartilham o eixo x mas têm eixo y próprio à direita — a forma padrão de plotar duas grandezas com unidades diferentes (ex.: temperatura e umidade). Pinte cada eixo e seus ticks para casar com a curva, para que o leitor saiba qual escala pertence a qual série.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 10, 100)
fig, ax1 = plt.subplots()
ax1.plot(x, np.sin(x), "b-")
ax1.set_xlabel("x")
ax1.set_ylabel("sin(x)", color="b")
ax1.tick_params(axis="y", labelcolor="b")
# a second axes sharing the same x, with an independent y
ax2 = ax1.twinx()
ax2.plot(x, x*10, "r-")
ax2.set_ylabel("10*x", color="r")
ax2.tick_params(axis="y", labelcolor="r")
plt.title("twinx: two y-scales")
plt.show()twiny (X Secundário)
ax.twiny() é o equivalente horizontal: novos eixos que compartilham o eixo y mas têm eixo x próprio no topo. Use-o para mostrar os mesmos dados em duas escalas x (ex.: metros e pés, ou tempo em segundos e minutos). A mesma dica de cores vale — combine a cor do eixo com sua curva.
import matplotlib.pyplot as plt
import numpy as np
y = np.linspace(0, 10, 50)
fig, ax1 = plt.subplots()
ax1.plot(np.exp(y), y, "g-")
ax1.set_ylabel("y")
ax1.set_xlabel("exp(y)", color="g")
# second axes sharing y, independent x on top
ax2 = ax1.twiny()
ax2.plot(y**2, y, "m-")
ax2.set_xlabel("y^2", color="m")
plt.title("twiny: two x-scales")
plt.show()Gráfico Gêmeo Combinado
Ao gemelar eixos, cada eixo tem sua própria legenda. Para mostrar uma legenda combinada única, colete os handles de linha dos dois eixos numa lista e chame ax1.legend(lines, labels). Esta é a forma idiomática de manter uma chave única num gráfico de eixo duplo, para que o leitor identifique as duas séries de uma vez.
import matplotlib.pyplot as plt
import numpy as np
t = np.linspace(0, 5, 100)
temp_c = 20 + 5*np.sin(t) # Celsius
humidity = 60 - 5*t # percent
fig, ax1 = plt.subplots(figsize=(8, 4))
l1, = ax1.plot(t, temp_c, "r-o", label="Temperature (C)")
ax1.set_xlabel("time (s)")
ax1.set_ylabel("Temperature (C)", color="r")
ax1.tick_params(axis="y", labelcolor="r")
ax2 = ax1.twinx()
l2, = ax2.plot(t, humidity, "b-s", label="Humidity (%)")
ax2.set_ylabel("Humidity (%)", color="b")
ax2.tick_params(axis="y", labelcolor="b")
# combine legends from both axes
lines = [l1, l2]
ax1.legend(lines, [l.get_label() for l in lines], loc="upper right")
plt.title("Temperature & Humidity")
plt.show()Despine em Eixos Gêmeos
Eixos gêmeos naturalmente produzem uma borda superior duplicada. Esconda as spines superiores em ambos os eixos para um visual mais limpo, e pinte as spines esquerda/direita para casar com o respectivo eixo y. Combinado com rótulos de tick coloridos, isso sinaliza claramente qual escala pertence a qual curva, sem poluir o gráfico.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 10, 100)
fig, ax1 = plt.subplots()
ax2 = ax1.twinx()
ax1.plot(x, np.sin(x), color="tab:blue")
ax2.plot(x, np.cos(x), color="tab:orange")
# remove the top spine so the two axes don't double-border
ax1.spines["top"].set_visible(False)
ax2.spines["top"].set_visible(False)
# color the spines to match their axes
ax1.spines["left"].set_color("tab:blue")
ax2.spines["right"].set_color("tab:orange")
plt.title("Clean Twin Axes")
plt.show()Gêmeos com Unidades Diferentes
Às vezes você não precisa de uma segunda série plotada — só quer um segundo eixo com unidades convertidas (km/milhas, C/F). Crie twiny(), alinhe os limites com set_xlim e defina manualmente xticks/xticklabels com os valores convertidos. Isso anota uma única série de dados com dois sistemas de unidades.
import matplotlib.pyplot as plt
import numpy as np
km = np.linspace(0, 100, 50)
mile = km * 0.621371
fig, ax1 = plt.subplots()
ax1.plot(km, np.sin(km/10), "tab:purple")
ax1.set_xlabel("distance")
ax1.set_ylabel("signal", color="tab:purple")
ax2 = ax1.twiny()
ax2.set_xlim(ax1.get_xlim()) # align x limits
# relabel the top ticks in miles
new_ticks = np.array([0, 25, 50, 75, 100])
ax2.set_xticks(new_ticks)
ax2.set_xticklabels([f"{m:.0f}" for m in new_ticks*0.621371])
ax2.set_xlabel("miles")
plt.show()Barras de Erro e Áreas Preenchidas
errorbar
plt.errorbar(x, y, yerr) plota pontos com barras de erro verticais — o padrão para dados experimentais com incerteza. fmt é uma string de formato de plot ('o-' = marcadores + linha). ecolor, elinewidth e capsize estilizam as barras de erro. Use xerr= para erros horizontais, ou ambos para incertezas 2-D.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 5, 10)
y = np.exp(-x)
yerr = 0.1 + 0.1*x # error grows with x
plt.errorbar(x, y, yerr=yerr, fmt="o-", color="tab:blue",
ecolor="gray", elinewidth=1.5, capsize=4,
markersize=6, label="exp(-x) +/- err")
plt.legend()
plt.title("Error Bar Plot")
plt.show()Erros Assimétricos
Para incertezas assimétricas, passe yerr como array 2 x N: a linha 0 são os erros inferiores (para baixo) e a linha 1 os superiores (para cima). É comum quando os erros são distorcidos (ex.: contagens de Poisson). O mesmo padrão vale para xerr em incertezas horizontais assimétricas.
import matplotlib.pyplot as plt
import numpy as np
x = np.arange(5)
y = np.array([2, 3, 5, 4, 6])
# separate lower and upper errors (each a 1-D array)
yerr = [[0.5, 1, 0.8, 0.6, 1.2], # lower
[1.0, 0.8, 1.5, 1.0, 0.7]] # upper
plt.errorbar(x, y, yerr=yerr, fmt="s", color="tab:green",
capsize=5)
plt.title("Asymmetric Error Bars")
plt.show()
# horizontal asymmetric errors work the same way
# xerr = [[...lower...], [...upper...]]fill_between
fill_between(x, y1, y2) sombreia a região entre duas curvas y — perfeito para intervalos de confiança, bandas de erro e faixas. where= limita o preenchimento a onde um array booleano é True (use interpolate=True se as curvas se cruzam). alpha < 1 mantém a curva subjacente visível através da banda.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 10, 100)
y = np.sin(x)
std = 0.2
plt.plot(x, y, "b-", label="mean")
# shade +/- one standard deviation
plt.fill_between(x, y - std, y + std, color="blue", alpha=0.2,
label="+/- 1 std")
# shade only where a condition holds
plt.fill_between(x, y, 0, where=(y > 0), color="green", alpha=0.2,
label="y > 0")
plt.legend()
plt.show()stackplot
plt.stackplot(x, y1, y2, ...) empilha várias séries umas sobre as outras, mostrando totais e composição ao longo de um x contínuo (geralmente tempo). Diferente das barras empilhadas, é para dados contínuos. A altura total é a soma de todas as séries. Use cores distintas com alpha para que as fronteiras entre camadas fiquem claras.
import matplotlib.pyplot as plt
import numpy as np
years = np.arange(2010, 2021)
a = np.array([10, 12, 14, 15, 17, 18, 20, 22, 23, 25, 27])
b = np.array([ 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
c = np.array([ 3, 4, 4, 5, 6, 6, 7, 8, 8, 9, 10])
plt.stackplot(years, a, b, c, labels=["A", "B", "C"],
colors=["#4C72B0", "#55A868", "#C44E52"], alpha=0.8)
plt.legend(loc="upper left")
plt.title("Stacked Area Chart")
plt.xlabel("year")
plt.ylabel("value")
plt.show()fill (Polígono)
plt.fill(x, y) fecha e sombreia um polígono arbitrário — útil para destacar regiões ou sombrear sob uma curva. Para sombrear sob uma curva, concatene os valores x com seu reverso e os valores y com zeros. Para múltiplas regiões preenchidas disjuntas, passe arrays 2-D ou chame fill repetidamente.
import matplotlib.pyplot as plt
import numpy as np
# fill a closed polygon defined by its vertices
x = [0, 1, 1, 0, 0]
y = [0, 0, 1, 1, 0]
plt.fill(x, y, color="tab:cyan", alpha=0.5)
# shade under a curve
xs = np.linspace(0, 2*np.pi, 100)
ys = np.sin(xs)
plt.fill(np.r_[xs, xs[::-1]],
np.r_[ys, np.zeros_like(ys)],
color="tab:orange", alpha=0.3)
plt.title("Filled Polygons")
plt.show()Integração com Seaborn
Introdução ao Seaborn
Seaborn é uma biblioteca de gráficos estatísticos de alto nível construída sobre o Matplotlib: aceita DataFrames do pandas, cuida de agrupamento/agregação e usa padrões mais bonitos. Toda função Seaborn retorna um Axes (ou Figure) do Matplotlib, então você pode continuar personalizando com chamadas plt/ax. Chame sns.set_theme() uma vez para trocar para o estilo Seaborn.
# install seaborn
pip install seaborn
import seaborn as sns
import matplotlib.pyplot as plt
import numpy as np
# Seaborn is built ON matplotlib: any sns plot returns an Axes
# and accepts an ax= argument, so you can mix freely.
sns.set_theme() # apply seaborn's default style
tips = sns.load_dataset("tips")
ax = sns.scatterplot(data=tips, x="total_bill", y="tip", hue="time")
ax.set_title("Tips dataset")
plt.show()Estilos do Seaborn
sns.set_style define a aparência dos eixos (grade, fundo), set_context escala fontes/linhas para o meio de saída ('paper', 'talk', 'poster'), e set_palette define o ciclo de cores. sns.despine() remove as spines superior/direita. Isso se compõe num visual padrão polido com uma ou duas linhas.
import seaborn as sns
import matplotlib.pyplot as plt
# five built-in themes: darkgrid, whitegrid, dark, white, ticks
sns.set_style("whitegrid")
sns.set_context("notebook") # paper, notebook, talk, poster
# set the color palette
sns.set_palette("Set2")
import numpy as np
for i in range(4):
plt.plot(np.arange(10), np.arange(10)+i)
plt.title("Seaborn-styled")
plt.show()
# remove the top/right spines (despine) for a clean look
# sns.despine()relplot (relacional)
sns.relplot é a interface no nível de figura para gráficos relacionais: kind='scatter' (padrão) ou 'line'. col/row dividem os dados em subplots (facetas) automaticamente — muito mais fácil que subplots manuais. Retorna um FacetGrid cujo .fig e .axes permitem descer ao Matplotlib para ajustar títulos e layout.
import seaborn as sns
import matplotlib.pyplot as plt
tips = sns.load_dataset("tips")
# scatter or line, faceted by a categorical variable
g = sns.relplot(data=tips, x="total_bill", y="tip",
hue="smoker", style="time", col="day",
kind="scatter", height=3, aspect=1.2)
g.fig.suptitle("Tips by day", y=1.03)
plt.show()histplot e kdeplot
sns.histplot é a substituição moderna do distplot obsoleto: desenha histogramas e pode sobrepor uma estimativa de densidade por kernel (kde=True). stat='density' normaliza, e common_norm=False mantém grupos normalizados independentemente. sns.kdeplot desenha apenas a curva de densidade suave, útil para comparar distribuições.
import seaborn as sns
import matplotlib.pyplot as plt
tips = sns.load_dataset("tips")
# histogram with an overlaid KDE (density curve)
sns.histplot(data=tips, x="total_bill", bins=20, kde=True,
hue="time", stat="density", common_norm=False)
plt.title("Histogram + KDE")
plt.show()
# standalone KDE
plt.figure()
sns.kdeplot(data=tips, x="total_bill", hue="time", fill=True)
plt.show()heatmap
sns.heatmap desenha uma matriz colorida com anotações opcionais por célula (annot=True). center=0 com um cmap divergente (coolwarm) torna correlações positivas/negativas visualmente distintas. Ele embrulha plt.imshow + plt.text + colorbar, economizando muito boilerplate para matrizes de correlação e matrizes de confusão.
import seaborn as sns
import matplotlib.pyplot as plt
import numpy as np
# correlation matrix
tips = sns.load_dataset("tips")
num = tips.select_dtypes("number").drop(columns=["size"])
corr = num.corr()
sns.heatmap(corr, annot=True, cmap="coolwarm", center=0,
vmin=-1, vmax=1, square=True,
linewidths=0.5, fmt=".2f")
plt.title("Correlation Heatmap")
plt.show()pairplot e violinplot
sns.pairplot cria uma grade de dispersões para cada par de colunas numéricas, coloridas por uma hue categórica — a forma mais rápida de explorar relações num conjunto de dados novo. sns.violinplot combina um box plot com uma estimativa de densidade, mostrando a forma da distribuição por grupo. Ambos são Matplotlib puro por baixo e podem ser personalizados mais.
import seaborn as sns
import matplotlib.pyplot as plt
iris = sns.load_dataset("iris")
# scatter matrix: every numeric column vs every other
g = sns.pairplot(iris, hue="species", height=2.5)
g.fig.suptitle("Iris pairplot", y=1.01)
plt.show()
# violin plot: box + kernel density on each side
plt.figure()
sns.violinplot(data=iris, x="species", y="sepal_length",
inner="quartile")
plt.show()Interatividade e Animação
Widget Slider
matplotlib.widgets.Slider adiciona um slider interativo. Crie eixos para ele (geralmente no rodapé da figura via plt.axes([left, bottom, width, height] em fração da figura)), ligue um callback ao on_changed e atualize os dados do gráfico dentro dele. Chame fig.canvas.draw_idle() para atualizar. Exige um backend interativo (não Agg).
import matplotlib.pyplot as plt
from matplotlib.widgets import Slider
import numpy as np
fig, ax = plt.subplots()
plt.subplots_adjust(bottom=0.25)
x = np.linspace(0, 10, 500)
line, = ax.plot(x, np.sin(x))
# axes for the slider
ax_freq = plt.axes([0.2, 0.1, 0.6, 0.03])
slider = Slider(ax_freq, "freq", 0.1, 5.0, valinit=1.0)
def update(val):
line.set_ydata(np.sin(slider.val * x))
fig.canvas.draw_idle()
slider.on_changed(update)
plt.show()Botões
matplotlib.widgets.Button adiciona um botão clicável. Como o slider, precisa dos próprios eixos (posicionados em coordenadas de fração da figura). O callback recebe um objeto de evento que você geralmente ignora. Combine múltiplos widgets (sliders, botões, checkboxes) para construir dashboards simples de exploração de dados direto no Matplotlib.
import matplotlib.pyplot as plt
from matplotlib.widgets import Button
import numpy as np
fig, ax = plt.subplots()
plt.subplots_adjust(bottom=0.2)
(ln,) = ax.plot(np.random.rand(10))
ax_btn = plt.axes([0.7, 0.05, 0.2, 0.075])
btn = Button(ax_btn, "Resample")
def reshuffle(event):
ln.set_ydata(np.random.rand(10))
fig.canvas.draw_idle()
btn.on_clicked(reshuffle)
plt.show()CheckButtons
CheckButtons renderiza uma lista de checkboxes. O callback recebe o texto do label alternado, então você faz match nele para trocar a visibilidade de cada artista. Use-o para deixar o espectador ligar e desligar séries. Como em cada um dos widgets, você precisa de um backend interativo e a janela deve permanecer aberta.
import matplotlib.pyplot as plt
from matplotlib.widgets import CheckButtons
import numpy as np
x = np.linspace(0, 5, 200)
l1, = plt.plot(x, np.sin(x), label="sin")
l2, = plt.plot(x, np.cos(x), label="cos")
plt.subplots_adjust(right=0.8)
rax = plt.axes([0.82, 0.4, 0.15, 0.2])
check = CheckButtons(rax, ["sin", "cos"], [True, True])
def toggle(label):
if label == "sin": l1.set_visible(not l1.get_visible())
if label == "cos": l2.set_visible(not l2.get_visible())
plt.draw()
check.on_clicked(toggle)
plt.show()Cursor e Eventos de Mouse
mpl_connect liga eventos (button_press_event, motion_notify_event, key_press_event, scroll_event) a callbacks. O objeto de evento carrega event.xdata/event.ydata (coords de dados) e event.inaxes (quais eixos, ou None). Essa é a base para interações personalizadas — miras, clique para anotar, ferramentas de zoom próprias.
import matplotlib.pyplot as plt
fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4], [1, 4, 2, 3])
def on_click(event):
if event.inaxes != ax:
return
print(f"clicked at x={event.xdata:.2f} y={event.ydata:.2f}")
def on_move(event):
if event.inaxes == ax:
ax.set_title(f"x={event.xdata:.2f}, y={event.ydata:.2f}")
fig.canvas.draw_idle()
fig.canvas.mpl_connect("button_press_event", on_click)
fig.canvas.mpl_connect("motion_notify_event", on_move)
plt.show()Animação (FuncAnimation)
FuncAnimation conduz uma animação chamando update(frame) repetidamente. update deve retornar os artistas alterados (como tupla) para que blit=True redesenhe apenas eles, por velocidade. interval é o atraso entre quadros em ms. Salvar exige um writer ('ffmpeg' para mp4, 'pillow' para gif). Mantenha o objeto de animação (ani) referenciado, senão ele é coletado pelo garbage collector e para.
import matplotlib.pyplot as plt
import matplotlib.animation as animation
import numpy as np
fig, ax = plt.subplots()
x = np.linspace(0, 2*np.pi, 200)
line, = ax.plot(x, np.sin(x))
def update(frame):
line.set_ydata(np.sin(x + frame / 10.0))
return line,
ani = animation.FuncAnimation(fig, update, frames=100,
interval=50, blit=True, repeat=True)
# save to a file (requires ffmpeg or pillow installed)
# ani.save("wave.mp4", writer="ffmpeg")
# ani.save("wave.gif", writer="pillow")
plt.show()Snippets de Matplotlib relacionados
Copy-paste ready code for common tasks.
Line Plot
Plot lines with markers, colors, and styles.
Bar Chart
Draw vertical, horizontal, and grouped bars.
Scatter Plot
Visualize relationships with size and color encodings.
Subplots
Arrange multiple axes with subplots and GridSpec.
Labels and Legend
Annotate plots with text, arrows, and legend options.
Styles and Themes
Apply built-in styles and customize rcParams.
Save Figure
Export figures to PNG, PDF, and SVG with DPI control.
3D Plot
Render surfaces and scatter in 3D.
Was this helpful?