Iniziare con Matplotlib

Questa pagina illustra tutto ciò che serve per iniziare a usare Matplotlib: come installarlo, come importarlo, come è strutturata la libreria e come creare e personalizzare il tuo primo grafico. Al termine avrai uno script funzionante che produce un grafico a linee completamente etichettato.

Installare Matplotlib

Matplotlib non fa parte della libreria standard di Python, quindi devi installarlo prima di poterlo importare. Usa pip, il gestore dei pacchetti di Python:

pip install matplotlib

Se stai lavorando all'interno di un ambiente virtuale (consigliato), attivalo prima e poi esegui il comando sopra. Per confermare che l'installazione sia andata a buon fine e verificare la versione:

python -m pip show matplotlib

Dovresti vedere un output simile a:

Name: matplotlib
Version: 3.9.x
...

Matplotlib richiede Python 3.9 o versioni successive a partire dalla serie di rilascio 3.9.

Importare Matplotlib

Matplotlib è organizzato in diversi sotto-pacchetti. Per i grafici quotidiani ti serve solo il modulo pyplot, che per convenzione viene importato con l'alias plt:

import matplotlib.pyplot as plt

L'alias plt è la convenzione universale nella comunità Python. Usarlo rende il tuo codice coerente con tutorial, documentazione e codice che trovi sul web.

Se hai bisogno anche di array numerici (comune quando si generano dati da rappresentare), importa NumPy contemporaneamente:

import matplotlib.pyplot as plt
import numpy as np

Come è Strutturato Matplotlib

Comprendere la struttura a due livelli di Matplotlib evita molta confusione:

• Figure — il contenitore di livello superiore. Pensalo come la tela o la finestra. Una Figure può contenere uno o più Axes.
• Axes — una singola area di tracciamento con il proprio asse x, asse y, titolo e dati. La parola "Axes" non indica solo le linee degli assi; è l'intera regione del grafico.

Matplotlib espone due interfacce per lavorare con questi oggetti:

L'interfaccia pyplot gestisce automaticamente la Figure e gli Axes correnti. L'interfaccia OO ti fornisce handle espliciti per controllare ogni oggetto con precisione. Entrambe producono output identico; la differenza è nell'organizzazione del codice.

Creare il Tuo Primo Grafico

La funzione plt.plot() traccia una linea attraverso una sequenza di coppie (x, y). Passa due liste di uguale lunghezza — una per i valori x e una per i valori y:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4]
y = [1, 4, 9, 16]

plt.plot(x, y)
plt.show()

plt.show() invia la figure allo schermo. In uno script da terminale, l'esecuzione si interrompe finché non chiudi la finestra del grafico. In un notebook Jupyter, il grafico appare inline e plt.show() è opzionale.

Aggiungere Etichette e un Titolo

Un grafico senza etichette è difficile da interpretare. Aggiungi etichette agli assi e un titolo con tre chiamate su una riga:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4]
y = [1, 4, 9, 16]

plt.plot(x, y)
plt.xlabel('x')
plt.ylabel('y = x²')
plt.title('Square Numbers')
plt.show()

• plt.xlabel() — etichetta per l'asse orizzontale.
• plt.ylabel() — etichetta per l'asse verticale.
• plt.title() — titolo visualizzato sopra il grafico.

Personalizzare il Colore e lo Stile della Linea

Passa argomenti per nome a plt.plot() per cambiare l'aspetto della linea:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4]
y = [1, 4, 9, 16]

plt.plot(x, y, color='steelblue', linewidth=2, linestyle='--')
plt.xlabel('x')
plt.ylabel('y = x²')
plt.title('Square Numbers')
plt.show()

Opzioni comuni:

Puoi anche usare una stringa di formato abbreviata come terzo argomento posizionale. 'r--' significa rosso tratteggiato, 'bs' significa quadrati blu, 'g^' significa triangoli verdi:

plt.plot(x, y, 'r--')

Impostare i Limiti degli Assi

Per impostazione predefinita Matplotlib sceglie i limiti degli assi in base ai dati. Puoi sovrascriverli:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4]
y = [1, 4, 9, 16]

plt.plot(x, y)
plt.xlim(0, 5)
plt.ylim(0, 20)
plt.show()

