Comment tracer des lignes horizontales et verticales dans Matplotlib

Pour tracer des lignes de référence horizontales et verticales dans Matplotlib, choisissez axhline et axvline lorsque la ligne doit couvrir une fraction des axes, ou hlines et vlines lorsque ses extrémités doivent être fixées à des valeurs de données. Lorsque l’objectif est de mettre en évidence une bande entière plutôt qu’une seule valeur, axhspan et axvspan ombrent la région entre deux positions. Chaque exemple enregistre sa figure dans un fichier PNG temporaire et affiche les coordonnées de l’objet qu’il crée, afin que vous puissiez confirmer exactement où Matplotlib a placé la ligne ou la bande.

axhline et axvline pour tracer des lignes horizontales et verticales dans Matplotlib

axhline pour tracer une ligne horizontale

axhline(y=...) place une ligne horizontale à y en coordonnées de données. Ses arguments xmin et xmax définissent les extrémités gauche et droite comme des fractions de la largeur des axes, normalement de 0 à 1 ; ce ne sont pas des valeurs de données x. Par exemple, xmin=0.1 et xmax=0.9 laissent une marge égale à 10 % de la largeur des axes à chaque extrémité.

import tempfile
from pathlib import Path

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([0, 2, 4], [1, 3, 2], marker="o")
line = ax.axhline(y=2, xmin=0.1, xmax=0.9, color="tab:red")
ax.set(xlim=(0, 4), ylim=(0, 4), xlabel="x", ylabel="y")
ax.grid(True)
print("x extent (axes fraction):", line.get_xdata())
print("y position (data):", line.get_ydata())
with tempfile.TemporaryDirectory() as directory:
    fig.savefig(Path(directory) / "plot.png")
plt.close(fig)

Sortie:

x extent (axes fraction): [0.1, 0.9]
y position (data): [2, 2]

Les valeurs affichées confirment la répartition : la position est la valeur de données 2, tandis que l’étendue est stockée sous forme des fractions d’axes 0.1 et 0.9.

La ligne reste à la valeur de données y=2. Si vous modifiez les limites de x, ses extrémités couvrent toujours de 10 % à 90 % de la largeur des axes, de sorte que le segment s’ajuste à la plage affichée.

axvline pour tracer une ligne verticale

axvline(x=...) place une ligne verticale à x en coordonnées de données. Ses arguments ymin et ymax définissent les extrémités inférieure et supérieure comme des fractions de la hauteur des axes, normalement de 0 à 1. Par exemple, ymin=0.1 et ymax=0.9 laissent une marge égale à 10 % de la hauteur des axes à chaque extrémité.

import tempfile
from pathlib import Path

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([0, 2, 4], [1, 3, 2], marker="o")
line = ax.axvline(x=2, ymin=0.1, ymax=0.9, color="tab:green")
ax.set(xlim=(0, 4), ylim=(0, 4), xlabel="x", ylabel="y")
ax.grid(True)
print("x position (data):", line.get_xdata())
print("y extent (axes fraction):", line.get_ydata())
with tempfile.TemporaryDirectory() as directory:
    fig.savefig(Path(directory) / "plot.png")
plt.close(fig)

Sortie:

x position (data): [2, 2]
y extent (axes fraction): [0.1, 0.9]

Ici, les valeurs stockées sont inversées : la position est la valeur de données 2, et l’étendue est la paire de fractions d’axes.

La ligne reste à la valeur de données x=2. Si vous modifiez les limites de y, ses extrémités couvrent toujours de 10 % à 90 % de la hauteur des axes. Ainsi, chaque fonction ax*line combine une position en coordonnées de données avec une étendue mesurée comme une fraction des axes.

hlines et vlines pour tracer des lignes horizontales et verticales dans Matplotlib

Utilisez hlines et vlines lorsque la position de la ligne et ses deux extrémités doivent utiliser des coordonnées de données. Pour hlines, y donne la hauteur et xmin et xmax donnent les valeurs x des extrémités. Pour vlines, x donne la position et ymin et ymax donnent les valeurs y des extrémités. Modifier les limites du graphique change les portions visibles, tandis que la position et les extrémités de la ligne en coordonnées de données restent fixes. Les deux fonctions renvoient une LineCollection et acceptent les arguments de style habituels, donc cet exemple définit aussi des styles en tirets et en pointillés et ajoute une légende grâce à l’argument label.

import tempfile
from pathlib import Path

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([0, 2, 4], [1, 3, 2], marker="o")
horizontal = ax.hlines(y=2, xmin=1, xmax=3, color="tab:red", linestyles="--",
                       linewidth=2, label="horizontal segment")
vertical = ax.vlines(x=2, ymin=1, ymax=3, color="tab:green", linestyles=":",
                     linewidth=2, label="vertical segment")
ax.set(xlim=(0, 4), ylim=(0, 4), xlabel="x", ylabel="y")
ax.grid(True)
ax.legend(loc="upper left")
print("horizontal segment endpoints:", horizontal.get_segments()[0].tolist())
print("vertical segment endpoints:", vertical.get_segments()[0].tolist())
with tempfile.TemporaryDirectory() as directory:
    fig.savefig(Path(directory) / "plot.png")
