Matplotlib Pyplot

matplotlib.pyplot é uma coleção de funções que fazem o Matplotlib se comportar como o sistema de plotagem do MATLAB. Cada função cria ou modifica algum elemento de uma figura — adicionando eixos, desenhando uma linha, definindo um título — e o pyplot mantém o controle da figura e dos eixos "atuais" automaticamente, sem que você precise passar objetos manualmente. Esta página explica como esse modelo stateful funciona, percorre as funções pyplot mais importantes e mostra quando trocar para a API orientada a objetos explícita.

O que é matplotlib.pyplot?

O Matplotlib possui duas interfaces principais:

Ambas as interfaces pertencem à mesma biblioteca. O pyplot é uma camada de conveniência — cada chamada plt.algo() acaba manipulando os mesmos objetos Figure e Axes que a interface OO expõe diretamente. Entender essa relação permite misturar os dois estilos com confiança.

O alias padrão é plt:

import matplotlib.pyplot as plt

Como funciona a interface stateful

O pyplot mantém uma referência interna à figura atual e aos eixos atuais. Ao chamar plt.plot(), o Matplotlib:

1. Verifica se já existe uma figura; se não, cria uma.
2. Verifica se essa figura possui eixos; se não, adiciona um único Axes para preencher a figura.
3. Desenha os dados nesses eixos.

import matplotlib.pyplot as plt

# No figure exists yet — pyplot creates one automatically
plt.plot([1, 2, 3], [4, 6, 5])
plt.title("My first plot")
plt.show()

A figura e os eixos foram criados implicitamente. Isso é conveniente para gráficos pontuais, mas pode causar surpresas ao executar vários gráficos no mesmo script. Use plt.figure() e plt.clf() (clear figure) ou plt.close() para controlar o estado explicitamente.

Funções principais do pyplot

plt.plot() — Desenhar linhas e marcadores

plt.plot(x, y) é a função principal. Ela desenha linhas, marcadores ou ambos.

import matplotlib.pyplot as plt

months = [1, 2, 3, 4, 5, 6]
revenue = [12000, 15000, 13500, 17000, 19500, 22000]

plt.plot(months, revenue, color="steelblue", linewidth=2, marker="o", markersize=6)
plt.xlabel("Month")
plt.ylabel("Revenue ($)")
plt.title("Monthly Revenue")
plt.grid(True, linestyle="--", alpha=0.5)
plt.show()

Parâmetros principais do plt.plot():

plt.xlabel(), plt.ylabel(), plt.title()

Rotule os eixos e adicione um título. Os três aceitam o argumento fontsize:

import matplotlib.pyplot as plt

plt.plot([0, 1, 2], [0, 1, 4])
plt.xlabel("x", fontsize=12)
plt.ylabel("x²", fontsize=12)
plt.title("Quadratic Growth", fontsize=14, fontweight="bold")
plt.show()

plt.legend()

Ao passar label= em uma chamada de plot, plt.legend() transforma esses rótulos em uma caixa no gráfico:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]

plt.plot(x, [v**1 for v in x], label="Linear")
plt.plot(x, [v**2 for v in x], label="Quadratic")
plt.plot(x, [v**3 for v in x], label="Cubic")
plt.xlabel("x")
plt.ylabel("y")
plt.title("Growth Rates")
plt.legend()
plt.show()

Controle o posicionamento da legenda com o parâmetro loc: "upper left", "lower right", "best" (padrão), entre outros.

plt.grid()

plt.grid(True) adiciona linhas de grade. Use axis="x" ou axis="y" para restringir a um eixo, e passe linestyle / alpha para estilizar as linhas:

plt.grid(True, axis="y", linestyle="--", alpha=0.7)

plt.xlim() e plt.ylim()

Defina o intervalo visível em cada eixo:

import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4, 5], [2, 4, 1, 5, 3])
plt.xlim(0, 6)     # show a bit of padding on each side
plt.ylim(0, 7)
plt.show()

plt.xticks() e plt.yticks()

Controle quais marcas de escala aparecem e que rótulos elas exibem:

import matplotlib.pyplot as plt

plt.plot([0, 1, 2, 3, 4], [10, 20, 15, 25, 30])
plt.xticks([0, 1, 2, 3, 4], ["Mon", "Tue", "Wed", "Thu", "Fri"])
plt.yticks([10, 20, 30], ["Low", "Mid", "High"])
plt.show()

plt.figure()

Crie uma nova figura explicitamente. Isso é importante em scripts que produzem vários gráficos separados:

import matplotlib.pyplot as plt

plt.figure(figsize=(8, 4))          # width, height in inches
plt.plot([1, 2, 3], [3, 1, 4])
plt.title("Figure with custom size")
plt.show()

figsize controla o tamanho da saída. Uma figura mais larga (por exemplo, (12, 4)) é adequada para dados de séries temporais; uma figura quadrada é adequada para gráficos de dispersão.

plt.savefig()

Salve a figura atual em um arquivo em vez de (ou além de) exibi-la:

