Referencia rápida

Hoja de referencia de la API y flujo de trabajo de Scikit-Learn

Guía de referencia para Scikit-Learn: diseño unificado de API (Estimator, Transformer, Predictor), preparación de datos, ingeniería de características, modelos supervisados y no supervisados, validación cruzada, métricas de evaluación y Pipelines sin fuga de datos.

· Publicado · Actualizado

Scikit-Learn (sklearn) es la biblioteca de código abierto fundamental de Python para modelado estadístico y aprendizaje automático tradicional, construida sobre NumPy, SciPy y Matplotlib. Su principal ventaja radica en un patrón de diseño con tres interfaces estrictamente unificado:

  • Estimator (Estimador): Aprende los parámetros del modelo a partir de los datos mediante fit(X, y).
  • Transformer (Transformador): Preprocesa y proyecta características mediante transform(X) y fit_transform(X).
  • Predictor (Predictor): Genera predicciones sobre nuevas muestras mediante predict(X), predict_proba(X) y score(X, y).

🔗 Hojas de referencia relacionadas: Hoja de referencia de NumPy · Hoja de referencia de Pandas · Algoritmos de aprendizaje supervisado · Métodos de análisis de datos · Hoja de referencia de Python


1. Ejemplo de inicio rápido de extremo a extremo

El siguiente script autónomo muestra el flujo de carga de datos, división estratificada, escalado de características, entrenamiento y evaluación del modelo:

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. Cargar datos
iris = load_iris()
X, y = iris.data, iris.target

# 2. División estratificada en entrenamiento y prueba
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42, stratify=y
)

# 3. Escalado de características (ajustar SOLO en entrenamiento para evitar fugas)
scaler = StandardScaler()
X_train_scaled = scaler.fit_transform(X_train)
X_test_scaled = scaler.transform(X_test)

# 4. Entrenar el estimador
knn = KNeighborsClassifier(n_neighbors=5)
knn.fit(X_train_scaled, y_train)

# 5. Predecir y evaluar
y_pred = knn.predict(X_test_scaled)
print(f"Exactitud: {accuracy_score(y_test, y_pred):.4f}")
print(classification_report(y_test, y_pred, target_names=iris.target_names))

2. Preparación y división de datos

Scikit-Learn requiere estructuras numéricas 2D: una matriz de características $X$ con forma (n_samples, n_features) y un vector objetivo $y$ con forma (n_samples,). Se admiten ndarrays de NumPy, matrices dispersas de SciPy (scipy.sparse) y DataFrames/Series de Pandas.

2.1 Conjuntos de datos integrados y generación sintética

from sklearn import datasets

# Conjuntos de datos pequeños de referencia (retorna objeto Bunch)
iris = datasets.load_iris()               # Clasificación multiclase
digits = datasets.load_digits()           # Imágenes de dígitos escritos a mano de 8x8
diabetes = datasets.load_diabetes()       # Punto de referencia para regresión
wine = datasets.load_wine()               # Análisis químico de vinos de 3 clases

# Conjuntos de datos de referencia reales (en caché local)
housing = datasets.fetch_california_housing()

# Generación de datos sintéticos para pruebas 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 División de datos (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,        # Proporción del conjunto de prueba (por defecto: 0.25)
    random_state=42,       # Semilla fija para reproducibilidad
    shuffle=True,          # Barajar muestras antes de dividir
    stratify=y             # Muy recomendado en clasificación: mantiene la proporción de clases
)

3. Ingeniería de características y preprocesamiento (sklearn.preprocessing & sklearn.impute)

