Guia de início rápido

Este tutorial aborda alguns padrões básicos de uso e práticas recomendadas para ajudá-lo a começar a usar o Matplotlib.

import matplotlib as mpl
import matplotlib.pyplot as plt
import numpy as np

Um exemplo simples

O Matplotlib representa graficamente seus dados em Figures (por exemplo, janelas, widgets Jupyter, etc.), cada um dos quais pode conter um ou mais Axes, uma área onde os pontos podem ser especificados em termos de coordenadas xy (ou theta-r em um gráfico polar, xyz em um gráfico 3D, etc). A maneira mais simples de criar uma figura com eixos é usando pyplot.subplots. Podemos então usar Axes.plotpara desenhar alguns dados nos eixos:

fig, ax = plt.subplots()  # Create a figure containing a single axes.
ax.plot([1, 2, 3, 4], [1, 4, 2, 3]);  # Plot some data on the axes.

[<matplotlib.lines.Line2D object at 0x7f2cdf586e60>]

Partes de uma Figura

Aqui estão os componentes de uma Figura Matplotlib.

Figure

A figura inteira . A Figura acompanha todas as crianças Axes, um grupo de Artistas 'especiais' (títulos, legendas de figuras, barras de cores, etc.) e até mesmo subfiguras aninhadas.

A maneira mais fácil de criar uma nova Figura é com o pyplot:

fig = plt.figure()  # an empty figure with no Axes
fig, ax = plt.subplots()  # a figure with a single Axes
fig, axs = plt.subplots(2, 2)  # a figure with a 2x2 grid of Axes

Muitas vezes é conveniente criar os Eixos junto com a Figura, mas você também pode adicionar manualmente os Eixos posteriormente. Observe que muitos back-ends do Matplotlib suportam zoom e panorâmica em janelas de figuras.

Axes

Um Axes é um Artista anexado a uma Figura que contém uma região para plotagem de dados e geralmente inclui dois (ou três no caso de 3D) Axisobjetos (esteja ciente da diferença entre Axes e Axis ) que fornecem marcas e rótulos de marcas para fornecer escalas para os dados nos Axes. Cada um Axestambém tem um título (definido por meio set_title()de ), um rótulo x (definido por meio set_xlabel()de ) e um rótulo y definido por meio de set_ylabel()).

A Axesclasse e suas funções de membro são o principal ponto de entrada para trabalhar com a interface OOP e têm a maioria dos métodos de plotagem definidos nelas (por exemplo ax.plot(), mostrado acima, usa o plotmétodo)

Axis

Esses objetos definem a escala e os limites e geram ticks (as marcas no Axis) e ticklabels (strings que rotulam os ticks). A localização dos ticks é determinada por um Locatorobjeto e as sequências de ticklabel são formatadas por um Formatter. A combinação do correto Locatore Formatterfornece um controle muito preciso sobre os locais e rótulos dos ticks.

Artist

Basicamente, tudo o que é visível na Figura é um Artista (mesmo Figure, Axes, e Axisobjetos). Isso inclui Textobjetos, Line2Dobjetos, collectionsobjetos, Patch objetos, etc. Quando a Figura é renderizada, todos os Artistas são desenhados na tela . A maioria dos Artistas está ligada a um Machado; tal Artista não pode ser compartilhado por múltiplos Eixos, ou movido de um para outro.

Tipos de entradas para funções de plotagem

Funções de plotagem esperam numpy.arrayou numpy.ma.masked_arraycomo entrada, ou objetos que podem ser passados ​​para numpy.asarray. Classes que são semelhantes a arrays ('semelhantes a arrays'), como pandas objetos de dados, numpy.matrixpodem não funcionar conforme o esperado. A convenção comum é convertê-los em numpy.arrayobjetos antes da plotagem. Por exemplo, para converter umnumpy.matrix

b = np.matrix([[1, 2], [3, 4]])
b_asarray = np.asarray(b)

A maioria dos métodos também analisará um objeto endereçável como um dict , a numpy.recarrayou a pandas.DataFrame. Matplotlib permite que você forneça o dataargumento de palavra-chave e gere gráficos passando as strings correspondentes às variáveis ​​x e y .

np.random.seed(19680801)  # seed the random number generator.
data = {'a': np.arange(50),
        'c': np.random.randint(0, 50, 50),
        'd': np.random.randn(50)}
data['b'] = data['a'] + 10 * np.random.randn(50)
data['d'] = np.abs(data['d']) * 100

fig, ax = plt.subplots(figsize=(5, 2.7), layout='constrained')
ax.scatter('a', 'b', c='c', s='d', data=data)
ax.set_xlabel('entry a')
ax.set_ylabel('entry b');

