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.

Grafico Matplotlib con una linea orizzontale rossa a y = 2 che si estende dal 10 % al 90 % della larghezza degli assi

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.

Grafico Matplotlib con una linea verticale verde a x = 2 che si estende dal 10 % al 90 % dell’altezza 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).

Grafico Matplotlib con un segmento orizzontale rosso tratteggiato a y = 2 da x = 1 a x = 3 e un segmento verticale verde punteggiato a x = 2 da y = 1 a y = 3, identificati da una legenda

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

Grafico Matplotlib con una banda orizzontale arancione tra y = 1,5 e y = 2,5 e una banda verticale blu tra x = 1,5 e x = 2,5, identificate da una legenda

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.