plt.close(fig)

Sortie:

horizontal segment endpoints: [[1.0, 2.0], [3.0, 2.0]]
vertical segment endpoints: [[2.0, 1.0], [2.0, 3.0]]

Les extrémités affichées sont des coordonnées de données pures : le segment horizontal va de (1, 2) à (3, 2), et le segment vertical va de (2, 1) à (2, 3).

Comme les quatre extrémités utilisent des coordonnées de données, zoomer ou modifier les limites change la portion visible de chaque segment au lieu de redimensionner ses extrémités pour correspondre à une fraction des axes.

axhspan et axvspan pour ombrer une région dans Matplotlib

Lorsqu’une seule ligne ne suffit pas, ombrez plutôt la région entre deux valeurs. axhspan(ymin, ymax) remplit une bande horizontale entre deux valeurs de données y sur toute la largeur des axes, et axvspan(xmin, xmax) remplit une bande verticale entre deux valeurs de données x sur toute la hauteur. Utilisez-les pour marquer une plage acceptable, une zone cible ou une période d’intérêt derrière vos données. Les deux fonctions renvoient un patch Rectangle.

import tempfile
from pathlib import Path

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([0, 2, 4], [1, 3, 2], marker="o")
band_y = ax.axhspan(ymin=1.5, ymax=2.5, color="tab:orange", alpha=0.3,
                    label="y between 1.5 and 2.5")
band_x = ax.axvspan(xmin=1.5, xmax=2.5, color="tab:blue", alpha=0.15,
                    label="x between 1.5 and 2.5")
ax.set(xlim=(0, 4), ylim=(0, 4), xlabel="x", ylabel="y")
ax.grid(True)
ax.legend(loc="upper left")
print("horizontal band y range:", band_y.get_y(), "to", band_y.get_y() + band_y.get_height())
print("vertical band x range:", band_x.get_x(), "to", band_x.get_x() + band_x.get_width())
with tempfile.TemporaryDirectory() as directory:
    fig.savefig(Path(directory) / "plot.png")
plt.close(fig)

Sortie:

horizontal band y range: 1.5 to 2.5
vertical band x range: 1.5 to 2.5

Les bords de la bande utilisent toujours des coordonnées de données. Comme axhline, les fonctions span acceptent aussi des arguments de fraction pour la direction transversale — axhspan prend xmin et xmax comme fractions d’axes pour limiter la largeur de la bande, et axvspan prend ymin et ymax — mais une bande dessinée ainsi commence et se termine toujours à des valeurs de données.

Pourquoi une ligne horizontale ou verticale peut ne pas apparaître dans Matplotlib

Deux vérifications expliquent presque tous les signalements de ligne manquante. La première est une erreur de type : les arguments de fraction de axhline et axvline doivent être des nombres. Les transmettre sous forme de chaînes — un accident fréquent lorsque les valeurs proviennent d’un formulaire, d’un fichier CSV ou d’une entrée de configuration — lève une ValueError avant que quoi que ce soit soit dessiné :

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([0, 2, 4], [1, 3, 2], marker="o")
ax.axhline(y=2, xmin="0.1", xmax="0.9", color="tab:red")
plt.close(fig)

Sortie:

ValueError: xmin must be a single scalar value, but got 0.1

Convertissez d’abord les valeurs en nombres, par exemple avec float(...), et le même appel réussit — le premier exemple de cet article est exactement cet appel avec des fractions numériques.

La deuxième vérification est la plage visible. Une ligne est créée en coordonnées de données même lorsque sa position se trouve hors des limites actuelles des axes, donc elle existe dans la figure mais est rognée de la vue :

import tempfile
from pathlib import Path

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([0, 2, 4], [1, 3, 2], marker="o")
line = ax.axhline(y=20, color="tab:red")
ax.set(xlim=(0, 4), ylim=(0, 4), xlabel="x", ylabel="y")
ax.grid(True)
print("line y position:", line.get_ydata())
print("axes y limits:", tuple(float(v) for v in ax.get_ylim()))
with tempfile.TemporaryDirectory() as directory:
    fig.savefig(Path(directory) / "plot.png")
plt.close(fig)

Sortie:

line y position: [20, 20]
axes y limits: (0.0, 4.0)

La ligne se trouve à y=20 alors que les axes s’arrêtent à 4.0. Étendez les limites pour inclure la position — ou corrigez la valeur si 20 était une erreur — et la ligne apparaît. La même vérification s’applique aux extrémités de hlines et vlines ainsi qu’aux bords de span qui tombent hors des limites.

Conclusion sur le tracé des lignes horizontales et verticales dans Matplotlib

Choisissez axhline ou axvline lorsque la position est une valeur de données mais que l’étendue de la ligne doit suivre une fraction des axes. Choisissez hlines ou vlines lorsque la position et les deux extrémités doivent rester à des valeurs de données, et utilisez axhspan ou axvspan lorsqu’une bande entière entre deux valeurs doit être mise en évidence au lieu d’une seule ligne. Ce choix de coordonnées détermine quelle partie d’une ligne reste visible après la modification des limites du graphique — et comparer les coordonnées stockées aux limites des axes explique toute ligne qui semble manquer.