Text(36.334, 0.5, 'entry b')

Estilos de codificação

As interfaces explícitas e implícitas

Conforme observado acima, existem essencialmente duas maneiras de usar o Matplotlib:

• Crie figuras e eixos explicitamente e chame métodos neles (o "estilo orientado a objetos (OO)").

• Confie no pyplot para criar e gerenciar implicitamente as Figuras e os Eixos e use as funções do pyplot para plotar.

Consulte Matplotlib Application Interfaces (APIs) para obter uma explicação das compensações entre as interfaces implícitas e explícitas.

Assim, pode-se usar o estilo OO

x = np.linspace(0, 2, 100)  # Sample data.

# Note that even in the OO-style, we use `.pyplot.figure` to create the Figure.
fig, ax = plt.subplots(figsize=(5, 2.7), layout='constrained')
ax.plot(x, x, label='linear')  # Plot some data on the axes.
ax.plot(x, x**2, label='quadratic')  # Plot more data on the axes...
ax.plot(x, x**3, label='cubic')  # ... and some more.
ax.set_xlabel('x label')  # Add an x-label to the axes.
ax.set_ylabel('y label')  # Add a y-label to the axes.
ax.set_title("Simple Plot")  # Add a title to the axes.
ax.legend();  # Add a legend.

<matplotlib.legend.Legend object at 0x7f2cdf587f70>

ou o estilo pyplot:

x = np.linspace(0, 2, 100)  # Sample data.

plt.figure(figsize=(5, 2.7), layout='constrained')
plt.plot(x, x, label='linear')  # Plot some data on the (implicit) axes.
plt.plot(x, x**2, label='quadratic')  # etc.
plt.plot(x, x**3, label='cubic')
plt.xlabel('x label')
plt.ylabel('y label')
plt.title("Simple Plot")
plt.legend();

<matplotlib.legend.Legend object at 0x7f2cfa992cb0>

(Além disso, há uma terceira abordagem, para o caso de incorporação do Matplotlib em um aplicativo GUI, que descarta completamente o pyplot, mesmo para a criação de figuras. Consulte a seção correspondente na galeria para obter mais informações: Incorporação do Matplotlib em interfaces gráficas do usuário .)

A documentação e os exemplos do Matplotlib usam os estilos OO e pyplot. Em geral, sugerimos o uso do estilo OO, principalmente para plotagens complicadas e funções e scripts que devem ser reutilizados como parte de um projeto maior. No entanto, o estilo pyplot pode ser muito conveniente para um trabalho interativo rápido.

Observação

Você pode encontrar exemplos mais antigos que usam a pylabinterface, via . Essa abordagem é fortemente obsoleta.from pylab import *

Fazendo funções auxiliares

Se você precisar fazer os mesmos gráficos repetidamente com diferentes conjuntos de dados ou quiser agrupar facilmente os métodos Matplotlib, use a função de assinatura recomendada abaixo.

def my_plotter(ax, data1, data2, param_dict):
    """
    A helper function to make a graph.
    """
    out = ax.plot(data1, data2, **param_dict)
    return out

que você usaria duas vezes para preencher duas subparcelas:

data1, data2, data3, data4 = np.random.randn(4, 100)  # make 4 random data sets
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(5, 2.7))
my_plotter(ax1, data1, data2, {'marker': 'x'})
my_plotter(ax2, data3, data4, {'marker': 'o'});

[<matplotlib.lines.Line2D object at 0x7f2cddab7c10>]

Observe que, se você deseja instalá-los como um pacote python ou qualquer outra personalização, pode usar um dos muitos modelos na web; Matplotlib tem um em mpl-cookiecutter

Artistas de estilo

A maioria dos métodos de plotagem tem opções de estilo para os Artistas, acessíveis quando um método de plotagem é chamado ou de um "configurador" no Artista. No gráfico abaixo, definimos manualmente a cor , a largura da linha e o estilo de linha dos Artistas criados por plote definimos o estilo de linha da segunda linha após o fato com set_linestyle.

fig, ax = plt.subplots(figsize=(5, 2.7))
x = np.arange(len(data1))
ax.plot(x, np.cumsum(data1), color='blue', linewidth=3, linestyle='--')
l, = ax.plot(x, np.cumsum(data2), color='orange', linewidth=2)
l.set_linestyle(':');

Cores

O Matplotlib possui uma variedade muito flexível de cores que são aceitas pela maioria dos Artistas; consulte o tutorial de cores para obter uma lista de especificações. Alguns artistas terão várias cores. ou seja, para um scattergráfico, a borda dos marcadores pode ser de cores diferentes do interior:

