HOWTO · Matplotlib
Come tracciare linee orizzontali e verticali in Matplotlib
Questo tutorial presenta come tracciare linee orizzontali e verticali in Matplotlib con axhline e axvline, hlines e vlines, e le funzioni di ombreggiatura axhspan e axvspan.
In questa pagina
Per tracciare linee di riferimento orizzontali e verticali in Matplotlib, scegli axhline e axvline quando la linea deve coprire una frazione degli assi, oppure hlines e vlines quando i suoi estremi devono essere fissati a valori dei dati. Quando l’obiettivo è evidenziare un’intera banda anziché un singolo valore, axhspan e axvspan ombreggiano la regione tra due posizioni. Ogni esempio salva la figura in un file PNG temporaneo e stampa le coordinate dell’oggetto che crea, così puoi verificare esattamente dove Matplotlib ha posizionato la linea o la banda.
axhline e axvline per tracciare linee orizzontali e verticali in Matplotlib
axhline per tracciare una linea orizzontale
axhline(y=...) posiziona una linea orizzontale in corrispondenza di y nelle coordinate dei dati. I suoi argomenti xmin e xmax impostano gli estremi sinistro e destro come frazioni della larghezza degli assi, normalmente da 0 a 1; non sono valori di dati x. Ad esempio, xmin=0.1 e xmax=0.9 lasciano un margine pari al 10 % della larghezza degli assi a ciascun estremo.
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)
Produzione:
x extent (axes fraction): [0.1, 0.9]
y position (data): [2, 2]
I valori stampati confermano la ripartizione: la posizione è il valore dei dati 2, mentre l’estensione è memorizzata come le frazioni degli assi 0.1 e 0.9.
La linea rimane al valore dei dati y=2. Se modifichi i limiti di x, i suoi estremi coprono comunque dal 10 % al 90 % della larghezza degli assi, quindi il segmento si adatta all’intervallo visualizzato.
axvline per tracciare una linea verticale
axvline(x=...) posiziona una linea verticale in corrispondenza di x nelle coordinate dei dati. I suoi argomenti ymin e ymax impostano gli estremi inferiore e superiore come frazioni dell’altezza degli assi, normalmente da 0 a 1. Ad esempio, ymin=0.1 e ymax=0.9 lasciano un margine pari al 10 % dell’altezza degli assi a ciascun estremo.
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)
Produzione:
x position (data): [2, 2]
y extent (axes fraction): [0.1, 0.9]
Qui i valori memorizzati sono speculari: la posizione è il valore dei dati 2 e l’estensione è la coppia di frazioni degli assi.
La linea rimane al valore dei dati x=2. Se modifichi i limiti di y, i suoi estremi coprono comunque dal 10 % al 90 % dell’altezza degli assi. Quindi, ciascuna funzione ax*line combina una posizione in coordinate dei dati con un’estensione misurata come frazione degli assi.
hlines e vlines per tracciare linee orizzontali e verticali in Matplotlib
Usa hlines e vlines quando la posizione della linea ed entrambi gli estremi devono usare coordinate dei dati. Per hlines, y indica l’altezza e xmin e xmax indicano i valori x degli estremi. Per vlines, x indica la posizione e ymin e ymax indicano i valori y degli estremi. Modificare i limiti del grafico cambia quali porzioni sono visibili, mentre la posizione e gli estremi della linea in coordinate dei dati restano fissi. Entrambe le funzioni restituiscono una LineCollection e accettano i consueti argomenti di stile, quindi questo esempio imposta anche stili tratteggiati e punteggiati e aggiunge una legenda tramite l’argomento 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)
Produzione:
horizontal segment endpoints: [[1.0, 2.0], [3.0, 2.0]]
vertical segment endpoints: [[2.0, 1.0], [2.0, 3.0]]
Gli estremi stampati sono coordinate dei dati pure: il segmento orizzontale va da (1, 2) a (3, 2), e il segmento verticale va da (2, 1) a (2, 3).
Poiché tutti e quattro gli estremi usano coordinate dei dati, lo zoom o la modifica dei limiti cambia la porzione visibile di ciascun segmento invece di ridimensionarne gli estremi in base a una frazione degli assi.
axhspan e axvspan per ombreggiare una regione in Matplotlib
Quando una singola linea non basta, ombreggia invece la regione tra due valori. axhspan(ymin, ymax) riempie una banda orizzontale tra due valori di dati y per l’intera larghezza degli assi, e axvspan(xmin, xmax) riempie una banda verticale tra due valori di dati x per l’intera altezza. Usale per marcare un intervallo accettabile, una zona obiettivo o un periodo di interesse dietro i tuoi dati. Entrambe le funzioni restituiscono una 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)
Produzione:
horizontal band y range: 1.5 to 2.5
vertical band x range: 1.5 to 2.5
I bordi della banda usano sempre coordinate dei dati. Come axhline, anche le funzioni span accettano argomenti di frazione per la direzione trasversale — axhspan accetta xmin e xmax come frazioni degli assi per limitare la larghezza della banda, e axvspan accetta ymin e ymax — ma una banda tracciata in questo modo inizia e finisce comunque in corrispondenza di valori dei dati.
Perché una linea orizzontale o verticale potrebbe non apparire in Matplotlib
Due controlli spiegano quasi ogni segnalazione di linea mancante. Il primo è un errore di tipo: gli argomenti di frazione di axhline e axvline devono essere numeri. Passarli come stringhe — un incidente comune quando i valori provengono da un modulo, un file CSV o una voce di configurazione — solleva un ValueError prima che venga disegnato qualsiasi cosa:
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)
Produzione:
ValueError: xmin must be a single scalar value, but got 0.1
Converti prima i valori in numeri, ad esempio con float(...), e la stessa chiamata riesce: il primo esempio di questo articolo è esattamente quella chiamata con frazioni numeriche.
Il secondo controllo è l’intervallo visibile. Una linea viene creata in coordinate dei dati anche quando la sua posizione si trova fuori dai limiti correnti degli assi, quindi esiste nella figura ma viene tagliata fuori dalla vista:
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)
Produzione:
line y position: [20, 20]
axes y limits: (0.0, 4.0)
La linea si trova a y=20 mentre gli assi si fermano a 4.0. Estendi i limiti per includere la posizione — oppure correggi il valore se 20 era un errore — e la linea appare. Lo stesso controllo si applica agli estremi di hlines e vlines e ai bordi di span che cadono fuori dai limiti.
Conclusione sul tracciamento di linee orizzontali e verticali in Matplotlib
Scegli axhline o axvline quando la posizione è un valore dei dati ma l’estensione della linea deve seguire una frazione degli assi. Scegli hlines o vlines quando la posizione ed entrambi gli estremi devono restare a valori dei dati, e usa axhspan o axvspan quando deve essere evidenziata un’intera banda tra due valori invece di una singola linea. Questa scelta di coordinate determina quanta parte di una linea è visibile dopo che modifichi i limiti del grafico, e confrontare le coordinate memorizzate con i limiti degli assi spiega qualsiasi linea che sembra mancare.