Guide de démarrage rapide

Ce didacticiel couvre certains modèles d'utilisation de base et les meilleures pratiques pour vous aider à démarrer avec Matplotlib.

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

Un exemple simple

Matplotlib représente graphiquement vos données sur des Figures (par exemple, des fenêtres, des widgets Jupyter, etc.), chacun pouvant contenir un ou plusieurs Axes, une zone où les points peuvent être spécifiés en termes de coordonnées xy (ou theta-r dans un tracé polaire, xyz dans un tracé 3D, etc.). La façon la plus simple de créer une figure avec des axes est d'utiliser pyplot.subplots. On peut alors utiliser Axes.plotpour tracer quelques données sur les Axes :

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

Parties d'une figure

Voici les composants d'une figure Matplotlib.

Figure

Le chiffre entier . La figure garde une trace de tous les enfants Axes, d'un groupe d'artistes "spéciaux" (titres, légendes des figures, barres de couleurs, etc.) et même de sous-figures imbriquées.

Le moyen le plus simple de créer une nouvelle figure est avec 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

Il est souvent pratique de créer les Axes avec la Figure, mais vous pouvez également ajouter manuellement des Axes ultérieurement. Notez que de nombreux backends Matplotlib prennent en charge le zoom et le panoramique sur les fenêtres de figure.

Axes

Un axe est un artiste attaché à une figure qui contient une région pour tracer des données et comprend généralement deux (ou trois dans le cas de la 3D) Axisobjets (attention à la différence entre Axes et Axis ) qui fournissent des graduations et des étiquettes de graduation pour fournir échelles pour les données dans les Axes. Chacun Axesa également un titre (défini via set_title()), une étiquette x (définie via set_xlabel()) et une étiquette y définie via set_ylabel()).

La Axesclasse et ses fonctions membres sont le point d'entrée principal pour travailler avec l'interface OOP, et ont la plupart des méthodes de traçage définies dessus (par exemple ax.plot(), montré ci-dessus, utilise la plotméthode)

Axis

Ces objets définissent l'échelle et les limites et génèrent des ticks (les repères sur l'axe) et des ticklabels (chaînes étiquetant les ticks). L'emplacement des ticks est déterminé par un Locatorobjet et les chaînes ticklabel sont formatées par un Formatter. La combinaison du correct Locatoret Formatterdonne un contrôle très fin sur les emplacements et les étiquettes des ticks.

Artist

Fondamentalement, tout ce qui est visible sur la figure est un artiste (même Figure, Axeset Axisobjets). Cela inclut les Textobjets, Line2Dles objets, collectionsles objets, les Patch objets, etc. Lorsque la figure est rendue, tous les artistes sont attirés sur la toile . La plupart des artistes sont liés à des haches ; un tel Artiste ne peut pas être partagé par plusieurs Axes, ou déplacé de l'un à l'autre.

Types d'entrées aux fonctions de traçage

Les fonctions de traçage attendent numpy.arrayou numpy.ma.masked_arraycomme entrée, ou des objets qui peuvent être passés à numpy.asarray. Les classes qui sont similaires aux tableaux (« de type tableau ») telles que pandas les objets de données et numpy.matrixpeuvent ne pas fonctionner comme prévu. La convention courante consiste à les convertir en numpy.arrayobjets avant de tracer. Par exemple, pour convertir unnumpy.matrix

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

La plupart des méthodes analyseront également un objet adressable comme un dict , un numpy.recarrayou un pandas.DataFrame. Matplotlib vous permet de fournir l' dataargument du mot-clé et de générer des tracés passant les chaînes correspondant aux variables x et 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')

Styles de codage

Les interfaces explicites et implicites

Comme indiqué ci-dessus, il existe essentiellement deux façons d'utiliser Matplotlib :

• Créez explicitement des figures et des axes et appelez des méthodes dessus (le "style orienté objet (OO)").

• Comptez sur pyplot pour créer et gérer implicitement les figures et les axes, et utilisez les fonctions pyplot pour le traçage.

Voir Matplotlib Application Interfaces (APIs) pour une explication des compromis entre les interfaces implicites et explicites.

On peut donc utiliser le style 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 le style 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>

(De plus, il existe une troisième approche, pour le cas de l'intégration de Matplotlib dans une application graphique, qui supprime complètement pyplot, même pour la création de figures. Voir la section correspondante dans la galerie pour plus d'informations : Intégration de Matplotlib dans les interfaces utilisateur graphiques .)

La documentation et les exemples de Matplotlib utilisent à la fois les styles OO et pyplot. En général, nous suggérons d'utiliser le style OO, en particulier pour les tracés complexes, ainsi que les fonctions et les scripts destinés à être réutilisés dans le cadre d'un projet plus vaste. Cependant, le style pyplot peut être très pratique pour un travail interactif rapide.

Noter

Vous pouvez trouver des exemples plus anciens qui utilisent l' pylabinterface, via . Cette approche est fortement déconseillée.from pylab import *