fig, ax = plt.subplots(figsize=(5, 2.7))
ax.scatter(data1, data2, s=50, facecolor='C0', edgecolor='k');

<matplotlib.collections.PathCollection object at 0x7f2cddcf8280>

Larguras de linha, estilos de linha e tamanhos de marcadores

Larguras de linha são tipicamente em pontos tipográficos (1 pt = 1/72 polegadas) e disponíveis para Artistas que possuem linhas traçadas. Da mesma forma, as linhas traçadas podem ter um estilo de linha. Veja o exemplo de estilos de linha .

O tamanho do marcador depende do método que está sendo usado. plotespecifica o tamanho do marcador em pontos e geralmente é o "diâmetro" ou a largura do marcador. scatterespecifica o tamanho do marcador como aproximadamente proporcional à área visual do marcador. Há uma variedade de estilos de marcadores disponíveis como códigos de string (consulte Recursos markers) ou os usuários podem definir seus próprios estilos MarkerStyle(consulte Referência de marcadores ):

fig, ax = plt.subplots(figsize=(5, 2.7))
ax.plot(data1, 'o', label='data1')
ax.plot(data2, 'd', label='data2')
ax.plot(data3, 'v', label='data3')
ax.plot(data4, 's', label='data4')
ax.legend();

<matplotlib.legend.Legend object at 0x7f2cfa946650>

Marcando parcelas

Rótulos de eixos e texto

set_xlabel, set_ylabel, e set_titlesão usados ​​para adicionar texto nos locais indicados (consulte Text in Matplotlib Plots para mais discussão). O texto também pode ser adicionado diretamente aos gráficos usando text:

mu, sigma = 115, 15
x = mu + sigma * np.random.randn(10000)
fig, ax = plt.subplots(figsize=(5, 2.7), layout='constrained')
# the histogram of the data
n, bins, patches = ax.hist(x, 50, density=True, facecolor='C0', alpha=0.75)

ax.set_xlabel('Length [cm]')
ax.set_ylabel('Probability')
ax.set_title('Aardvark lengths\n (not really)')
ax.text(75, .025, r'$\mu=115,\ \sigma=15$')
ax.axis([55, 175, 0, 0.03])
ax.grid(True);

Todas as textfunções retornam uma matplotlib.text.Text instância. Assim como nas linhas acima, você pode personalizar as propriedades passando argumentos de palavra-chave para as funções de texto:

t = ax.set_xlabel('my data', fontsize=14, color='red')

Essas propriedades são abordadas com mais detalhes em Propriedades e layout do texto .

Usando expressões matemáticas no texto

Matplotlib aceita expressões de equação TeX em qualquer expressão de texto. Por exemplo, para escrever a expressão\(\sigma_i=15\)no título, você pode escrever uma expressão TeX cercada por cifrões:

ax.set_title(r'$\sigma_i=15$')

onde o rprecedente da string do título significa que a string é uma string bruta e não deve tratar as barras invertidas como escapes de python. O Matplotlib possui um analisador de expressão TeX integrado e um mecanismo de layout, além de fornecer suas próprias fontes matemáticas – para obter detalhes, consulte Escrevendo expressões matemáticas . Você também pode usar LaTeX diretamente para formatar seu texto e incorporar a saída diretamente em suas figuras de exibição ou postscript salvo – consulte Renderização de texto com LaTeX .

Anotações

Também podemos anotar pontos em um gráfico, geralmente conectando uma seta apontando para xy , a um pedaço de texto em xytext :

fig, ax = plt.subplots(figsize=(5, 2.7))

t = np.arange(0.0, 5.0, 0.01)
s = np.cos(2 * np.pi * t)
line, = ax.plot(t, s, lw=2)

ax.annotate('local max', xy=(2, 1), xytext=(3, 1.5),
            arrowprops=dict(facecolor='black', shrink=0.05))

ax.set_ylim(-2, 2);

(-2.0, 2.0)

Neste exemplo básico, xy e xytext estão em coordenadas de dados. Há uma variedade de outros sistemas de coordenadas que podem ser escolhidos -- consulte Anotação básica e Anotações avançadas para obter detalhes. Mais exemplos também podem ser encontrados em Annotating Plots .

Legendas

Frequentemente, queremos identificar linhas ou marcadores com Axes.legend:

fig, ax = plt.subplots(figsize=(5, 2.7))
ax.plot(np.arange(len(data1)), data1, label='data1')
ax.plot(np.arange(len(data2)), data2, label='data2')
ax.plot(np.arange(len(data3)), data3, 'd', label='data3')
ax.legend();

