Matplotlib Pyplot

matplotlib.pyplot est une collection de fonctions qui permettent à Matplotlib de se comporter comme le système de tracé de MATLAB. Chaque fonction crée ou modifie un élément d'une figure — ajout d'axes, tracé d'une ligne, définition d'un titre — et pyplot garde automatiquement une trace de la figure et des axes « courants », de sorte que vous n'avez pas à faire circuler des objets. Cette page explique comment ce modèle à état fonctionne, passe en revue les fonctions pyplot les plus importantes et montre quand basculer vers l'API orientée objet explicite.

Qu'est-ce que matplotlib.pyplot ?

Matplotlib propose deux interfaces principales :

Les deux interfaces appartiennent à la même bibliothèque. pyplot est une couche de commodité — chaque appel plt.quelquechose() manipule en fin de compte les mêmes objets Figure et Axes qu'expose directement l'interface OO. Comprendre cette relation vous permet de mélanger les deux styles en toute confiance.

L'alias standard est plt :

import matplotlib.pyplot as plt

Comment fonctionne l'interface à état

pyplot conserve une référence interne à la figure courante et aux axes courants. Lorsque vous appelez plt.plot(), Matplotlib :

1. Vérifie si une figure existe déjà ; si non, en crée une.
2. Vérifie si cette figure possède des axes ; si non, ajoute un seul Axes pour remplir la figure.
3. Trace les données sur ces axes.

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

La figure et les axes ont été créés implicitement. C'est pratique pour les graphiques ponctuels, mais cela peut provoquer des surprises lorsque vous exécutez plusieurs graphiques dans le même script. Utilisez plt.figure() et plt.clf() (effacer la figure) ou plt.close() pour contrôler l'état explicitement.

Fonctions pyplot essentielles

plt.plot() — Tracer des lignes et des marqueurs

plt.plot(x, y) est la fonction de base. Elle trace des lignes, des marqueurs, ou les deux.

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

Paramètres clés de plt.plot() :

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

Étiquetez les axes et ajoutez un titre. Les trois acceptent un argument 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()

Lorsque vous passez label= à un appel de tracé, plt.legend() transforme ces étiquettes en une boîte sur le graphique :

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

Contrôlez le positionnement de la légende avec le paramètre loc : "upper left", "lower right", "best" (par défaut), etc.

plt.grid()

plt.grid(True) ajoute des lignes de grille. Utilisez axis="x" ou axis="y" pour restreindre à un seul axe, et passez linestyle / alpha pour styliser les lignes :

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

plt.xlim() et plt.ylim()

Définissez la plage visible sur chaque axe :

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() et plt.yticks()

Contrôlez les graduations affichées et leurs étiquettes :

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

Créez une nouvelle figure explicitement. C'est important dans les scripts qui produisent plusieurs graphiques séparés :

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 contrôle la taille de sortie. Une figure plus large (par ex. (12, 4)) convient aux données de séries temporelles ; une figure carrée convient aux nuages de points.

plt.savefig()

Enregistrez la figure courante dans un fichier au lieu de (ou en plus de) l'afficher :

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

Les formats pris en charge incluent png, pdf, svg et jpg. bbox_inches="tight" rogne les espaces blancs superflus autour de la figure. Appelez savefig() avant show() — show() réinitialise l'état de la figure dans certains backends.

plt.close() et plt.clf()

Dans une boucle qui produit de nombreuses figures, fermez toujours les figures dont vous avez terminé l'utilisation pour libérer de la mémoire :

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

Sous-graphiques via pyplot

plt.subplots() est le pont entre les interfaces pyplot et OO. Il crée un objet Figure et un ou plusieurs objets Axes, puis retourne les deux :

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() ajuste automatiquement l'espacement entre les panneaux pour éviter le chevauchement des titres et des étiquettes.

pyplot vs. l'API orientée objet

Dès que vous dépassez un seul ensemble d'axes, l'API à état devient plus difficile à appréhender. Utilisez l'API OO (via fig, ax = plt.subplots()) lorsque :

• Vous avez plus d'un sous-graphique.
• Vous écrivez une fonction qui crée et retourne un graphique.
• Vous avez besoin d'un contrôle précis sur les formateurs de graduations, les axes secondaires ou les axes insérés.

Le schéma est simple : la plupart des fonctions plt.quelquechose() ont un équivalent ax.set_quelquechose() sur l'objet Axes.

Un exemple complet

Le script suivant combine les fonctions pyplot les plus courantes en un exemple autonome et exécutable :

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

Cet exemple montre les deux séries sur les mêmes axes, une légende, une grille, des étiquettes de graduations x personnalisées, et enregistre le résultat dans un fichier PNG.

Pièges courants

Oublier plt.show() — dans un script Python ordinaire (pas Jupyter), la fenêtre du graphique ne s'ouvre jamais sans cet appel. Dans Jupyter, %matplotlib inline rend cela automatique.

Appeler plt.savefig() après plt.show() — show() finalise et réinitialise la figure. Enregistrez d'abord, puis affichez :

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

Accumulation de plusieurs figures — dans une boucle, chaque appel plt.figure() crée une nouvelle figure qui reste en mémoire jusqu'à ce que vous appeliez plt.close(). Fermez les figures dont vous n'avez plus besoin.

Mélanger les styles pyplot et OO de manière incohérente — il est acceptable d'utiliser les deux, mais soyez délibéré : récupérez l'objet Axes et travaillez directement avec lui plutôt que de vous fier aux « axes courants » implicites de pyplot lorsque vous avez plus d'un ensemble d'axes.

Étapes suivantes

• Graphiques en lignes Matplotlib — styles de lignes, séries multiples et zones remplies en détail.
• Marqueurs Matplotlib — toutes les formes de marqueurs intégrés et comment les styliser.
• Étiquettes Matplotlib — titres, étiquettes d'axes, annotations et positionnement du texte.
• Grille Matplotlib — styles de lignes de grille, graduations mineures et stylisation de l'arrière-plan.
• Barres Matplotlib — graphiques à barres verticaux, horizontaux, empilés et groupés.
• Nuages de points Matplotlib — nuages de points avec palettes de couleurs et encodage de taille.
• Histogrammes Matplotlib — contrôle des intervalles, courbes de densité et distributions superposées.
• Sous-graphiques Matplotlib — dispositions multi-panneaux avec subplots() et GridSpec.