Création d'une fonction d'assistance

Si vous devez créer les mêmes tracés encore et encore avec différents ensembles de données, ou si vous souhaitez envelopper facilement les méthodes Matplotlib, utilisez la fonction de signature recommandée ci-dessous.

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 vous utiliseriez ensuite deux fois pour remplir deux sous-parcelles :

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

Notez que si vous souhaitez les installer en tant que package python, ou toute autre personnalisation, vous pouvez utiliser l'un des nombreux modèles sur le Web ; Matplotlib en a un chez mpl-cookiecutter

Artistes Stylistes

La plupart des méthodes de traçage ont des options de style pour les artistes, accessibles soit lorsqu'une méthode de traçage est appelée, soit à partir d'un « régleur » sur l'artiste. Dans le tracé ci-dessous, nous définissons manuellement la couleur , la largeur de ligne et le style de ligne des artistes créés par plot, et nous définissons le style de ligne de la deuxième ligne après coup avec 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(':');

Couleurs

Matplotlib a une gamme très flexible de couleurs qui sont acceptées pour la plupart des artistes ; voir le tutoriel sur les couleurs pour une liste des spécifications. Certains artistes prendront plusieurs couleurs. c'est-à-dire pour une scatterparcelle, le bord des marqueurs peut être de couleurs différentes de l'intérieur :

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

<matplotlib.collections.PathCollection object at 0x7f2cddcf8280>

Largeurs de ligne, styles de ligne et tailles de marqueur

Les largeurs de ligne sont généralement exprimées en points typographiques (1 pt = 1/72 pouce) et disponibles pour les artistes qui ont tracé des lignes. De même, les lignes tracées peuvent avoir un style de ligne. Voir l' exemple de styles de ligne .

La taille du marqueur dépend de la méthode utilisée. plotspécifie la taille du marqueur en points et correspond généralement au "diamètre" ou à la largeur du marqueur. scatterspécifie la taille du marqueur comme étant approximativement proportionnelle à la zone visuelle du marqueur. Il existe un tableau de styles de marqueurs disponibles sous forme de codes de chaîne (voir markers), ou les utilisateurs peuvent définir les leurs MarkerStyle(voir Référence des marqueurs ) :

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>

Étiquetage des parcelles

Étiquettes et texte des axes

set_xlabel, set_ylabelet set_titlesont utilisés pour ajouter du texte aux emplacements indiqués (voir Texte dans les tracés Matplotlib pour plus de détails). Le texte peut également être directement ajouté aux tracés à l'aide de 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);

Toutes les textfonctions renvoient une matplotlib.text.Text instance. Tout comme avec les lignes ci-dessus, vous pouvez personnaliser les propriétés en passant des arguments de mots-clés dans les fonctions de texte :

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

Ces propriétés sont décrites plus en détail dans Propriétés et disposition du texte .

Utilisation d'expressions mathématiques dans le texte

Matplotlib accepte les expressions d'équation TeX dans n'importe quelle expression de texte. Par exemple pour écrire l'expression\(\sigma_i=15\)dans le titre, vous pouvez écrire une expression TeX entourée de signes dollar :

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

où la rchaîne de titre qui précède signifie que la chaîne est une chaîne brute et qu'il ne faut pas traiter les barres obliques inverses comme des échappements python. Matplotlib possède un analyseur d'expressions et un moteur de mise en page TeX intégrés, et fournit ses propres polices mathématiques - pour plus de détails, voir Écrire des expressions mathématiques . Vous pouvez également utiliser LaTeX directement pour formater votre texte et incorporer la sortie directement dans vos figures d'affichage ou votre postscript enregistré - voir Rendu de texte avec LaTeX .

Annotation

Nous pouvons également annoter des points sur un tracé, souvent en reliant une flèche pointant vers xy , à un morceau de texte à 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)

Dans cet exemple de base, xy et xytext sont en coordonnées de données. Il existe une variété d'autres systèmes de coordonnées que l'on peut choisir - voir Annotation de base et Annotations avancées pour plus de détails. D'autres exemples peuvent également être trouvés dans Annotation de tracés .

Légendes

Souvent, nous voulons identifier des lignes ou des marqueurs avec un 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>

Les légendes dans Matplotlib sont assez flexibles dans la disposition, le placement et les artistes qu'elles peuvent représenter. Ils sont discutés en détail dans le guide Légende .

Échelles et graduations d'axe

Chaque Axe a deux (ou trois) Axisobjets représentant les axes x et y. Ceux-ci contrôlent l' échelle de l'Axe, les localisateurs de ticks et les formateurs de ticks . Des axes supplémentaires peuvent être attachés pour afficher d'autres objets Axis.

Échelles

En plus de l'échelle linéaire, Matplotlib fournit des échelles non linéaires, comme une échelle logarithmique. Étant donné que les échelles logarithmiques sont tellement utilisées, il existe également des méthodes directes telles que loglog, semilogxet semilogy. Il existe plusieurs échelles (voir Échelles pour d'autres exemples). Ici, nous définissons l'échelle manuellement :

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