<matplotlib.legend.Legend object at 0x7f2cde2aaa40>

As legendas no Matplotlib são bastante flexíveis em layout, posicionamento e quais artistas elas podem representar. Eles são discutidos em detalhes no guia Legend .

Escalas e escalas do eixo

Cada Axes tem dois (ou três) Axisobjetos que representam os eixos x e y. Estes controlam a escala do Eixo, os localizadores de ticks e os formatadores de ticks . Eixos adicionais podem ser anexados para exibir outros objetos Axis.

Escalas

Além da escala linear, o Matplotlib fornece escalas não lineares, como uma escala logarítmica. Como as escalas logarítmicas são muito usadas, também existem métodos diretos como loglog, semilogxe semilogy. Existem várias escalas (consulte Escalas para outros exemplos). Aqui definimos a escala manualmente:

fig, axs = plt.subplots(1, 2, figsize=(5, 2.7), layout='constrained')
xdata = np.arange(len(data1))  # make an ordinal for this
data = 10**data1
axs[0].plot(xdata, data)

axs[1].set_yscale('log')
axs[1].plot(xdata, data);

[<matplotlib.lines.Line2D object at 0x7f2cde4a5930>]

A escala define o mapeamento dos valores de dados para o espaçamento ao longo do Eixo. Isso acontece em ambas as direções e é combinado em um transform , que é a maneira como o Matplotlib mapeia as coordenadas de dados para eixos, figuras ou coordenadas de tela. Consulte o Tutorial de Transformações .

Localizadores e formatadores de ticks

Cada Axis tem um localizador de escala e um formatador que escolhe onde ao longo dos objetos Axis colocar marcas de escala. Uma interface simples para isso é set_xticks:

fig, axs = plt.subplots(2, 1, layout='constrained')
axs[0].plot(xdata, data1)
axs[0].set_title('Automatic ticks')

axs[1].plot(xdata, data1)
axs[1].set_xticks(np.arange(0, 100, 30), ['zero', '30', 'sixty', '90'])
axs[1].set_yticks([-1.5, 0, 1.5])  # note that we don't need to specify labels
axs[1].set_title('Manual ticks');

Text(0.5, 1.0, 'Manual ticks')

Escalas diferentes podem ter localizadores e formatadores diferentes; por exemplo, a escala logarítmica acima usa LogLocatore LogFormatter. Veja Localizadores de Tick e Formatadores de Tick para outros formatadores e localizadores e informações para escrever o seu próprio.

Plotando datas e strings

O Matplotlib pode manipular matrizes de datas e matrizes de strings, bem como números de ponto flutuante. Eles recebem localizadores e formatadores especiais, conforme apropriado. Para datas:

fig, ax = plt.subplots(figsize=(5, 2.7), layout='constrained')
dates = np.arange(np.datetime64('2021-11-15'), np.datetime64('2021-12-25'),
                  np.timedelta64(1, 'h'))
data = np.cumsum(np.random.randn(len(dates)))
ax.plot(dates, data)
cdf = mpl.dates.ConciseDateFormatter(ax.xaxis.get_major_locator())
ax.xaxis.set_major_formatter(cdf);

Para obter mais informações, consulte os exemplos de data (por exemplo , rótulos de marcação de data )

Para strings, obtemos plotagem categórica (consulte: Plotando variáveis ​​categóricas ).

fig, ax = plt.subplots(figsize=(5, 2.7), layout='constrained')
categories = ['turnips', 'rutabaga', 'cucumber', 'pumpkins']

ax.bar(categories, np.random.rand(len(categories)));

<BarContainer object of 4 artists>

Uma ressalva sobre a plotagem categórica é que alguns métodos de análise de arquivos de texto retornam uma lista de strings, mesmo que todas as strings representem números ou datas. Se você passar 1000 strings, o Matplotlib pensará que você quis dizer 1000 categorias e adicionará 1000 ticks ao seu gráfico!

Objetos Axis adicionais

A plotagem de dados de magnitude diferente em um gráfico pode exigir um eixo y adicional. Tal Axis pode ser criado usando twinxpara adicionar um novo Axes com um eixo x invisível e um eixo y posicionado à direita (analogamente para twiny). Consulte Gráficos com escalas diferentes para outro exemplo.

Da mesma forma, você pode adicionar um secondary_xaxisou secondary_yaxister uma escala diferente do Eixo principal para representar os dados em diferentes escalas ou unidades. Veja Eixo Secundário para mais exemplos.

