HOWTO · Matplotlib
Cómo trazar líneas horizontales y verticales en Matplotlib
Este tutorial presenta cómo trazar líneas horizontales y verticales en Matplotlib con axhline y axvline, hlines y vlines, y las funciones de sombreado axhspan y axvspan.
En esta página
Para dibujar líneas de referencia horizontales y verticales en Matplotlib, elige axhline y axvline cuando la línea deba abarcar una fracción de los ejes, o hlines y vlines cuando sus extremos deban fijarse en valores de datos. Cuando el objetivo es resaltar una banda completa en lugar de un solo valor, axhspan y axvspan sombrean la región entre dos posiciones. Cada ejemplo guarda su figura en un archivo PNG temporal e imprime las coordenadas del objeto que crea, para que puedas confirmar exactamente dónde colocó Matplotlib la línea o la banda.
axhline y axvline para trazar líneas horizontales y verticales en Matplotlib
axhline para trazar una línea horizontal
axhline(y=...) coloca una línea horizontal en y en coordenadas de datos. Sus argumentos xmin y xmax fijan los extremos izquierdo y derecho como fracciones del ancho de los ejes, normalmente de 0 a 1; no son valores de datos de x. Por ejemplo, xmin=0.1 y xmax=0.9 dejan un margen equivalente al 10 % del ancho de los ejes en cada extremo.
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)
Salida:
x extent (axes fraction): [0.1, 0.9]
y position (data): [2, 2]
Los valores impresos confirman la división: la posición es el valor de datos 2, mientras que la extensión se almacena como las fracciones de los ejes 0.1 y 0.9.
La línea permanece en el valor de datos y=2. Si cambias los límites de x, sus extremos siguen abarcando del 10 % al 90 % del ancho de los ejes, por lo que el segmento se ajusta al rango mostrado.
axvline para trazar una línea vertical
axvline(x=...) coloca una línea vertical en x en coordenadas de datos. Sus argumentos ymin y ymax fijan los extremos inferior y superior como fracciones de la altura de los ejes, normalmente de 0 a 1. Por ejemplo, ymin=0.1 y ymax=0.9 dejan un margen equivalente al 10 % de la altura de los ejes en cada extremo.
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)
Salida:
x position (data): [2, 2]
y extent (axes fraction): [0.1, 0.9]
Aquí los valores almacenados se invierten: la posición es el valor de datos 2 y la extensión es el par de fracciones de los ejes.
La línea permanece en el valor de datos x=2. Si cambias los límites de y, sus extremos siguen abarcando del 10 % al 90 % de la altura de los ejes. Así, cada función ax*line combina una posición en coordenadas de datos con una extensión medida como fracción de los ejes.
hlines y vlines para trazar líneas horizontales y verticales en Matplotlib
Usa hlines y vlines cuando la posición de la línea y ambos extremos deban usar coordenadas de datos. En hlines, y da la altura y xmin y xmax dan los valores x de los extremos. En vlines, x da la posición y ymin y ymax dan los valores y de los extremos. Cambiar los límites del gráfico cambia qué porciones son visibles, mientras que la posición y los extremos de la línea en coordenadas de datos permanecen fijos. Ambas funciones devuelven una LineCollection y aceptan los argumentos de estilo habituales, por lo que este ejemplo también define estilos discontinuo y de puntos y añade una leyenda mediante el argumento 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)
Salida:
horizontal segment endpoints: [[1.0, 2.0], [3.0, 2.0]]
vertical segment endpoints: [[2.0, 1.0], [2.0, 3.0]]
Los extremos impresos son coordenadas de datos puras: el segmento horizontal va de (1, 2) a (3, 2), y el segmento vertical va de (2, 1) a (2, 3).
Como los cuatro extremos usan coordenadas de datos, acercar o cambiar los límites cambia la porción visible de cada segmento en lugar de redimensionar sus extremos para que coincidan con una fracción de los ejes.
axhspan y axvspan para sombrear una región en Matplotlib
Cuando una sola línea no basta, sombrea en su lugar la región entre dos valores. axhspan(ymin, ymax) rellena una banda horizontal entre dos valores de datos de y a todo el ancho de los ejes, y axvspan(xmin, xmax) rellena una banda vertical entre dos valores de datos de x a toda la altura. Úsalas para marcar un rango aceptable, una zona objetivo o un periodo de interés detrás de tus datos. Ambas funciones devuelven un parche 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)
Salida:
horizontal band y range: 1.5 to 2.5
vertical band x range: 1.5 to 2.5
Los bordes de la banda siempre usan coordenadas de datos. Al igual que axhline, las funciones de span también aceptan argumentos de fracción para la dirección transversal — axhspan toma xmin y xmax como fracciones de los ejes para limitar el ancho de la banda, y axvspan toma ymin y ymax — pero una banda dibujada así sigue empezando y terminando en valores de datos.
Por qué una línea horizontal o vertical puede no aparecer en Matplotlib
Dos comprobaciones explican casi todos los informes de líneas desaparecidas. La primera es un error de tipo: los argumentos de fracción de axhline y axvline deben ser números. Pasarlos como cadenas — un accidente común cuando los valores proceden de un formulario, un archivo CSV o una entrada de configuración — produce un ValueError antes de que se dibuje nada:
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)
Salida:
ValueError: xmin must be a single scalar value, but got 0.1
Convierte primero los valores a números, por ejemplo con float(...), y la misma llamada funciona: el primer ejemplo de este artículo es exactamente esa llamada con fracciones numéricas.
La segunda comprobación es el rango visible. Una línea se crea en coordenadas de datos incluso cuando su posición queda fuera de los límites actuales de los ejes, por lo que existe en la figura pero queda recortada de la 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)
Salida:
line y position: [20, 20]
axes y limits: (0.0, 4.0)
La línea está en y=20 mientras los ejes se detienen en 4.0. Amplía los límites para incluir la posición — o corrige el valor si 20 fue un error — y la línea aparece. La misma comprobación se aplica a los extremos de hlines y vlines y a los bordes de span que caen fuera de los límites.
Conclusión sobre cómo dibujar líneas horizontales y verticales en Matplotlib
Elige axhline o axvline cuando la posición sea un valor de datos pero la extensión de la línea deba seguir una fracción de los ejes. Elige hlines o vlines cuando la posición y ambos extremos deban permanecer en valores de datos, y usa axhspan o axvspan cuando haya que resaltar una banda completa entre dos valores en lugar de una sola línea. Esta elección de coordenadas determina cuánto de una línea es visible después de cambiar los límites del gráfico, y comparar las coordenadas almacenadas con los límites de los ejes explica cualquier línea que parezca faltar.