Rótulos no Matplotlib

Os rótulos transformam um gráfico bruto em uma história legível. Este capítulo cobre todos os principais elementos de rótulo no Matplotlib: rótulos de eixos, títulos de gráficos, legendas, rótulos de marcações e anotações de texto. Para cada elemento você verá a função essencial, seus parâmetros mais úteis e exemplos práticos que podem ser executados imediatamente.

Antes de começar, certifique-se de que o Matplotlib está instalado. Consulte Primeiros Passos com Matplotlib para instruções de configuração.

Definindo Rótulos de Eixos

As funções xlabel() e ylabel() adicionam texto descritivo aos eixos horizontal e vertical. Ambas aceitam os mesmos parâmetros.

import matplotlib.pyplot as plt

height = [63, 64, 65, 66, 67, 68, 69, 70, 71, 72]
weight = [127, 130, 133, 136, 139, 142, 145, 148, 151, 154]

plt.scatter(height, weight)
plt.xlabel('Height (inches)')
plt.ylabel('Weight (pounds)')
plt.show()

Personalizando a Aparência dos Rótulos

Ambas as funções aceitam um argumento fontsize (em pontos) e qualquer palavra-chave da classe Text do Matplotlib, como color, fontweight e fontstyle.

import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]
y = [2, 4, 6, 8, 10]

plt.plot(x, y)
plt.xlabel('Time (seconds)', fontsize=13, color='steelblue', fontweight='bold')
plt.ylabel('Distance (meters)', fontsize=13, color='steelblue', fontweight='bold')
plt.show()

Ajustando o Espaçamento dos Rótulos

Use o parâmetro labelpad para afastar um rótulo das marcações do eixo — útil quando os rótulos de marcações são longos ou estão rotacionados.

import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]
y = [1000, 2000, 3000, 4000, 5000]

plt.plot(x, y)
plt.xlabel('Quarter', labelpad=12)
plt.ylabel('Revenue ($)', labelpad=16)
plt.show()

Adicionando um Título ao Gráfico

A função title() adiciona um título centralizado acima do gráfico por padrão.

import matplotlib.pyplot as plt

months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
          'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
sales = [25000, 30000, 45000, 35000, 50000, 60000,
         70000, 80000, 90000, 100000, 110000, 120000]

plt.plot(months, sales)
plt.title('Monthly Sales')
plt.xlabel('Month')
plt.ylabel('Sales ($)')
plt.show()

Posicionamento e Estilo do Título

Passe loc ('left', 'center', 'right') para alterar o alinhamento horizontal, e pad para controlar o espaço entre o título e a parte superior do gráfico.

import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]
y = [3, 7, 2, 9, 4]

plt.plot(x, y, marker='o')
plt.title('Sensor Readings', loc='left', pad=14,
          fontsize=15, fontweight='bold', color='darkslategray')
plt.show()

Título da Figura com suptitle()

Quando uma figura contém múltiplos subgráficos, use suptitle() para adicionar um título que abranja todos eles. Os subgráficos individuais ainda podem ter seu próprio title().

import matplotlib.pyplot as plt

fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(8, 3))

ax1.plot([1, 2, 3], [4, 5, 6])
ax1.set_title('Product A')

ax2.plot([1, 2, 3], [6, 5, 4])
ax2.set_title('Product B')

fig.suptitle('Q1 Sales Comparison', fontsize=14, fontweight='bold')
plt.tight_layout()
plt.show()

tight_layout() evita que o título da figura sobreponha o conteúdo dos subgráficos. Consulte Subgráficos no Matplotlib para um tratamento completo de figuras com múltiplos painéis.

Personalizando a Legenda

Uma legenda identifica as séries de dados no seu gráfico. Chame legend() após plotar as séries.

Legenda Básica

Passe uma palavra-chave label para cada chamada de plotagem, em seguida chame plt.legend() para renderizá-la.

import matplotlib.pyplot as plt

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

plt.plot(x, [2, 4, 6, 8, 10], label='Series A')
plt.plot(x, [1, 3, 5, 7, 9],  label='Series B')
plt.legend()
plt.xlabel('x')
plt.ylabel('y')
plt.title('Two Series')
plt.show()

Posição da Legenda

Passe o parâmetro loc para posicionar a legenda com precisão. Valores comuns: 'upper left', 'upper right', 'lower left', 'lower right', 'center' ou 'best' (o Matplotlib escolhe a posição com menor sobreposição — o padrão).

import matplotlib.pyplot as plt

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

plt.plot(x, [2, 4, 6, 8, 10], label='Revenue')
plt.plot(x, [1, 2, 3, 4, 5],  label='Costs')
plt.legend(loc='upper left')
plt.show()

Legenda Fora dos Eixos

Use bbox_to_anchor junto com loc para posicionar a legenda fora da área do gráfico. Chame tight_layout() ou ajuste subplots_adjust para que a legenda não seja cortada.

import matplotlib.pyplot as plt

x = [1, 2, 3, 4]
fig, ax = plt.subplots()

