Skip to content

Matplotlib Folha de referência

Biblioteca Python completa de gráficos para visualização de dados.

01

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.

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

matplotlib
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.

matplotlib
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.

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

Backends 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.

matplotlib
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 backend
02

Grá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.

matplotlib
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.

matplotlib
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'.

matplotlib
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.

matplotlib
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.

matplotlib
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.

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

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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

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

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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

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

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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

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

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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

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

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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

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

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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

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

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+.

matplotlib
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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

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

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.

matplotlib
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).

matplotlib
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.

matplotlib
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).

matplotlib
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.

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

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.

matplotlib
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.

matplotlib
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.

matplotlib
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).

matplotlib
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.

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

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

matplotlib
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.

matplotlib
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.

matplotlib
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'.

matplotlib
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 Bbox

Transparente 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.

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

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.

matplotlib
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.

matplotlib
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).

matplotlib
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.

matplotlib
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.

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

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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

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

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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

matplotlib
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]
16

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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

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

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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

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

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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

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

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.

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

matplotlib
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.

matplotlib
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.

matplotlib
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.

matplotlib
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.

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

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

matplotlib
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.

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.

matplotlib
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.

matplotlib
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.

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

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.