Adicionar texto dentro do gráfico no Matplotlib

Use matplotlib.pyplot.text() para colocar um rótulo ou uma nota em uma posição escolhida dentro de um gráfico do Matplotlib. A função recebe as coordenadas x e y seguidas da string a ser exibida; argumentos opcionais controlam a aparência do texto. Por exemplo, plt.text(2, 20, "Peak point") coloca um rótulo na coordenada de dados (2, 20). Com um objeto de eixos, use a chamada equivalente ax.text(2, 20, "Peak point"). Consulte a referência da API de pyplot.text() para ver a lista completa de parâmetros.

Use matplotlib.pyplot.text() para adicionar texto a um gráfico

O exemplo a seguir desenha uma linha e coloca um rótulo em um dos seus pontos de dados. Ele utiliza a interface pyplot e define o intervalo exibido de modo que as coordenadas escolhidas fiquem dentro do gráfico.

import matplotlib.pyplot as plt

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

plt.plot(x, y, marker="o")
plt.xlim(0, 5)
plt.ylim(0, 35)
plt.text(3, 25, "Peak point", fontsize=12, color="crimson")
plt.title("A labeled line plot")
plt.xlabel("X")
plt.ylabel("Y")
plt.show()

x e y contêm os dados plotados, e a chamada coloca “Peak point” na coordenada (3, 25). As duas chamadas de limites incluem essa coordenada no intervalo visível. Em scripts que criam vários gráficos, ax.text(x, y, label) anexa o texto a um objeto de eixos específico e deixa claro qual gráfico o recebe. A chamada pyplot é conveniente para um único gráfico atual. O rótulo “Peak point” permanece em inglês no código inalterado.

Posicionar texto com coordenadas de dados e limites dos eixos

Por padrão, os argumentos x e y de text() usam coordenadas de dados. Um rótulo em (3, 25) segue, portanto, esses valores no gráfico; ele não é posicionado por distância em pixels a partir de um canto. Os limites atuais de x e y determinam qual parte do plano de coordenadas de dados fica visível. Defina limites adequados com plt.xlim() e plt.ylim(), ou use ax.set_xlim() e ax.set_ylim() com um objeto de eixos.

Escolha uma posição que mantenha o rótulo legível e não cubra dados importantes. Para uma nota que deve permanecer em uma fração fixa dos eixos, independentemente dos valores dos dados, use coordenadas de eixos por meio de transform=ax.transAxes; (0, 0) é o canto inferior esquerdo e (1, 1) o canto superior direito dos eixos. Isso difere das coordenadas de dados padrão e é útil para legendas ancoradas dentro de um gráfico. O exemplo a seguir combina os dois sistemas: o rótulo de dados permanece em (3, 25), enquanto a nota de rascunho permanece no canto superior esquerdo dos eixos mesmo que os dados ou os limites mudem.

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4], [10, 15, 25, 30], marker="o")
ax.set_xlim(0, 5)
ax.set_ylim(0, 35)
ax.text(3, 25, "Peak point", fontsize=12, color="crimson")
ax.text(0.02, 0.95, "Draft - internal data", transform=ax.transAxes,
        fontsize=10, ha="left", va="top")
ax.set_title("Data and axes coordinates")
plt.show()

Um caso limite surpreende muitos usuários: o texto é ancorado nas suas coordenadas, mas, por padrão, não é recortado aos eixos. Um rótulo que começa dentro do gráfico pode transbordar a borda dos eixos para a margem, e um rótulo ancorado fora dos limites é desenhado fora da área dos eixos. Passe clip_on=True para cortar o texto exatamente na borda dos eixos. O exemplo inicia dois rótulos idênticos em x = 4,6, perto da borda direita em x = 5:

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4], [10, 15, 25, 30], marker="o")
ax.set_xlim(0, 5)
ax.set_ylim(0, 35)
ax.text(4.6, 32, "Clipped at the edge", fontsize=12, clip_on=True)
ax.text(4.6, 27, "Drawn in full", fontsize=12)
ax.set_title("Text at the axes edge")
plt.show()

