Matplotlib Pyplot

matplotlib.pyplot è una raccolta di funzioni che fa comportare Matplotlib come il sistema di tracciamento di MATLAB. Ogni funzione crea o modifica un elemento di una figura — aggiungendo assi, disegnando una linea, impostando un titolo — e pyplot tiene traccia automaticamente della figura e degli assi "correnti", così non è necessario passare oggetti in giro. Questa pagina spiega come funziona quel modello stateful, illustra le funzioni pyplot più importanti e mostra quando è meglio passare all'API esplicita orientata agli oggetti.

Cos'è matplotlib.pyplot?

Matplotlib dispone di due interfacce principali:

Entrambe le interfacce si trovano nella stessa libreria. pyplot è uno strato di comodità — ogni chiamata plt.something() manipola in ultima analisi gli stessi oggetti Figure e Axes che l'interfaccia OO espone direttamente. Comprendere questa relazione consente di mescolare entrambi gli stili con sicurezza.

L'alias standard è plt:

import matplotlib.pyplot as plt

Come funziona l'interfaccia stateful

pyplot mantiene un riferimento interno alla figura corrente e agli assi correnti. Quando si chiama plt.plot(), Matplotlib:

1. Verifica se esiste già una figura; in caso contrario, ne crea una.
2. Verifica se quella figura ha degli assi; in caso contrario, aggiunge un singolo Axes per riempire la figura.
3. Disegna i dati su quegli assi.

import matplotlib.pyplot as plt

# No figure exists yet — pyplot creates one automatically
plt.plot([1, 2, 3], [4, 6, 5])
plt.title("My first plot")
plt.show()

La figura e gli assi sono stati creati implicitamente. Questo è comodo per grafici una tantum, ma può causare sorprese quando si eseguono più grafici nello stesso script. Usa plt.figure() e plt.clf() (clear figure) oppure plt.close() per controllare lo stato esplicitamente.

Funzioni principali di pyplot

plt.plot() — Disegnare linee e marcatori

plt.plot(x, y) è il cavallo di battaglia. Disegna linee, marcatori o entrambi.

import matplotlib.pyplot as plt

months = [1, 2, 3, 4, 5, 6]
revenue = [12000, 15000, 13500, 17000, 19500, 22000]

plt.plot(months, revenue, color="steelblue", linewidth=2, marker="o", markersize=6)
plt.xlabel("Month")
plt.ylabel("Revenue ($)")
plt.title("Monthly Revenue")
plt.grid(True, linestyle="--", alpha=0.5)
plt.show()

Parametri principali di plt.plot():

plt.xlabel(), plt.ylabel(), plt.title()

Etichetta gli assi e aggiunge un titolo. Tutte e tre accettano un argomento fontsize:

import matplotlib.pyplot as plt

plt.plot([0, 1, 2], [0, 1, 4])
plt.xlabel("x", fontsize=12)
plt.ylabel("x²", fontsize=12)
plt.title("Quadratic Growth", fontsize=14, fontweight="bold")
plt.show()

plt.legend()

Quando si passa label= a una chiamata di tracciamento, plt.legend() trasforma quelle etichette in un riquadro sul grafico:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]

plt.plot(x, [v**1 for v in x], label="Linear")
plt.plot(x, [v**2 for v in x], label="Quadratic")
plt.plot(x, [v**3 for v in x], label="Cubic")
plt.xlabel("x")
plt.ylabel("y")
plt.title("Growth Rates")
plt.legend()
plt.show()

Controlla il posizionamento della legenda con il parametro loc: "upper left", "lower right", "best" (predefinito), e così via.

plt.grid()

plt.grid(True) aggiunge linee della griglia. Usa axis="x" o axis="y" per limitarle a un solo asse, e passa linestyle / alpha per stilizzare le linee:

plt.grid(True, axis="y", linestyle="--", alpha=0.7)

plt.xlim() e plt.ylim()

Imposta l'intervallo visibile su ciascun asse:

import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4, 5], [2, 4, 1, 5, 3])
plt.xlim(0, 6)     # show a bit of padding on each side
plt.ylim(0, 7)
plt.show()

plt.xticks() e plt.yticks()

Controlla quali segni di graduazione appaiono e quali etichette portano:

import matplotlib.pyplot as plt

plt.plot([0, 1, 2, 3, 4], [10, 20, 15, 25, 30])
plt.xticks([0, 1, 2, 3, 4], ["Mon", "Tue", "Wed", "Thu", "Fri"])
plt.yticks([10, 20, 30], ["Low", "Mid", "High"])
plt.show()

plt.figure()

Crea una nuova figura esplicitamente. Questo è importante negli script che producono più grafici separati:

import matplotlib.pyplot as plt

plt.figure(figsize=(8, 4))          # width, height in inches
plt.plot([1, 2, 3], [3, 1, 4])
plt.title("Figure with custom size")
plt.show()

figsize controlla la dimensione dell'output. Una figura più larga (ad es. (12, 4)) è adatta per dati di serie temporali; una figura quadrata è adatta per grafici a dispersione.

plt.savefig()