plt.xlim(min, max) e plt.ylim(min, max) impostano l'intervallo visibile di ciascun asse. È utile quando si vuole evidenziare una regione specifica o mantenere gli assi coerenti su più grafici.

Tracciare Più Linee

Chiama plt.plot() più volte prima di plt.show() per sovrapporre diverse linee sugli stessi Axes. Aggiungi un argomento label a ogni chiamata, poi chiama plt.legend() per visualizzare la legenda:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]
y_sq = [1, 4, 9, 16, 25]
y_cb = [1, 8, 27, 64, 125]

plt.plot(x, y_sq, color='steelblue', label='x²')
plt.plot(x, y_cb, color='tomato', label='x³')
plt.xlabel('x')
plt.ylabel('y')
plt.title('Comparing Growth')
plt.legend()
plt.show()

plt.legend() legge la stringa label da ogni chiamata a plot() e costruisce la legenda automaticamente. Inseriscila prima di plt.show().

L'Interfaccia Object-Oriented

Per qualsiasi cosa che vada oltre un singolo grafico semplice, l'interfaccia OO è più chiara e più facile da mantenere. Crea una Figure e uno o più Axes con plt.subplots(), poi chiama i metodi direttamente sull'oggetto ax:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]
y_sq = [1, 4, 9, 16, 25]
y_cb = [1, 8, 27, 64, 125]

fig, ax = plt.subplots()

ax.plot(x, y_sq, color='steelblue', label='x²')
ax.plot(x, y_cb, color='tomato', label='x³')
ax.set_xlabel('x')
ax.set_ylabel('y')
ax.set_title('Comparing Growth')
ax.legend()
ax.grid(True)

plt.show()

I nomi dei metodi OO rispecchiano le funzioni pyplot con il prefisso set_: plt.xlabel() diventa ax.set_xlabel(), plt.title() diventa ax.set_title(), e così via. L'handle esplicito ax rende inequivocabile quale grafico stai modificando — essenziale quando una Figure contiene più subplot.

Salvare un Grafico su File

Chiama plt.savefig() al posto di (o in aggiunta a) plt.show() per scrivere la figure su disco:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4]
y = [1, 4, 9, 16]

plt.plot(x, y, color='steelblue', linewidth=2)
plt.xlabel('x')
plt.ylabel('y = x²')
plt.title('Square Numbers')
plt.savefig('square_numbers.png', dpi=150, bbox_inches='tight')

Matplotlib deduce il formato del file dall'estensione. Formati comuni: .png, .pdf, .svg, .jpg. L'argomento dpi controlla la risoluzione (150–300 dpi è tipico per i report). bbox_inches='tight' elimina lo spazio bianco dai bordi.

Errori Comuni

Chiama plt.show() una sola volta. Chiamarlo più volte in uno script può produrre figure vuote perché Matplotlib cancella la figure corrente dopo averla visualizzata.

L'ordine conta con pyplot. Le chiamate di personalizzazione (plt.xlabel(), plt.title(), ecc.) devono venire prima di plt.show().

Riutilizzare una figure. Se costruisci un grafico in un ciclo e dimentichi di cancellarlo, i dati delle iterazioni precedenti si accumulano. Chiama plt.clf() (cancella la figure) o plt.close() tra un'iterazione e l'altra, oppure crea ogni volta un nuovo fig, ax = plt.subplots().

Backend non interattivi. Su server privi di display (CI, container Docker), plt.show() potrebbe generare un errore. Imposta il backend prima di importare pyplot:

import matplotlib
matplotlib.use('Agg')  # non-interactive PNG backend
import matplotlib.pyplot as plt

Passi Successivi

Ora che sai produrre un grafico di base, esplora i capitoli dedicati:

• Matplotlib Pyplot — approfondimento delle funzioni pyplot e dei tipi di grafico
• Matplotlib Line Plots — stilizzare linee, marcatori e fill-between
• Matplotlib Labels — etichette degli assi, titoli, annotazioni
• Matplotlib Markers — marcatori dei punti dati e loro stili
• Matplotlib Grid — aggiungere e configurare le linee della griglia
• Matplotlib Subplots — disporre più grafici in una singola figure
• Matplotlib Bar Charts — grafici a barre verticali e orizzontali
• Matplotlib Scatter Plots — grafici a dispersione a due variabili
• Matplotlib Histograms — distribuzioni di frequenza
• Matplotlib Pie Charts — dati proporzionali