Horizontale und vertikale Linien in Matplotlib zeichnen

Um horizontale und vertikale Referenzlinien in Matplotlib zu zeichnen, verwenden Sie axhline und axvline, wenn sich die Linie über einen Anteil der Achsen erstrecken soll, und hlines und vlines, wenn ihre Endpunkte auf Datenwerten festgelegt werden sollen. Wenn Sie statt eines einzelnen Werts einen ganzen Bereich hervorheben möchten, schattieren axhspan und axvspan die Fläche zwischen zwei Positionen. Jedes Beispiel speichert seine Abbildung in einer temporären PNG-Datei und gibt die Koordinaten des erzeugten Objekts aus, sodass Sie genau überprüfen können, wo Matplotlib die Linie oder das Band platziert hat.

axhline und axvline zum Zeichnen horizontaler und vertikaler Linien in Matplotlib

Mit axhline eine horizontale Linie zeichnen

axhline(y=...) platziert eine horizontale Linie bei y in Datenkoordinaten. Die Argumente xmin und xmax legen den linken und rechten Endpunkt als Anteil der Achsenbreite fest, normalerweise zwischen 0 und 1; es handelt sich dabei nicht um x-Datenwerte. Mit xmin=0.1 und xmax=0.9 bleibt beispielsweise an beiden Enden ein Abstand von 10 % der Achsenbreite.

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)

Ausgabe:

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

Die ausgegebenen Werte bestätigen die Aufteilung: Die Position ist der Datenwert 2, während die Ausdehnung als Achsenanteile 0.1 und 0.9 gespeichert wird.

Die Linie bleibt beim Datenwert y=2. Wenn Sie die x-Grenzen ändern, erstreckt sie sich weiterhin von 10 % bis 90 % der Achsenbreite; das Liniensegment passt sich daher dem angezeigten Bereich an.

Mit axvline eine vertikale Linie zeichnen

axvline(x=...) platziert eine vertikale Linie bei x in Datenkoordinaten. Die Argumente ymin und ymax legen den unteren und oberen Endpunkt als Anteil der Achsenhöhe fest, normalerweise zwischen 0 und 1. Mit ymin=0.1 und ymax=0.9 bleibt beispielsweise an beiden Enden ein Abstand von 10 % der Achsenhöhe.

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)

Ausgabe:

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

Hier sind die gespeicherten Werte vertauscht: Die Position ist der Datenwert 2, und die Ausdehnung ist das Paar der Achsenanteile.

Die Linie bleibt beim Datenwert x=2. Wenn Sie die y-Grenzen ändern, erstreckt sie sich weiterhin von 10 % bis 90 % der Achsenhöhe. Damit kombiniert jede ax*line-Funktion eine Position in Datenkoordinaten mit einer Ausdehnung, die als Anteil der Achsen gemessen wird.

hlines und vlines zum Zeichnen horizontaler und vertikaler Linien in Matplotlib

Verwenden Sie hlines und vlines, wenn die Linienposition und beide Endpunkte Datenkoordinaten verwenden sollen. Bei hlines gibt y die Höhe an und xmin und xmax geben die x-Werte der Endpunkte an. Bei vlines gibt x die Position an und ymin und ymax geben die y-Werte der Endpunkte an. Wenn Sie die Diagrammgrenzen ändern, ändert sich, welche Teile sichtbar sind, während Position und Endpunkte der Linie in Datenkoordinaten fest bleiben. Beide Funktionen geben eine LineCollection zurück und akzeptieren die üblichen Stilargumente, daher setzt dieses Beispiel auch gestrichelte und gepunktete Stile und fügt über das Argument label eine Legende hinzu.

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)

Ausgabe:

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

Die ausgegebenen Endpunkte sind reine Datenkoordinaten: Das horizontale Segment verläuft von (1, 2) nach (3, 2), und das vertikale Segment verläuft von (2, 1) nach (2, 3).

Da alle vier Endpunkte Datenkoordinaten verwenden, ändert das Zoomen oder Ändern der Grenzen den sichtbaren Teil jedes Segments, anstatt seine Endpunkte an einen Anteil der Achsen anzupassen.

Mit axhspan und axvspan einen Bereich in Matplotlib schattieren

Wenn eine einzelne Linie nicht ausreicht, schattieren Sie stattdessen den Bereich zwischen zwei Werten. axhspan(ymin, ymax) füllt ein horizontales Band zwischen zwei y-Datenwerten über die gesamte Breite der Achsen, und axvspan(xmin, xmax) füllt ein vertikales Band zwischen zwei x-Datenwerten über die gesamte Höhe. Verwenden Sie sie, um einen zulässigen Bereich, eine Zielzone oder einen interessierenden Zeitraum hinter Ihren Daten zu markieren. Beide Funktionen geben ein Rectangle-Patch zurück.

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)

Ausgabe:

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

Die Bandkanten verwenden immer Datenkoordinaten. Wie axhline akzeptieren auch die Span-Funktionen Anteilsargumente für die Querrichtung — axhspan nimmt xmin und xmax als Achsenanteile, um die Breite des Bandes zu begrenzen, und axvspan nimmt ymin und ymax — aber ein so gezeichnetes Band beginnt und endet trotzdem bei Datenwerten.

Warum eine horizontale oder vertikale Linie in Matplotlib möglicherweise nicht erscheint

Zwei Prüfungen erklären fast jeden Bericht über eine fehlende Linie. Die erste ist ein Typfehler: Die Anteilsargumente von axhline und axvline müssen Zahlen sein. Wenn Sie sie als Zeichenketten übergeben — ein häufiger Unfall, wenn die Werte aus einem Formular, einer CSV-Datei oder einem Konfigurationseintrag stammen — wird ein ValueError ausgelöst, bevor irgendetwas gezeichnet wird:

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)

Ausgabe:

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

Wandeln Sie die Werte zuerst in Zahlen um, zum Beispiel mit float(...), und derselbe Aufruf gelingt — das erste Beispiel in diesem Artikel ist genau dieser Aufruf mit numerischen Anteilen.

Die zweite Prüfung ist der sichtbare Bereich. Eine Linie wird in Datenkoordinaten erzeugt, auch wenn ihre Position außerhalb der aktuellen Achsengrenzen liegt; sie existiert also in der Abbildung, wird aber aus der Ansicht herausgeschnitten:

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)

Ausgabe:

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

Die Linie liegt bei y=20, während die Achsen bei 4.0 enden. Erweitern Sie die Grenzen so, dass sie die Position einschließen — oder korrigieren Sie den Wert, falls 20 ein Fehler war — und die Linie erscheint. Dieselbe Prüfung gilt für die Endpunkte von hlines und vlines sowie für Bandkanten von Spans, die außerhalb der Grenzen fallen.

Fazit zum Zeichnen horizontaler und vertikaler Linien in Matplotlib

Wählen Sie axhline oder axvline, wenn die Position ein Datenwert ist, die Ausdehnung der Linie aber einem Anteil der Achsen folgen soll. Wählen Sie hlines oder vlines, wenn die Position und beide Endpunkte bei Datenwerten bleiben sollen, und verwenden Sie axhspan oder axvspan, wenn statt einer einzelnen Linie ein ganzes Band zwischen zwei Werten hervorgehoben werden soll. Diese Koordinatenwahl bestimmt, wie viel von einer Linie sichtbar ist, nachdem Sie die Diagrammgrenzen ändern — und der Vergleich der gespeicherten Koordinaten mit den Achsengrenzen erklärt jede Linie, die zu fehlen scheint.