Transformador Caso de uso Transformación matemática / Lógica Parámetros clave
StandardScaler Estandarización Z-score de variables numéricas $z = \frac{x - \mu}{\sigma}$ (media cero, varianza unitaria) with_mean=True, with_std=True
MinMaxScaler Escalado de características a un intervalo cerrado $x' = \frac{x - x_{\min}}{x_{\max} - x_{\min}} \cdot (\max - \min) + \min$ feature_range=(0, 1)
RobustScaler Escalado robusto frente a valores atípicos Escalado intercuartílico: $x' = \frac{x - Q_2}{Q_3 - Q_1}$ quantile_range=(25.0, 75.0)
Normalizer Normalización por fila para cada muestra Escala cada muestra a norma unitaria ($L_1$, $L_2$ o Max) norm='l2' ('l1', 'max')
Binarizer Binarización por umbral de variables continuas $x > \text{threshold} \Rightarrow 1$, en caso contrario $0$ threshold=0.0
SimpleImputer Imputación de valores faltantes Sustituye valores ausentes por media, mediana, moda o constante missing_values=np.nan, strategy='mean'
OneHotEncoder Codificación One-Hot de categorías nominales Convierte variables categóricas en columnas binarias ficticias drop='first', handle_unknown='ignore'
OrdinalEncoder Codificación ordinal de categorías ordenadas Convierte categorías en enteros ordenados $0, \dots, K-1$ categories='auto', encoded_missing_value
LabelEncoder Codificación de etiquetas para la variable objetivo $y$ Convierte etiquetas de texto a enteros $0 \dots C-1$ SOLO para el objetivo $y$, NUNCA para las características $X$
PolynomialFeatures Generación de características polinomiales y de interacción Genera términos de orden superior $[1, a, b, a^2, ab, b^2]$ degree=2, include_bias=False

3.1 Ejemplos de código de preprocesamiento

import numpy as np
from sklearn.preprocessing import (
    StandardScaler, MinMaxScaler, RobustScaler, Normalizer,
    Binarizer, OneHotEncoder, OrdinalEncoder, LabelEncoder, PolynomialFeatures
)
from sklearn.impute import SimpleImputer

# 1. Estandarización numérica (¡nunca ajustar en el conjunto de prueba!)
scaler = StandardScaler()
X_train_std = scaler.fit_transform(X_train)
X_test_std = scaler.transform(X_test)

# 2. Imputación de valores faltantes (estrategia 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. Codificación One-Hot (gestiona categorías no vistas en prueba)
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. Codificación de la variable objetivo
le = LabelEncoder()
y_train_enc = le.fit_transform(y_train)
y_test_enc = le.transform(y_test)

# 5. Expansión de características polinomiales
poly = PolynomialFeatures(degree=2, include_bias=False)
X_train_poly = poly.fit_transform(X_train)

4. Índice maestro de estimadores habituales

4.1 Aprendizaje supervisado: Clasificación

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

# Regresión logística (modelo lineal de referencia)
clf_lr = LogisticRegression(C=1.0, max_iter=200, random_state=42)

# K vecinos más cercanos (KNN)
clf_knn = KNeighborsClassifier(n_neighbors=5, metric='minkowski', p=2)

# Máquinas de vectores de soporte (núcleo RBF)
clf_svm = SVC(C=1.0, kernel='rbf', gamma='scale', probability=True, random_state=42)

# Naive Bayes gaussiano
clf_gnb = GaussianNB()

# Bosque aleatorio (ensamble de embolsado / Bagging)
clf_rf = RandomForestClassifier(n_estimators=100, max_depth=None, n_jobs=-1, random_state=42)

# Gradient Boosting basado en histogramas (GBDT rápido afín a LightGBM)
clf_hgb = HistGradientBoostingClassifier(learning_rate=0.1, max_iter=100, random_state=42)

4.2 Aprendizaje supervisado: Regresión

from sklearn.linear_model import LinearRegression, Ridge, Lasso
from sklearn.svm import SVR
from sklearn.ensemble import RandomForestRegressor, HistGradientBoostingRegressor

# Regresión lineal por mínimos cuadrados ordinarios (OLS)
reg_lr = LinearRegression()