ax.plot(x, [1, 4, 9, 16],  label='Quadratic')
ax.plot(x, [1, 8, 27, 64], label='Cubic')
ax.legend(loc='upper left', bbox_to_anchor=(1, 1))
plt.tight_layout()
plt.show()

Estilizando a Legenda

import matplotlib.pyplot as plt

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

plt.plot(x, [2, 4, 6, 8, 10], label='Actual')
plt.plot(x, [1, 3, 5, 7, 9],  label='Forecast', linestyle='--')
plt.legend(
    title='Data',
    fontsize=11,
    title_fontsize=12,
    framealpha=0.9,
    edgecolor='gray',
)
plt.show()

framealpha controla a opacidade da caixa da legenda (0 = transparente, 1 = sólido). title adiciona um cabeçalho dentro da caixa da legenda.

Personalizando os Rótulos de Marcações

Os rótulos de marcações são os números ou strings que o Matplotlib imprime ao longo de cada eixo. Use xticks() e yticks() para substituí-los.

Rotacionando Rótulos de Marcações

Nomes de categorias longos se sobrepõem por padrão. Rotacione-os com o parâmetro rotation.

import matplotlib.pyplot as plt

categories = ['January', 'February', 'March', 'April', 'May', 'June']
values = [12, 19, 14, 22, 18, 25]

plt.bar(categories, values)
plt.xticks(rotation=45, ha='right')
plt.ylabel('Units sold')
plt.title('Monthly Sales')
plt.tight_layout()
plt.show()

ha='right' alinha a borda direita de cada rótulo com sua marcação, o que fica mais organizado após a rotação.

Definindo Valores e Rótulos de Marcações Personalizados

Passe duas listas para xticks(): as posições das marcações e as strings a serem exibidas.

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 2 * np.pi, 100)
plt.plot(x, np.sin(x))

ticks = [0, np.pi / 2, np.pi, 3 * np.pi / 2, 2 * np.pi]
labels = ['0', 'π/2', 'π', '3π/2', '2π']
plt.xticks(ticks, labels, fontsize=12)
plt.ylabel('sin(x)')
plt.title('Sine Wave with Custom Tick Labels')
plt.show()

Estilizando a Fonte dos Rótulos de Marcações

Tanto xticks() quanto yticks() aceitam argumentos de palavra-chave de fonte diretamente.

import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]
y = [10, 20, 15, 30, 25]

plt.plot(x, y)
plt.xticks(fontsize=12, color='steelblue')
plt.yticks(fontsize=12, color='steelblue')
plt.show()

Adicionando Anotações de Texto

A função text() posiciona uma string em uma posição arbitrária dentro do sistema de coordenadas dos eixos.

import matplotlib.pyplot as plt

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

plt.plot(x, y, marker='o')
plt.text(3, 3.2, 'dip here', fontsize=11, color='crimson')
plt.title('Text Annotation Example')
plt.show()

Os dois primeiros argumentos são as coordenadas x e y em unidades de dados.

Anotando com uma Seta

annotate() desenha um rótulo mais uma seta opcional apontando para um ponto de dados específico. É a ferramenta certa quando você deseja destacar valores discrepantes ou picos.

import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]
y = [4, 7, 2, 9, 3]

plt.plot(x, y, marker='o')
plt.annotate(
    'Peak',
    xy=(4, 9),           # tip of the arrow (the data point)
    xytext=(3.2, 9.5),   # where the label sits
    arrowprops=dict(arrowstyle='->', color='black'),
    fontsize=12,
)
plt.title('Annotated Line Plot')
plt.show()

API Orientada a Objetos: Usando Métodos de Axes

Todas as funções acima são atalhos convenientes para os eixos ativos atuais. Ao trabalhar com múltiplos subgráficos — ou sempre que precisar de controle preciso — use os métodos do objeto Axes diretamente: ax.set_xlabel(), ax.set_ylabel(), ax.set_title(), ax.legend() e ax.set_xticks().

import matplotlib.pyplot as plt

fig, ax = plt.subplots()

months = ['Jan', 'Feb', 'Mar', 'Apr']
revenue = [12000, 15000, 13000, 18000]
costs   = [8000,  9000, 10000, 11000]

ax.plot(months, revenue, marker='o', label='Revenue')
ax.plot(months, costs,   marker='s', label='Costs', linestyle='--')

ax.set_xlabel('Month', fontsize=12)
ax.set_ylabel('Amount ($)', fontsize=12)
ax.set_title('Revenue vs Costs — Q1', fontsize=14)
ax.legend(loc='upper left')

plt.tight_layout()
plt.show()

Prefira o estilo orientado a objetos quando seu script criar mais de um eixo. Os atalhos plt.* direcionam para qualquer eixo que estiver ativo no momento, o que pode produzir bugs difíceis de rastrear em figuras com múltiplos subgráficos.

Referência Rápida

Capítulos Relacionados

• Plotagem no Matplotlib — desenhar linhas e pontos
• Linha no Matplotlib — opções de estilo e cor de linha
• Marcadores no Matplotlib — formas e tamanhos de marcadores
• Grade no Matplotlib — adicionar linhas de grade a um gráfico
• Subgráficos no Matplotlib — figuras com múltiplos painéis