import matplotlib.pyplot as plt

plt.plot([1, 2, 3], [1, 4, 9])
plt.title("Saved Plot")
plt.savefig("output.png", dpi=150, bbox_inches="tight")
plt.show()

Os formatos suportados incluem png, pdf, svg e jpg. bbox_inches="tight" remove o espaço em branco extra ao redor da figura. Chame savefig() antes de show() — show() limpa o estado da figura em alguns backends.

plt.close() e plt.clf()

Em um loop que produz muitas figuras, sempre feche as figuras que não são mais necessárias para liberar memória:

plt.close()       # close the current figure
plt.close("all")  # close every open figure
plt.clf()         # clear the current figure without closing its window

Subplots via pyplot

plt.subplots() é a ponte entre as interfaces pyplot e OO. Ela cria um objeto Figure e um ou mais objetos Axes, retornando ambos:

import matplotlib.pyplot as plt

fig, axes = plt.subplots(1, 2, figsize=(10, 4))  # 1 row, 2 columns

# Left panel
axes[0].plot([1, 2, 3], [1, 4, 9], color="steelblue")
axes[0].set_title("Quadratic")
axes[0].set_xlabel("x")
axes[0].set_ylabel("x²")

# Right panel
axes[1].plot([1, 2, 3], [1, 8, 27], color="tomato")
axes[1].set_title("Cubic")
axes[1].set_xlabel("x")
axes[1].set_ylabel("x³")

fig.suptitle("Growth Curves", fontsize=14)
plt.tight_layout()
plt.show()

plt.tight_layout() ajusta automaticamente o espaçamento entre os painéis para evitar que títulos e rótulos se sobreponham.

pyplot vs. a API orientada a objetos

Ao trabalhar com mais de um único eixo, a API stateful se torna mais difícil de raciocinar. Use a API OO (via fig, ax = plt.subplots()) quando:

• Você tiver mais de um subplot.
• Estiver escrevendo uma função que cria e retorna um gráfico.
• Precisar de controle refinado sobre formatadores de escala, eixos secundários ou eixos inseridos.

O padrão é simples: a maioria das funções plt.algo() possui um equivalente ax.set_algo() no objeto Axes.

Um exemplo completo

O script a seguir combina as funções pyplot mais comuns em um exemplo completo e executável:

import matplotlib.pyplot as plt

# Data
years = [2019, 2020, 2021, 2022, 2023]
product_a = [45, 38, 52, 61, 70]
product_b = [30, 42, 39, 55, 65]

# Figure
plt.figure(figsize=(9, 5))

# Two series
plt.plot(years, product_a, marker="o", color="steelblue",
         linewidth=2, label="Product A")
plt.plot(years, product_b, marker="s", color="tomato",
         linewidth=2, label="Product B")

# Labels and decoration
plt.xlabel("Year", fontsize=12)
plt.ylabel("Units Sold (thousands)", fontsize=12)
plt.title("Annual Sales Comparison", fontsize=14)
plt.legend()
plt.grid(True, linestyle="--", alpha=0.5)
plt.xticks(years)

# Save and display
plt.savefig("sales_comparison.png", dpi=150, bbox_inches="tight")
plt.show()

Este exemplo mostra duas séries nos mesmos eixos, uma legenda, grade, rótulos personalizados no eixo x e salva o resultado em um arquivo PNG.

Erros comuns

Esquecer plt.show() — em um script Python comum (não Jupyter), a janela do gráfico nunca abre sem ele. No Jupyter, %matplotlib inline torna isso automático.

Chamar plt.savefig() após plt.show() — show() finaliza e reinicia a figura. Salve primeiro, depois exiba:

plt.savefig("chart.png")  # correct order
plt.show()

Figuras múltiplas se acumulando — em um loop, cada chamada plt.figure() cria uma nova figura que permanece na memória até você chamar plt.close(). Feche as figuras que não são mais necessárias.

Misturar estilos pyplot e OO de forma inconsistente — é válido usar os dois, mas seja deliberado: obtenha o objeto Axes e trabalhe com ele diretamente em vez de depender do "eixo atual" implícito do pyplot quando você tiver mais de um eixo.

Próximos passos

• Gráficos de Linhas no Matplotlib — estilos de linha, múltiplas séries e áreas preenchidas em profundidade.
• Marcadores no Matplotlib — todas as formas de marcadores integradas e como estilizá-las.
• Rótulos no Matplotlib — títulos, rótulos de eixos, anotações e posicionamento de texto.
• Grade no Matplotlib — estilos de linhas de grade, marcas de escala secundárias e estilização do fundo.
• Barras no Matplotlib — gráficos de barras verticais, horizontais, empilhadas e agrupadas.
• Dispersão no Matplotlib — gráficos de dispersão com mapas de cores e codificação por tamanho.
• Histogramas no Matplotlib — controle de intervalos, curvas de densidade e distribuições sobrepostas.
• Subplot no Matplotlib — layouts com múltiplos painéis usando subplots() e GridSpec.