O primeiro rótulo para na borda direita dos eixos; o segundo continua para a margem. Se um rótulo precisa permanecer legível, mantenha sua âncora e sua largura total dentro dos limites — amplie os limites ou mova a âncora — em vez de depender do recorte, que remove o excesso sem avisar. Os rótulos “Clipped at the edge” e “Drawn in full” permanecem em inglês, como todo o código.

Personalizar a aparência do texto

Passe argumentos de palavra-chave para text() para estilizar um rótulo. fontsize altera seu tamanho, color define sua cor e fontweight="bold" o destaca. Defina rotation para girar o texto e use horizontalalignment (ou ha) e verticalalignment (ou va) para alinhá-lo em torno de suas coordenadas x e y. Por exemplo, ha="center" e va="bottom" centralizam um rótulo sobre um ponto, mantendo-o acima desse ponto.

Um argumento bbox adiciona um fundo atrás do texto, o que pode separar um rótulo de uma linha ou marcador movimentados. Ele aceita um dicionário de propriedades de patch. Este exemplo combina alinhamento, ênfase, rotação e uma caixa branca translúcida:

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3], [2, 4, 3], marker="o")
ax.set_ylim(1.8, 4.7)
ax.text(2, 4, "Peak", fontsize=12, color="crimson", fontweight="bold",
        ha="center", va="bottom", rotation=15,
        bbox={"facecolor": "white", "alpha": 0.8})
ax.set_title("Styled text")
plt.show()

Por exemplo, bbox={"facecolor": "white", "alpha": 0.8} cria um fundo branco parcialmente transparente. Use apenas opções que melhorem a legibilidade; cores fortes, fontes grandes ou rotação podem competir com os dados quando aplicados amplamente. O rótulo exibido no exemplo de código inalterado permanece em inglês.

Adicionar anotações e texto em várias linhas

Use plt.annotate() quando uma nota precisa apontar para um elemento. Seu argumento xy identifica o ponto de dados descrito, enquanto xytext indica a posição do texto. A posição do texto da anotação também usa coordenadas de dados por padrão; defina limites que incluam tanto o alvo quanto a nota. Com eixos, use ax.annotate() para que o alvo e a nota pertençam ao gráfico pretendido.

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4], [10, 15, 25, 30], marker="o")
ax.set_xlim(0, 5)
ax.set_ylim(0, 35)
ax.annotate("Peak", xy=(3, 25), xytext=(1.2, 31),
            arrowprops={"arrowstyle": "->"})
ax.set_title("Annotation with an arrow")
plt.show()

Aqui, arrowprops={"arrowstyle": "->"} desenha a seta da nota em (1,2, 31) até o pico em (3, 25). Sem arrowprops, annotate() coloca texto simples de forma muito parecida com text().

Para uma nota em várias linhas, inclua caracteres de quebra de linha na string passada para text(), como "First line\nSecond line". O Matplotlib renderiza cada segmento em sua própria linha na posição selecionada. Um rótulo de várias linhas é útil para uma explicação compacta; ajuste sua posição e seu alinhamento para que ele permaneça dentro da área visível do gráfico e não oculte os dados próximos.

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4], [10, 15, 25, 30], marker="o")
ax.set_xlim(0, 5)
ax.set_ylim(0, 35)
ax.text(0.4, 33, "First line\nSecond line", fontsize=12, va="top")
ax.set_title("Multi-line text")
plt.show()

Com va="top", a coordenada y (33) ancora o topo do bloco de duas linhas, de modo que ambas as linhas permanecem dentro do gráfico. Os rótulos “Peak”, “First line” e “Second line” permanecem em inglês nos exemplos inalterados. Essas técnicas permitem adicionar rótulos, contexto e ponteiros, mantendo cada nota vinculada às coordenadas ou ao elemento que ela descreve.