L'échelle définit le mappage des valeurs de données à l'espacement le long de l'axe. Cela se produit dans les deux sens et est combiné dans un transform , qui est la façon dont Matplotlib mappe les coordonnées des données aux axes, à la figure ou aux coordonnées de l'écran. Voir Tutoriel sur les transformations .

Tick ​​localisateurs et formateurs

Chaque axe a un localisateur de graduation et un formateur qui choisissent où le long des objets de l'axe placer des graduations. Une interface simple pour ceci est 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')

Différentes échelles peuvent avoir différents localisateurs et formateurs ; par exemple, l'échelle logarithmique ci-dessus utilise LogLocatoret LogFormatter. Voir Localisateurs de ticks et formateurs de ticks pour d'autres formateurs et localisateurs et des informations pour écrire les vôtres.

Traçage des dates et des chaînes

Matplotlib peut gérer le traçage de tableaux de dates et de tableaux de chaînes, ainsi que de nombres à virgule flottante. Ceux-ci obtiennent des localisateurs et des formateurs spéciaux, le cas échéant. Pour les dates :

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

Pour plus d'informations, voir les exemples de date (par exemple , étiquettes de coche de date )

Pour les chaînes, nous obtenons un tracé catégoriel (voir : Tracé des variables catégorielles ).

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>

Une mise en garde concernant le traçage catégoriel est que certaines méthodes d'analyse de fichiers texte renvoient une liste de chaînes, même si les chaînes représentent toutes des nombres ou des dates. Si vous passez 1000 chaînes, Matplotlib pensera que vous vouliez dire 1000 catégories et ajoutera 1000 ticks à votre tracé !

Objets Axe supplémentaires

Le traçage de données de magnitude différente dans un graphique peut nécessiter un axe y supplémentaire. Un tel Axe peut être créé en utilisant twinxpour ajouter un nouvel Axe avec un axe x invisible et un axe y positionné à droite (analogiquement pour twiny). Voir Tracés à différentes échelles pour un autre exemple.

De même, vous pouvez ajouter un secondary_xaxisou secondary_yaxisayant une échelle différente de l'axe principal pour représenter les données dans différentes échelles ou unités. Voir Axe secondaire pour d'autres exemples.

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 [°]')

Données mappées en couleur

Souvent, nous voulons avoir une troisième dimension dans un tracé représenté par des couleurs dans une palette de couleurs. Matplotlib a un certain nombre de types de tracés qui font cela :

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

Palettes de couleurs

Ce sont tous des exemples d'artistes qui dérivent d' ScalarMappable objets. Ils peuvent tous définir un mappage linéaire entre vmin et vmax dans la palette de couleurs spécifiée par cmap . Matplotlib propose de nombreuses palettes de couleurs ( Choisir des palettes de couleurs dans Matplotlib ) que vous pouvez créer vous-même ( Créer des palettes de couleurs dans Matplotlib ) ou télécharger en tant que packages tiers .

Normalisations

Parfois, nous voulons un mappage non linéaire des données sur la palette de couleurs, comme dans l' LogNormexemple ci-dessus. Pour ce faire, nous fournissons à ScalarMappable l' argument norm au lieu de vmin et vmax . D'autres normalisations sont affichées dans Colormap Normalization .

Barres de couleur

L'ajout d'un colorbardonne une clé pour relier la couleur aux données sous-jacentes. Les barres de couleurs sont des artistes au niveau de la figure et sont attachées à un ScalarMappable (où elles obtiennent leurs informations sur la norme et la palette de couleurs) et volent généralement de l'espace à un parent Axes. Le placement des barres de couleurs peut être complexe : voir Placer les barres de couleurs pour plus de détails. Vous pouvez également modifier l'apparence des barres de couleurs avec le mot-clé extend pour ajouter des flèches aux extrémités, et réduire et aspect pour contrôler la taille. Enfin, la barre de couleurs aura des localisateurs et des formateurs par défaut appropriés à la norme. Ceux-ci peuvent être modifiés comme pour les autres objets Axis.

Travailler avec plusieurs figures et axes

Vous pouvez ouvrir plusieurs figures avec plusieurs appels à ou . En conservant les références d'objet, vous pouvez ajouter des artistes à l'une ou l'autre figure.fig = plt.figure()fig2, ax = plt.subplots()

Plusieurs haches peuvent être ajoutées de plusieurs façons, mais la plus basique est plt.subplots()celle utilisée ci-dessus. On peut obtenir des mises en page plus complexes, avec des objets Axes couvrant des colonnes ou des lignes, en utilisant 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')

Matplotlib dispose d'outils assez sophistiqués pour organiser les Axes : Voir Arranger plusieurs Axes dans une Figure et Composition de figures complexes et sémantiques .

Plus de lecture

Pour plus de types de tracés, voir Types de tracés et la référence de l'API , en particulier l' API Axes .