# Regresión Ridge (regularización L2 contra multicolinealidad)
reg_ridge = Ridge(alpha=1.0)

# Regresión Lasso (regularización L1 para selección de variables)
reg_lasso = Lasso(alpha=0.1)

# Regresión con vectores de soporte (SVR)
reg_svr = SVR(kernel='rbf', C=1.0, epsilon=0.1)

# Regresor de bosque aleatorio
reg_rf = RandomForestRegressor(n_estimators=100, n_jobs=-1, random_state=42)

4.3 Aprendizaje no supervisado: Agrupamiento y reducción de dimensionalidad

from sklearn.cluster import KMeans, DBSCAN
from sklearn.decomposition import PCA

# Agrupamiento K-Means
kmeans = KMeans(n_clusters=3, init='k-means++', n_init=10, random_state=42)
kmeans.fit(X)
cluster_labels = kmeans.labels_        # Asignaciones de clústeres
cluster_centers = kmeans.cluster_centers_

# Clúster espacial basado en densidad (DBSCAN: tolerante al ruido)
dbscan = DBSCAN(eps=0.5, min_samples=5)
db_labels = dbscan.fit_predict(X)      # -1 representa valores atípicos (ruido)

# Análisis de componentes principales (PCA): retiene el 95% de varianza
pca = PCA(n_components=0.95)
X_pca = pca.fit_transform(X)
print("Componentes retenidos:", pca.n_components_)
print("Ratio de varianza explicada:", pca.explained_variance_ratio_)

5. Operaciones de la API unificada

Operación Método canónico Tipo de objeto Semántica y valor de retorno
Ajustar (Fit) estimator.fit(X, y) Todos los estimadores Estima parámetros a partir de datos de entrenamiento; retorna self
Predecir (Predict) predictor.predict(X) Todos los predictores Genera etiquetas de clase discretas o valores continuos
Probabilidad predictor.predict_proba(X) Clasificadores Calcula la matriz de distribución de probabilidad a posteriori
Distancia de decisión predictor.decision_function(X) Modelos lineales / SVM Distancia con signo de las muestras al hiperplano separador
Transformar transformer.transform(X) Todos los transformadores Proyecta características utilizando los parámetros aprendidos
Ajustar y transformar transformer.fit_transform(X) Todos los transformadores Calcula parámetros y transforma en un único paso optimizado
Puntuación por defecto estimator.score(X, y) Clasificadores / Regresores Exactitud en clasificación; coeficiente $R^2$ en regresión

6. Métricas de evaluación (sklearn.metrics)

6.1 Métricas de clasificación

from sklearn.metrics import (
    accuracy_score, precision_score, recall_score, f1_score,
    roc_auc_score, confusion_matrix, classification_report,
    ConfusionMatrixDisplay
)

# 1. Métricas de etiquetas discretas (especificar average en multiclase)
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 rango continuo (ROC-AUC requiere probabilidades estimadas)
y_prob = clf.predict_proba(X_test)[:, 1]   # Probabilidades de la clase positiva
auc = roc_auc_score(y_test, y_prob)

# 3. Matriz de confusión e informe completo de clasificación
cm = confusion_matrix(y_test, y_pred)
print(classification_report(y_test, y_pred))

# 4. Visualización de matriz de confusión
disp = ConfusionMatrixDisplay(confusion_matrix=cm)
disp.plot()

6.2 Métricas de regresión

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)  # Raíz del error cuadrático medio (RMSE)
r2 = r2_score(y_test, y_pred)                            # Coeficiente de determinación R²

6.3 Métricas de agrupamiento (Clustering)

from sklearn.metrics import (
    adjusted_rand_score, homogeneity_score, v_measure_score, silhouette_score
)

# Validación externa (cuando se dispone de etiquetas verdaderas)
ari = adjusted_rand_score(y_true, cluster_labels)       # Rango: [-1, 1], mayor es mejor
homo = homogeneity_score(y_true, cluster_labels)        # Rango: [0, 1]
vm = v_measure_score(y_true, cluster_labels)           # Media armónica entre homogeneidad y exhaustividad