Salva la figura corrente in un file invece di (o in aggiunta a) visualizzarla:

import matplotlib.pyplot as plt

plt.plot([1, 2, 3], [1, 4, 9])
plt.title("Saved Plot")
plt.savefig("output.png", dpi=150, bbox_inches="tight")
plt.show()

I formati supportati includono png, pdf, svg e jpg. bbox_inches="tight" taglia lo spazio bianco in eccesso attorno alla figura. Chiama savefig() prima di show() — show() cancella lo stato della figura in alcuni backend.

plt.close() e plt.clf()

In un ciclo che produce molte figure, chiudi sempre le figure di cui hai finito per liberare memoria:

plt.close()       # close the current figure
plt.close("all")  # close every open figure
plt.clf()         # clear the current figure without closing its window

Sottotrame con pyplot

plt.subplots() è il ponte tra le interfacce pyplot e OO. Crea un oggetto Figure e uno o più oggetti Axes, poi restituisce entrambi:

import matplotlib.pyplot as plt

fig, axes = plt.subplots(1, 2, figsize=(10, 4))  # 1 row, 2 columns

# Left panel
axes[0].plot([1, 2, 3], [1, 4, 9], color="steelblue")
axes[0].set_title("Quadratic")
axes[0].set_xlabel("x")
axes[0].set_ylabel("x²")

# Right panel
axes[1].plot([1, 2, 3], [1, 8, 27], color="tomato")
axes[1].set_title("Cubic")
axes[1].set_xlabel("x")
axes[1].set_ylabel("x³")

fig.suptitle("Growth Curves", fontsize=14)
plt.tight_layout()
plt.show()

plt.tight_layout() regola automaticamente la spaziatura tra i pannelli per evitare che titoli ed etichette si sovrappongano.

pyplot vs. l'API orientata agli oggetti

Una volta che si va oltre un singolo asse, l'API stateful diventa più difficile da gestire. Usa l'API OO (tramite fig, ax = plt.subplots()) quando:

• Hai più di un sottografico.
• Stai scrivendo una funzione che crea e restituisce un grafico.
• Hai bisogno di un controllo granulare su formattatori di tick, assi secondari o assi inseriti.

Lo schema è semplice: la maggior parte delle funzioni plt.something() ha un equivalente ax.set_something() sull'oggetto Axes.

Un esempio completo

Il seguente script combina le funzioni pyplot più comuni in un unico esempio autonomo ed eseguibile:

import matplotlib.pyplot as plt

# Data
years = [2019, 2020, 2021, 2022, 2023]
product_a = [45, 38, 52, 61, 70]
product_b = [30, 42, 39, 55, 65]

# Figure
plt.figure(figsize=(9, 5))

# Two series
plt.plot(years, product_a, marker="o", color="steelblue",
         linewidth=2, label="Product A")
plt.plot(years, product_b, marker="s", color="tomato",
         linewidth=2, label="Product B")

# Labels and decoration
plt.xlabel("Year", fontsize=12)
plt.ylabel("Units Sold (thousands)", fontsize=12)
plt.title("Annual Sales Comparison", fontsize=14)
plt.legend()
plt.grid(True, linestyle="--", alpha=0.5)
plt.xticks(years)

# Save and display
plt.savefig("sales_comparison.png", dpi=150, bbox_inches="tight")
plt.show()

Questo esempio mostra entrambe le serie sugli stessi assi, una legenda, una griglia, etichette personalizzate dei tick sull'asse x e salva il risultato in un file PNG.

Errori comuni

Dimenticare plt.show() — in uno script Python normale (non Jupyter), la finestra del grafico non si apre senza di esso. In Jupyter, %matplotlib inline lo rende automatico.

Chiamare plt.savefig() dopo plt.show() — show() finalizza e ripristina la figura. Prima salva, poi mostra:

plt.savefig("chart.png")  # correct order
plt.show()

Accumulo di più figure — in un ciclo, ogni chiamata plt.figure() crea una nuova figura che rimane in memoria finché non si chiama plt.close(). Chiudi le figure di cui non hai più bisogno.

Mescolare gli stili pyplot e OO in modo incoerente — è lecito usare entrambi, ma bisogna farlo deliberatamente: ottieni l'oggetto Axes e lavoraci direttamente invece di affidarti agli "assi correnti" impliciti di pyplot quando hai più di un asse.

Passi successivi

• Grafici a linee con Matplotlib — stili di linea, serie multiple e aree riempite in profondità.
• Marcatori Matplotlib — tutte le forme di marcatore integrate e come stilizzarle.
• Etichette Matplotlib — titoli, etichette degli assi, annotazioni e posizionamento del testo.
• Griglia Matplotlib — stili delle linee della griglia, tick minori e stile dello sfondo.
• Barre Matplotlib — grafici a barre verticali, orizzontali, in pila e raggruppati.
• Dispersione Matplotlib — grafici a dispersione con mappe di colore e codifica della dimensione.
• Istogrammi Matplotlib — controllo dei bin, curve di densità e distribuzioni sovrapposte.
• Sottotrame Matplotlib — layout multi-pannello con subplots() e GridSpec.