fig, (ax1, ax3) = plt.subplots(1, 2, figsize=(7, 2.7), layout='constrained')
l1, = ax1.plot(t, s)
ax2 = ax1.twinx()
l2, = ax2.plot(t, range(len(t)), 'C1')
ax2.legend([l1, l2], ['Sine (left)', 'Straight (right)'])

ax3.plot(t, s)
ax3.set_xlabel('Angle [rad]')
ax4 = ax3.secondary_xaxis('top', functions=(np.rad2deg, np.deg2rad))
ax4.set_xlabel('Angle [°]')

Text(0.5, 509.6660000000001, 'Angle [°]')

Dados mapeados por cores

Freqüentemente, queremos ter uma terceira dimensão em um gráfico representado por cores em um mapa de cores. Matplotlib tem vários tipos de gráficos que fazem isso:

X, Y = np.meshgrid(np.linspace(-3, 3, 128), np.linspace(-3, 3, 128))
Z = (1 - X/2 + X**5 + Y**3) * np.exp(-X**2 - Y**2)

fig, axs = plt.subplots(2, 2, layout='constrained')
pc = axs[0, 0].pcolormesh(X, Y, Z, vmin=-1, vmax=1, cmap='RdBu_r')
fig.colorbar(pc, ax=axs[0, 0])
axs[0, 0].set_title('pcolormesh()')

co = axs[0, 1].contourf(X, Y, Z, levels=np.linspace(-1.25, 1.25, 11))
fig.colorbar(co, ax=axs[0, 1])
axs[0, 1].set_title('contourf()')

pc = axs[1, 0].imshow(Z**2 * 100, cmap='plasma',
                          norm=mpl.colors.LogNorm(vmin=0.01, vmax=100))
fig.colorbar(pc, ax=axs[1, 0], extend='both')
axs[1, 0].set_title('imshow() with LogNorm()')

pc = axs[1, 1].scatter(data1, data2, c=data3, cmap='RdBu_r')
fig.colorbar(pc, ax=axs[1, 1], extend='both')
axs[1, 1].set_title('scatter()')

Text(0.5, 1.0, 'scatter()')

Mapas de cores

Todos esses são exemplos de Artistas que derivam de ScalarMappable objetos. Todos eles podem definir um mapeamento linear entre vmin e vmax no mapa de cores especificado por cmap . Matplotlib tem muitos mapas de cores para escolher ( Escolhendo mapas de cores no Matplotlib ), você pode fazer o seu próprio ( Criando mapas de cores no Matplotlib ) ou baixar como pacotes de terceiros .

Normalizações

Às vezes, queremos um mapeamento não linear dos dados para o mapa de cores, como no LogNormexemplo acima. Fazemos isso fornecendo ao ScalarMappable o argumento norm em vez de vmin e vmax . Mais normalizações são mostradas em Colormap Normalization .

Barras de cores

Adicionar um colorbarfornece uma chave para relacionar a cor de volta aos dados subjacentes. Colorbars são artistas em nível de figura e são anexados a um ScalarMappable (onde obtêm suas informações sobre a norma e o mapa de cores) e geralmente roubam espaço de um eixo pai. O posicionamento de barras de cores pode ser complexo: consulte Posicionamento de barras de cores para obter detalhes. Você também pode alterar a aparência das barras de cores com a palavra-chave extend para adicionar setas às extremidades e encolher e aspecto para controlar o tamanho. Por fim, a barra de cores terá localizadores e formatadores padrão adequados à norma. Estes podem ser alterados como para outros objetos Axis.

Trabalhando com várias figuras e eixos

Você pode abrir várias figuras com várias chamadas para ou . Ao manter as referências de objeto, você pode adicionar Artistas a qualquer Figura.fig = plt.figure()fig2, ax = plt.subplots()

Vários eixos podem ser adicionados de várias maneiras, mas a mais básica é plt.subplots()a usada acima. Pode-se obter layouts mais complexos, com objetos Axes abrangendo colunas ou linhas, usando subplot_mosaic.

fig, axd = plt.subplot_mosaic([['upleft', 'right'],
                               ['lowleft', 'right']], layout='constrained')
axd['upleft'].set_title('upleft')
axd['lowleft'].set_title('lowleft')
axd['right'].set_title('right');

Text(0.5, 1.0, 'right')

O Matplotlib possui ferramentas bastante sofisticadas para organizar os eixos: consulte Organizando vários eixos em uma figura e composição de figuras complexas e semânticas .

Mais leitura

Para mais tipos de plotagem, consulte Tipos de plotagem e a referência da API , em particular a API de eixos .