# Validación interna (basada en geometría, sin etiquetas reales)
sil = silhouette_score(X, cluster_labels)              # Rango: [-1, 1], cercano a 1 indica grupos nítidos

7. Validación cruzada y ajuste de hiperparámetros (sklearn.model_selection)

7.1 Validación cruzada (Cross-Validation)

from sklearn.model_selection import cross_val_score, cross_validate, StratifiedKFold

# Validación cruzada K-Fold estándar
scores = cross_val_score(clf, X, y, cv=5, scoring='accuracy')
print(f"Exactitud 5-Fold CV: {scores.mean():.4f} (±{scores.std():.4f})")

# Generador 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')

# Evaluación conjunta multivariable
multi_scores = cross_validate(
    clf, X, y, cv=5,
    scoring=['accuracy', 'roc_auc'],
    return_train_score=False
)
print("AUC promedio de validación:", multi_scores['test_roc_auc'].mean())

7.2 Búsqueda en cuadrícula y búsqueda aleatoria

from sklearn.model_selection import GridSearchCV, RandomizedSearchCV
from scipy.stats import randint

# 1. Búsqueda exhaustiva en cuadrícula (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("Mejores parámetros:", grid.best_params_)
best_model = grid.best_estimator_

# 2. Búsqueda aleatoria de hiperparámetros (para espacios extensos)
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 combinaciones aleatorias
    cv=5,
    scoring='accuracy',
    random_state=42,
    n_jobs=-1
)
rand_search.fit(X_train, y_train)
print("Mejores parámetros de búsqueda aleatoria:", rand_search.best_params_)

8. Buenas prácticas en producción: Pipeline & ColumnTransformer

8.1 Por qué las Pipelines son obligatorias

Aplicar transformaciones o imputaciones globalmente antes de la división conduce a la fuga de datos (Data Leakage): la información de los pliegues de prueba contamina las estadísticas de entrenamiento, produciendo métricas offline artificialmente optimistas que fallan en producción.

Pipeline une transformadores y estimadores en una unidad atómica libre de fugas. En la validación cruzada, los transformadores se ajustan exclusivamente en cada pliegue de entrenamiento.

8.2 Receta de producción con ColumnTransformer

Los datos tabulares del mundo real combinan columnas numéricas continuas y variables 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. Separar explícitamente los nombres de las columnas
numeric_features = ['age', 'income', 'credit_score']
categorical_features = ['gender', 'occupation', 'city']

# 2. Sub-pipeline numérico: imputación por mediana -> escalado estándar
numeric_transformer = Pipeline(steps=[
    ('imputer', SimpleImputer(strategy='median')),
    ('scaler', StandardScaler())
])

# 3. Sub-pipeline categórico: imputación constante -> codificación One-Hot
categorical_transformer = Pipeline(steps=[
    ('imputer', SimpleImputer(strategy='constant', fill_value='missing')),
    ('onehot', OneHotEncoder(handle_unknown='ignore', sparse_output=False))
])

# 4. Integrar columnas en un ColumnTransformer unificado
preprocessor = ColumnTransformer(transformers=[
    ('num', numeric_transformer, numeric_features),
    ('cat', categorical_transformer, categorical_features)
])

# 5. Ensamblar la pipeline completa de extremo a extremo
full_pipeline = Pipeline(steps=[
    ('preprocessor', preprocessor),
    ('classifier', RandomForestClassifier(n_estimators=100, random_state=42))
])

# 6. Ajuste e inferencia atómicos (cero fugas, despliegue robusto)
full_pipeline.fit(X_train_df, y_train)
y_pred = full_pipeline.predict(X_test_df)
print("Exactitud de prueba del Pipeline:", full_pipeline.score(X_test_df, y_test))

Temas relacionados