Scikit-Learn (sklearn) è la libreria open source di riferimento in Python per la modellazione statistica e il machine learning tradizionale, costruita su NumPy, SciPy e Matplotlib. La sua robustezza architetturale risiede in un design pattern rigorosamente unificato a tre interfacce:
- Estimator (Stimatore): Apprende i parametri del modello dai dati mediante
fit(X, y). - Transformer (Trasformatore): Pre-elabora e proietta le feature mediante
transform(X)efit_transform(X). - Predictor (Predittore): Genera predizioni su campioni inediti mediante
predict(X),predict_proba(X)escore(X, y).
🔗 Cheat Sheet correlati: Cheat Sheet NumPy · Cheat Sheet Pandas · Algoritmi di apprendimento supervisionato · Metodi di analisi dati · Cheat Sheet Python
1. Esempio introduttivo end-to-end
Lo script seguente illustra il caricamento del dataset, la suddivisione stratificata, lo scaling delle feature, l'addestramento e la valutazione:
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler
from sklearn.neighbors import KNeighborsClassifier
from sklearn.metrics import accuracy_score, classification_report
# 1. Caricamento dati
iris = load_iris()
X, y = iris.data, iris.target
# 2. Suddivisione stratificata train / test
X_train, X_test, y_train, y_test = train_test_split(
X, y, test_size=0.2, random_state=42, stratify=y
)
# 3. Ridimensionamento feature (adattare SOLO sul training set per evitare leak)
scaler = StandardScaler()
X_train_scaled = scaler.fit_transform(X_train)
X_test_scaled = scaler.transform(X_test)
# 4. Addestramento stimatore
knn = KNeighborsClassifier(n_neighbors=5)
knn.fit(X_train_scaled, y_train)
# 5. Predizione e valutazione
y_pred = knn.predict(X_test_scaled)
print(f"Accuratezza: {accuracy_score(y_test, y_pred):.4f}")
print(classification_report(y_test, y_pred, target_names=iris.target_names))
2. Preparazione e suddivisione dei dati
Scikit-Learn richiede strutture numeriche 2D: una matrice delle feature $X$ di forma (n_samples, n_features) e un vettore target $y$ di forma (n_samples,). Sono supportati ndarray NumPy, matrici sparse SciPy (scipy.sparse) e DataFrame/Series Pandas.
2.1 Dataset integrati & Generazione sintetica
from sklearn import datasets
# Piccoli dataset standard di riferimento (restituisce oggetto Bunch)
iris = datasets.load_iris() # Classificazione multi-classe
digits = datasets.load_digits() # Immagini di cifre manoscritte 8x8
diabetes = datasets.load_diabetes() # Benchmark per regressione
wine = datasets.load_wine() # Analisi chimica del vino a 3 classi
# Dataset reali di riferimento (memorizzati localmente nella cache)
housing = datasets.fetch_california_housing()
# Generazione dati sintetici per testare algoritmi
X, y = datasets.make_classification(
n_samples=1000, n_features=20, n_informative=15, n_classes=2, random_state=42
)
X_reg, y_reg = datasets.make_regression(n_samples=500, n_features=10, noise=0.1, random_state=42)
X_blob, y_blob = datasets.make_blobs(n_samples=300, centers=3, n_features=2, random_state=42)
2.2 Suddivisione del dataset (train_test_split)
from sklearn.model_selection import train_test_split
X_train, X_test, y_train, y_test = train_test_split(
X, y,
test_size=0.25, # Proporzione del set di test (predefinito: 0.25)
random_state=42, # Seme casuale fisso per la riproducibilità
shuffle=True, # Rimescola i campioni prima della divisione
stratify=y # Molto consigliato per classificazione: preserva la proporzione delle classi
)
3. Feature Engineering e pre-elaborazione (sklearn.preprocessing & sklearn.impute)
| Trasformatore | Caso d'uso | Trasformazione matematica / Logica | Parametri chiave |
|---|---|---|---|
StandardScaler |
Standardizzazione Z-score delle feature numeriche | $z = \frac{x - \mu}{\sigma}$ (media zero, varianza unitaria) | with_mean=True, with_std=True |
MinMaxScaler |
Scalatura delle feature in un intervallo chiuso prefissato | $x' = \frac{x - x_{\min}}{x_{\max} - x_{\min}} \cdot (\max - \min) + \min$ | feature_range=(0, 1) |
RobustScaler |
Scaling robusto rispetto agli outlier | Scalatura basata sull'intervallo interquartile: $x' = \frac{x - Q_2}{Q_3 - Q_1}$ | quantile_range=(25.0, 75.0) |
Normalizer |
Normalizzazione per riga su ogni singolo campione | Scala ogni campione alla norma unitaria ($L_1$, $L_2$ o Max) | norm='l2' ('l1', 'max') |
Binarizer |
Binarizzazione tramite soglia di valori continui | $x > \text{threshold} \Rightarrow 1$, altrimenti $0$ | threshold=0.0 |
SimpleImputer |
Imputazione dei valori mancanti | Sostituisce valori nulli con media, mediana, moda o costante | missing_values=np.nan, strategy='mean' |
OneHotEncoder |
Codifica One-Hot per variabili categoriche nominali | Converte variabili categoriche in colonne binarie dummy | drop='first', handle_unknown='ignore' |
OrdinalEncoder |
Codifica ordinale per variabili categoriche ordinate | Codifica le categorie in interi ordinati $0, \dots, K-1$ | categories='auto', encoded_missing_value |
LabelEncoder |
Codifica delle etichette per la variabile target $y$ | Converte etichette testuali in interi $0 \dots C-1$ | SOLO per la variabile target $y$, MAI per le feature $X$ |
PolynomialFeatures |
Generazione di feature polinomiali e di interazione | Genera termini di ordine superiore $[1, a, b, a^2, ab, b^2]$ | degree=2, include_bias=False |
3.1 Esempi di codice di pre-elaborazione
import numpy as np
from sklearn.preprocessing import (
StandardScaler, MinMaxScaler, RobustScaler, Normalizer,
Binarizer, OneHotEncoder, OrdinalEncoder, LabelEncoder, PolynomialFeatures
)
from sklearn.impute import SimpleImputer
# 1. Standardizzazione numerica (mai applicare fit sui dati di test!)
scaler = StandardScaler()
X_train_std = scaler.fit_transform(X_train)
X_test_std = scaler.transform(X_test)
# 2. Imputazione valori mancanti (strategia con mediana)
imputer = SimpleImputer(missing_values=np.nan, strategy='median')
X_train_imp = imputer.fit_transform(X_train)
X_test_imp = imputer.transform(X_test)
# 3. Codifica One-Hot (gestisce in sicurezza categorie sconosciute)
ohe = OneHotEncoder(handle_unknown='ignore', sparse_output=False)
X_train_ohe = ohe.fit_transform(X_train_cat)
X_test_ohe = ohe.transform(X_test_cat)
# 4. Codifica della variabile target
le = LabelEncoder()
y_train_enc = le.fit_transform(y_train)
y_test_enc = le.transform(y_test)
# 5. Espansione polinomiale delle feature
poly = PolynomialFeatures(degree=2, include_bias=False)
X_train_poly = poly.fit_transform(X_train)
4. Indice principale degli stimatori più diffusi
4.1 Apprendimento supervisionato: Classificazione
from sklearn.linear_model import LogisticRegression
from sklearn.neighbors import KNeighborsClassifier
from sklearn.svm import SVC
from sklearn.naive_bayes import GaussianNB
from sklearn.ensemble import RandomForestClassifier, HistGradientBoostingClassifier
# Regressione logistica (baseline lineare di classificazione)
clf_lr = LogisticRegression(C=1.0, max_iter=200, random_state=42)
# K vicini più prossimi (KNN)
clf_knn = KNeighborsClassifier(n_neighbors=5, metric='minkowski', p=2)
# Support Vector Machine (kernel RBF)
clf_svm = SVC(C=1.0, kernel='rbf', gamma='scale', probability=True, random_state=42)
# Naive Bayes gaussiano
clf_gnb = GaussianNB()
# Random Forest (ensemble con Bagging)
clf_rf = RandomForestClassifier(n_estimators=100, max_depth=None, n_jobs=-1, random_state=42)
# Gradient Boosting basato su istogrammi (GBDT rapido affine a LightGBM)
clf_hgb = HistGradientBoostingClassifier(learning_rate=0.1, max_iter=100, random_state=42)
4.2 Apprendimento supervisionato: Regressione
from sklearn.linear_model import LinearRegression, Ridge, Lasso
from sklearn.svm import SVR
from sklearn.ensemble import RandomForestRegressor, HistGradientBoostingRegressor
# Regressione lineare ordinaria dei minimi quadrati (OLS)
reg_lr = LinearRegression()
# Regressione Ridge (regolarizzazione L2 contro la multicollinearità)
reg_ridge = Ridge(alpha=1.0)
# Regressione Lasso (regolarizzazione L1 per selezione feature)
reg_lasso = Lasso(alpha=0.1)
# Support Vector Regression (SVR)
reg_svr = SVR(kernel='rbf', C=1.0, epsilon=0.1)
# Regressore Random Forest
reg_rf = RandomForestRegressor(n_estimators=100, n_jobs=-1, random_state=42)
4.3 Apprendimento non supervisionato: Clustering & Riduzione della dimensionalità
from sklearn.cluster import KMeans, DBSCAN
from sklearn.decomposition import PCA
# Clustering K-Means
kmeans = KMeans(n_clusters=3, init='k-means++', n_init=10, random_state=42)
kmeans.fit(X)
cluster_labels = kmeans.labels_ # Assegnazioni ai cluster
cluster_centers = kmeans.cluster_centers_
# Clustering spaziale basato sulla densità (DBSCAN: resistente al rumore)
dbscan = DBSCAN(eps=0.5, min_samples=5)
db_labels = dbscan.fit_predict(X) # -1 identifica campioni di rumore (outlier)
# Analisi delle componenti principali (PCA): conserva il 95% di varianza
pca = PCA(n_components=0.95)
X_pca = pca.fit_transform(X)
print("Componenti conservate:", pca.n_components_)
print("Rapporto di varianza spiegata:", pca.explained_variance_ratio_)
5. Operazioni essenziali dell'API unificata
| Operazione | Metodo canonico | Tipo di oggetto target | Semantica e valore di ritorno |
|---|---|---|---|
| Adattare (Fit) | estimator.fit(X, y) |
Tutti gli Estimator | Stima i parametri dai dati di addestramento; restituisce self |
| Predire (Predict) | predictor.predict(X) |
Tutti i Predictor | Genera etichette di classe discrete o valori target continui |
| Probabilità | predictor.predict_proba(X) |
Classificatori | Calcola la matrice di distribuzione di probabilità a posteriori |
| Distanza decisionale | predictor.decision_function(X) |
Modelli lineari / SVM | Distanza con segno dei campioni dall'iperpiano separatore |
| Trasformare | transformer.transform(X) |
Tutti i Transformer | Proietta le feature in ingresso tramite i parametri appresi |
| Adattare e trasformare | transformer.fit_transform(X) |
Tutti i Transformer | Calcola parametri e trasforma in un unico passaggio ottimizzato |
| Punteggio predefinito | estimator.score(X, y) |
Classificatori / Regressori | Accuratezza per classificazione; coefficiente $R^2$ per regressione |
6. Metriche di valutazione (sklearn.metrics)
6.1 Metriche per la classificazione
from sklearn.metrics import (
accuracy_score, precision_score, recall_score, f1_score,
roc_auc_score, confusion_matrix, classification_report,
ConfusionMatrixDisplay
)
# 1. Metriche su etichette discrete (specificare average per multi-classe)
acc = accuracy_score(y_test, y_pred)
prec = precision_score(y_test, y_pred, average='macro')
rec = recall_score(y_test, y_pred, average='macro')
f1 = f1_score(y_test, y_pred, average='macro')
# 2. Metriche per ranking continuo (ROC-AUC richiede probabilità stimate)
y_prob = clf.predict_proba(X_test)[:, 1] # Probabilità della classe positiva
auc = roc_auc_score(y_test, y_prob)
# 3. Matrice di confusione e report di classificazione
cm = confusion_matrix(y_test, y_pred)
print(classification_report(y_test, y_pred))
# 4. Visualizzazione grafica della matrice di confusione
disp = ConfusionMatrixDisplay(confusion_matrix=cm)
disp.plot()
6.2 Metriche per la regressione
from sklearn.metrics import mean_absolute_error, mean_squared_error, r2_score
mae = mean_absolute_error(y_test, y_pred)
mse = mean_squared_error(y_test, y_pred)
rmse = mean_squared_error(y_test, y_pred, squared=False) # Radice dell'errore quadratico medio (RMSE)
r2 = r2_score(y_test, y_pred) # Coefficiente di determinazione R²
6.3 Metriche per il clustering
from sklearn.metrics import (
adjusted_rand_score, homogeneity_score, v_measure_score, silhouette_score
)
# Validazione esterna (quando sono note le etichette reali)
ari = adjusted_rand_score(y_true, cluster_labels) # Intervallo: [-1, 1], valori più alti indicano migliore accordo
homo = homogeneity_score(y_true, cluster_labels) # Intervallo: [0, 1]
vm = v_measure_score(y_true, cluster_labels) # Media armonica tra omogeneità e completezza
# Validazione interna (geometrica, senza etichette reali)
sil = silhouette_score(X, cluster_labels) # Intervallo: [-1, 1], vicino a 1 indica cluster ben separati
7. Cross-Validation e regolazione degli iperparametri (sklearn.model_selection)
7.1 Validazione crociata (Cross-Validation)
from sklearn.model_selection import cross_val_score, cross_validate, StratifiedKFold
# Cross-validation K-Fold standard
scores = cross_val_score(clf, X, y, cv=5, scoring='accuracy')
print(f"Accuratezza 5-Fold CV: {scores.mean():.4f} (±{scores.std():.4f})")
# Generatore K-Fold stratificato
skf = StratifiedKFold(n_splits=5, shuffle=True, random_state=42)
scores_skf = cross_val_score(clf, X, y, cv=skf, scoring='f1_macro')
# Valutazione congiunta multi-metrica
multi_scores = cross_validate(
clf, X, y, cv=5,
scoring=['accuracy', 'roc_auc'],
return_train_score=False
)
print("AUC media di validazione:", multi_scores['test_roc_auc'].mean())
7.2 Ricerca su griglia e ricerca casuale
from sklearn.model_selection import GridSearchCV, RandomizedSearchCV
from scipy.stats import randint
# 1. Ricerca esaustiva su griglia (GridSearchCV)
param_grid = {
'n_neighbors': [3, 5, 7, 11],
'weights': ['uniform', 'distance'],
'metric': ['euclidean', 'manhattan']
}
grid = GridSearchCV(
estimator=KNeighborsClassifier(),
param_grid=param_grid,
cv=5,
scoring='accuracy',
n_jobs=-1
)
grid.fit(X_train, y_train)
print("Migliori parametri:", grid.best_params_)
best_model = grid.best_estimator_
# 2. Ricerca casuale degli iperparametri (per spazi di ricerca ampi)
param_dist = {
'n_estimators': randint(50, 300),
'max_depth': [None, 5, 10, 20],
'min_samples_split': randint(2, 11)
}
rand_search = RandomizedSearchCV(
estimator=RandomForestClassifier(random_state=42),
param_distributions=param_dist,
n_iter=20, # Numero di combinazioni casuali di parametri
cv=5,
scoring='accuracy',
random_state=42,
n_jobs=-1
)
rand_search.fit(X_train, y_train)
print("Migliori parametri ricerca casuale:", rand_search.best_params_)
8. Buone pratiche di produzione: Pipeline e ColumnTransformer
8.1 Perché le Pipeline sono indispensabili
Applicare trasformazioni o imputazioni globalmente prima della suddivisione causa il fenomeno del Data Leakage (fuga di dati): le informazioni dei fold di test contaminano le statistiche di addestramento, portando a metriche offline illusoriamente ottimistiche che falliscono in produzione.
Pipeline lega trasformatori e stimatori in un'unica entità atomica a prova di leakage. Durante la cross-validation, i trasformatori vengono addestrati rigorosamente sui soli fold di training.
8.2 Modello ColumnTransformer per la produzione
I dati tabulari reali presentano tipicamente una combinazione di feature numeriche e variabili categoriche:
from sklearn.compose import ColumnTransformer
from sklearn.pipeline import Pipeline
from sklearn.impute import SimpleImputer
from sklearn.preprocessing import StandardScaler, OneHotEncoder
from sklearn.ensemble import RandomForestClassifier
# 1. Partizionamento esplicito delle feature
numeric_features = ['age', 'income', 'credit_score']
categorical_features = ['gender', 'occupation', 'city']
# 2. Sub-pipeline numerica: imputazione con mediana -> standardizzazione
numeric_transformer = Pipeline(steps=[
('imputer', SimpleImputer(strategy='median')),
('scaler', StandardScaler())
])
# 3. Sub-pipeline categorica: imputazione con costante -> One-Hot encoding
categorical_transformer = Pipeline(steps=[
('imputer', SimpleImputer(strategy='constant', fill_value='missing')),
('onehot', OneHotEncoder(handle_unknown='ignore', sparse_output=False))
])
# 4. Integrazione delle colonne in un ColumnTransformer unificato
preprocessor = ColumnTransformer(transformers=[
('num', numeric_transformer, numeric_features),
('cat', categorical_transformer, categorical_features)
])
# 5. Assemblaggio della pipeline completa
full_pipeline = Pipeline(steps=[
('preprocessor', preprocessor),
('classifier', RandomForestClassifier(n_estimators=100, random_state=42))
])
# 6. Addestramento e inferenza atomici (zero leakage, deploy robusto)
full_pipeline.fit(X_train_df, y_train)
y_pred = full_pipeline.predict(X_test_df)
print("Accuratezza del Pipeline sul test set:", full_pipeline.score(X_test_df, y_test))