Scikit-Learn (sklearn) é a biblioteca essencial de código aberto em Python para modelagem estatística e aprendizado de máquina tradicional, construída sobre NumPy, SciPy e Matplotlib. Seu grande diferencial arquitetural reside em um padrão de projeto estritamente unificado em três interfaces:
- Estimator (Estimador): Aprende os parâmetros do modelo a partir dos dados por meio de
fit(X, y). - Transformer (Transformador): Pré-processa e projeta atributos por meio de
transform(X)efit_transform(X). - Predictor (Preditor): Realiza predições sobre novas amostras por meio de
predict(X),predict_proba(X)escore(X, y).
🔗 Folhas de consulta relacionadas: Folha de consulta NumPy · Folha de consulta Pandas · Algoritmos de aprendizado supervisionado · Métodos de análise de dados · Folha de consulta Python
1. Exemplo introdutório de ponta a ponta
O script independente a seguir ilustra o carregamento de dados, divisão estratificada, escalonamento de atributos, ajuste do modelo e avaliação:
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. Carregar dados
iris = load_iris()
X, y = iris.data, iris.target
# 2. Divisão estratificada entre treino e teste
X_train, X_test, y_train, y_test = train_test_split(
X, y, test_size=0.2, random_state=42, stratify=y
)
# 3. Escalonamento de atributos (ajustar APENAS nos dados de treino para evitar vazamento)
scaler = StandardScaler()
X_train_scaled = scaler.fit_transform(X_train)
X_test_scaled = scaler.transform(X_test)
# 4. Ajustar estimador
knn = KNeighborsClassifier(n_neighbors=5)
knn.fit(X_train_scaled, y_train)
# 5. Predição e avaliação
y_pred = knn.predict(X_test_scaled)
print(f"Acurácia: {accuracy_score(y_test, y_pred):.4f}")
print(classification_report(y_test, y_pred, target_names=iris.target_names))
2. Preparação e divisão de dados
O Scikit-Learn exige estruturas numéricas bidimensionais: uma matriz de atributos $X$ com formato (n_samples, n_features) e um vetor de destino $y$ com formato (n_samples,). São aceitos ndarrays do NumPy, matrizes esparsas do SciPy (scipy.sparse) e DataFrames/Series do Pandas.
2.1 Conjuntos de dados integrados e sintéticos
from sklearn import datasets
# Conjuntos de dados pequenos para testes (retorna objeto Bunch)
iris = datasets.load_iris() # Classificação multiclasse
digits = datasets.load_digits() # Imagens de dígitos manuscritos 8x8
diabetes = datasets.load_diabetes() # Benchmark de regressão
wine = datasets.load_wine() # Análise química de vinhos em 3 classes
# Conjuntos de dados de referência reais (em cache local)
housing = datasets.fetch_california_housing()
# Geração de dados sintéticos para testes de algoritmos
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 Divisão do conjunto de dados (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, # Proporção do conjunto de teste (padrão: 0.25)
random_state=42, # Semente fixa para reprodutibilidade
shuffle=True, # Embaralhar amostras antes da divisão
stratify=y # Altamente recomendado para classificação: preserva proporção das classes
)
3. Engenharia de atributos e pré-processamento (sklearn.preprocessing & sklearn.impute)
| Transformador | Caso de uso | Transformação matemática / Lógica | Parâmetros principais |
|---|---|---|---|
StandardScaler |
Padronização Z-score de atributos numéricos | $z = \frac{x - \mu}{\sigma}$ (média zero, variância unitária) | with_mean=True, with_std=True |
MinMaxScaler |
Escalonamento de atributos para intervalo delimitado | $x' = \frac{x - x_{\min}}{x_{\max} - x_{\min}} \cdot (\max - \min) + \min$ | feature_range=(0, 1) |
RobustScaler |
Escalonamento robusto contra valores discrepantes (outliers) | Escalonamento interquartil: $x' = \frac{x - Q_2}{Q_3 - Q_1}$ | quantile_range=(25.0, 75.0) |
Normalizer |
Normalização por linha para cada amostra | Normaliza cada amostra para ter norma unitária ($L_1$, $L_2$ ou Max) | norm='l2' ('l1', 'max') |
Binarizer |
Binarização por limiar de valores contínuos | $x > \text{threshold} \Rightarrow 1$, caso contrário $0$ | threshold=0.0 |
SimpleImputer |
Imputação de valores faltantes | Substitui valores ausentes por média, mediana, moda ou constante | missing_values=np.nan, strategy='mean' |
OneHotEncoder |
Codificação One-Hot para variáveis categóricas nominais | Converte variáveis categóricas em colunas binárias indicadoras | drop='first', handle_unknown='ignore' |
OrdinalEncoder |
Codificação ordinal para variáveis categóricas ordenadas | Converte categorias em inteiros ordenados $0, \dots, K-1$ | categories='auto', encoded_missing_value |
LabelEncoder |
Codificação de rótulos para a variável de destino $y$ | Converte rótulos textuais em inteiros $0 \dots C-1$ | APENAS para a variável de destino $y$, NUNCA para atributos $X$ |
PolynomialFeatures |
Geração de atributos polinomiais e termos de interação | Gera termos polinomiais $[1, a, b, a^2, ab, b^2]$ | degree=2, include_bias=False |
3.1 Exemplos de código de pré-processamento
import numpy as np
from sklearn.preprocessing import (
StandardScaler, MinMaxScaler, RobustScaler, Normalizer,
Binarizer, OneHotEncoder, OrdinalEncoder, LabelEncoder, PolynomialFeatures
)
from sklearn.impute import SimpleImputer
# 1. Padronização numérica (nunca ajuste no conjunto de teste!)
scaler = StandardScaler()
X_train_std = scaler.fit_transform(X_train)
X_test_std = scaler.transform(X_test)
# 2. Imputação de valores ausentes (estratégia de 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ção One-Hot (lida com categorias não vistas no teste)
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ção da variável de destino
le = LabelEncoder()
y_train_enc = le.fit_transform(y_train)
y_test_enc = le.transform(y_test)
# 5. Expansão de atributos polinomiais
poly = PolynomialFeatures(degree=2, include_bias=False)
X_train_poly = poly.fit_transform(X_train)
4. Índice mestre de estimadores fundamentais
4.1 Aprendizado supervisionado: Classificação
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
# Regressão logística (modelo linear de referência)
clf_lr = LogisticRegression(C=1.0, max_iter=200, random_state=42)
# K vizinhos mais próximos (KNN)
clf_knn = KNeighborsClassifier(n_neighbors=5, metric='minkowski', p=2)
# Máquinas de vetores de suporte (núcleo RBF)
clf_svm = SVC(C=1.0, kernel='rbf', gamma='scale', probability=True, random_state=42)
# Naive Bayes gaussiano
clf_gnb = GaussianNB()
# Floresta aleatória (ensemble por Bagging)
clf_rf = RandomForestClassifier(n_estimators=100, max_depth=None, n_jobs=-1, random_state=42)
# Gradient Boosting baseado em histogramas (GBDT rápido semelhante ao LightGBM)
clf_hgb = HistGradientBoostingClassifier(learning_rate=0.1, max_iter=100, random_state=42)
4.2 Aprendizado supervisionado: Regressão
from sklearn.linear_model import LinearRegression, Ridge, Lasso
from sklearn.svm import SVR
from sklearn.ensemble import RandomForestRegressor, HistGradientBoostingRegressor
# Regressão linear por mínimos quadrados ordinários (OLS)
reg_lr = LinearRegression()
# Regressão Ridge (regularização L2 contra multicolinearidade)
reg_ridge = Ridge(alpha=1.0)
# Regressão Lasso (regularização L1 para seleção de atributos)
reg_lasso = Lasso(alpha=0.1)
# Regressão por vetores de suporte (SVR)
reg_svr = SVR(kernel='rbf', C=1.0, epsilon=0.1)
# Regressor de floresta aleatória
reg_rf = RandomForestRegressor(n_estimators=100, n_jobs=-1, random_state=42)
4.3 Aprendizado não supervisionado: Agrupamento e redução de dimensionalidade
from sklearn.cluster import KMeans, DBSCAN
from sklearn.decomposition import PCA
# Agrupamento K-Means
kmeans = KMeans(n_clusters=3, init='k-means++', n_init=10, random_state=42)
kmeans.fit(X)
cluster_labels = kmeans.labels_ # Atribuições de clústeres
cluster_centers = kmeans.cluster_centers_
# Agrupamento espacial baseado em densidade (DBSCAN: resistente a ruídos)
dbscan = DBSCAN(eps=0.5, min_samples=5)
db_labels = dbscan.fit_predict(X) # -1 identifica ruídos/outliers
# Análise de componentes principais (PCA): retém 95% da variância
pca = PCA(n_components=0.95)
X_pca = pca.fit_transform(X)
print("Componentes retidos:", pca.n_components_)
print("Razão de variância explicada:", pca.explained_variance_ratio_)
5. Operações da API unificada
| Operação | Método canônico | Tipo de objeto | Semântica e valor retornado |
|---|---|---|---|
| Ajustar (Fit) | estimator.fit(X, y) |
Todos os estimadores | Estima parâmetros a partir dos dados de treino; retorna self |
| Prever (Predict) | predictor.predict(X) |
Todos os preditores | Gera rótulos de classe discretos ou valores contínuos |
| Probabilidade | predictor.predict_proba(X) |
Classificadores | Gera matriz com a distribuição de probabilidades a posteriori |
| Distância de decisão | predictor.decision_function(X) |
Modelos lineares / SVM | Distância com sinal das amostras até o hiperplano separador |
| Transformar | transformer.transform(X) |
Todos os transformadores | Projeta atributos utilizando os parâmetros aprendidos |
| Ajustar e transformar | transformer.fit_transform(X) |
Todos os transformadores | Calcula parâmetros e transforma em uma única etapa otimizada |
| Pontuação padrão | estimator.score(X, y) |
Classificadores / Regressores | Acurácia para classificação; coeficiente de determinação $R^2$ para regressão |
6. Métricas de avaliação (sklearn.metrics)
6.1 Métricas de classificação
from sklearn.metrics import (
accuracy_score, precision_score, recall_score, f1_score,
roc_auc_score, confusion_matrix, classification_report,
ConfusionMatrixDisplay
)
# 1. Métricas de rótulos discretos (especifique average em multiclasse)
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. Métricas de ranking contínuo (ROC-AUC requer probabilidades)
y_prob = clf.predict_proba(X_test)[:, 1] # Probabilidades da classe positiva
auc = roc_auc_score(y_test, y_prob)
# 3. Matriz de confusão e relatório detalhado de classificação
cm = confusion_matrix(y_test, y_pred)
print(classification_report(y_test, y_pred))
# 4. Visualização gráfica da matriz de confusão
disp = ConfusionMatrixDisplay(confusion_matrix=cm)
disp.plot()
6.2 Métricas de regressão
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) # Raiz do erro quadrático médio (RMSE)
r2 = r2_score(y_test, y_pred) # Coeficiente de determinação R²
6.3 Métricas de agrupamento (Clustering)
from sklearn.metrics import (
adjusted_rand_score, homogeneity_score, v_measure_score, silhouette_score
)
# Validação externa (quando rótulos verdadeiros estão disponíveis)
ari = adjusted_rand_score(y_true, cluster_labels) # Intervalo: [-1, 1], quanto maior melhor
homo = homogeneity_score(y_true, cluster_labels) # Intervalo: [0, 1]
vm = v_measure_score(y_true, cluster_labels) # Média harmônica de homogeneidade e completude
# Validação interna (geométrica, sem necessidade de rótulos reais)
sil = silhouette_score(X, cluster_labels) # Intervalo: [-1, 1], próximo a 1 indica grupos bem separados
7. Validação cruzada e ajuste de hiperparâmetros (sklearn.model_selection)
7.1 Validação cruzada (Cross-Validation)
from sklearn.model_selection import cross_val_score, cross_validate, StratifiedKFold
# Validação cruzada K-Fold padrão
scores = cross_val_score(clf, X, y, cv=5, scoring='accuracy')
print(f"Acurácia 5-Fold CV: {scores.mean():.4f} (±{scores.std():.4f})")
# Gerador K-Fold estratificado
skf = StratifiedKFold(n_splits=5, shuffle=True, random_state=42)
scores_skf = cross_val_score(clf, X, y, cv=skf, scoring='f1_macro')
# Avaliação conjunta com múltiplas métricas
multi_scores = cross_validate(
clf, X, y, cv=5,
scoring=['accuracy', 'roc_auc'],
return_train_score=False
)
print("AUC média de validação:", multi_scores['test_roc_auc'].mean())
7.2 Busca em grade e busca aleatória
from sklearn.model_selection import GridSearchCV, RandomizedSearchCV
from scipy.stats import randint
# 1. Busca exaustiva em grade (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("Melhores parâmetros:", grid.best_params_)
best_model = grid.best_estimator_
# 2. Busca aleatória de hiperparâmetros (para espaços de busca grandes)
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, # Número de combinações aleatórias de parâmetros
cv=5,
scoring='accuracy',
random_state=42,
n_jobs=-1
)
rand_search.fit(X_train, y_train)
print("Melhores parâmetros da busca aleatória:", rand_search.best_params_)
8. Melhores práticas para produção: Pipeline & ColumnTransformer
8.1 Por que Pipelines são obrigatórios
Aplicar transformações ou imputações de dados globalmente antes da divisão gera Vazamento de Dados (Data Leakage): as informações dos conjuntos de validação contaminam os dados de treino, gerando métricas ilusórias que falham em ambiente de produção.
Pipeline integra etapas de pré-processamento e estimadores em uma unidade atômica livre de vazamentos. Durante a validação cruzada, os transformadores são ajustados estritamente apenas nos dados de treino de cada partição.
8.2 Exemplo de ColumnTransformer para produção
Dados tabulares reais contêm uma combinação de colunas numéricas contínuas e variáveis categóricas:
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. Particionar explicitamente os nomes das colunas
numeric_features = ['age', 'income', 'credit_score']
categorical_features = ['gender', 'occupation', 'city']
# 2. Sub-pipeline numérico: imputação pela mediana -> escalonamento padrão
numeric_transformer = Pipeline(steps=[
('imputer', SimpleImputer(strategy='median')),
('scaler', StandardScaler())
])
# 3. Sub-pipeline categórico: imputação por constante -> One-Hot encoding
categorical_transformer = Pipeline(steps=[
('imputer', SimpleImputer(strategy='constant', fill_value='missing')),
('onehot', OneHotEncoder(handle_unknown='ignore', sparse_output=False))
])
# 4. Integrar colunas em um ColumnTransformer unificado
preprocessor = ColumnTransformer(transformers=[
('num', numeric_transformer, numeric_features),
('cat', categorical_transformer, categorical_features)
])
# 5. Montar pipeline completo do modelo
full_pipeline = Pipeline(steps=[
('preprocessor', preprocessor),
('classifier', RandomForestClassifier(n_estimators=100, random_state=42))
])
# 6. Ajuste e inferência atômicos (vazamento zero, deploy estável)
full_pipeline.fit(X_train_df, y_train)
y_pred = full_pipeline.predict(X_test_df)
print("Acurácia de teste da Pipeline:", full_pipeline.score(X_test_df, y_test))