umap-learn

¿Qué hace umap-learn?

Descripción general

UMAP (Uniform Manifold Approximation and Projection) es una técnica de reducción de dimensionalidad para visualización y reducción de dimensionalidad no lineal en general. Aplica este skill para embeddings rápidos y escalables que preservan la estructura local y global, aprendizaje supervisado y preprocesamiento para clustering.

Inicio rápido

Instalación

Versión estable actual: umap-learn 0.5.12 (publicada en abril de 2026). Requiere Python 3.9+ y depende de scikit-learn>=1.6, numba, pynndescent, numpy y scipy. Fija una versión verificada:

uv pip install umap-learn==0.5.12

Uso básico

UMAP sigue las convenciones de scikit-learn y se puede usar como reemplazo directo de t-SNE o PCA.

import umap
from sklearn.preprocessing import StandardScaler

# Preparar datos (la estandarización es esencial)
scaled_data = StandardScaler().fit_transform(data)

# Método 1: Paso único (ajustar y transformar)
embedding = umap.UMAP().fit_transform(scaled_data)

# Método 2: Pasos separados (para reutilizar el modelo entrenado)
reducer = umap.UMAP(random_state=42)
reducer.fit(scaled_data)
embedding = reducer.embedding_  # Acceder al embedding entrenado

Requisito de preprocesamiento: Ajusta el preprocesamiento a la métrica. Para métricas numéricas de tipo euclidiano, escala las características antes de ajustar para que las columnas de alta varianza no dominen. Para flujos de trabajo con cosine, binarios, distancia precomputada o características mixtas, elige un preprocesamiento que coincida con la métrica en lugar de estandarizar ciegamente cada columna.

Flujo de trabajo típico

import umap
import matplotlib.pyplot as plt
from sklearn.preprocessing import StandardScaler

# 1. Preprocesar datos
scaler = StandardScaler()
scaled_data = scaler.fit_transform(raw_data)

# 2. Crear y ajustar UMAP
reducer = umap.UMAP(
    n_neighbors=15,
    min_dist=0.1,
    n_components=2,
    metric='euclidean',
    random_state=42
)
embedding = reducer.fit_transform(scaled_data)

# 3. Visualizar
plt.scatter(embedding[:, 0], embedding[:, 1], c=labels, cmap='Spectral', s=5)
plt.colorbar()
plt.title('Embedding UMAP')
plt.show()

Guía de ajuste de parámetros

UMAP tiene cuatro parámetros principales que controlan el comportamiento del embedding. Comprenderlos es crucial para un uso efectivo.

n_neighbors (valor predeterminado: 15)

Propósito: Equilibra la estructura local frente a la global en el embedding.

Cómo funciona: Controla el tamaño del vecindario local que UMAP examina al aprender la estructura de la variedad.

Efectos según el valor:

• Valores bajos (2-5): Enfatizan el detalle local fino, pero pueden fragmentar los datos en componentes desconectados
• Valores medios (15-20): Vista equilibrada de la estructura local y las relaciones globales (punto de partida recomendado)
• Valores altos (50-200): Priorizan la estructura topológica amplia a expensas de los detalles finos

Recomendación: Comienza con 15 y ajusta según los resultados. Aumenta para obtener más estructura global, disminuye para obtener más detalle local.

min_dist (valor predeterminado: 0.1)

Propósito: Controla qué tan juntos se agrupan los puntos en el espacio de baja dimensionalidad.

Cómo funciona: Establece la distancia mínima que se permite que los puntos estén separados en la representación de salida.

Efectos según el valor:

• Valores bajos (0.0-0.1): Crea embeddings agrupados útiles para clustering; revela detalles topológicos finos
• Valores altos (0.5-0.99): Evita el empaquetamiento apretado; enfatiza la preservación topológica amplia sobre la estructura local

Recomendación: Usa 0.0 para aplicaciones de clustering, 0.1-0.3 para visualización, 0.5+ para estructura suelta.

n_components (valor predeterminado: 2)

Propósito: Determina la dimensionalidad del espacio de salida del embedding.

Característica clave: A diferencia de t-SNE, UMAP escala bien en la dimensión del embedding, lo que permite su uso más allá de la visualización.

Usos comunes:

• 2-3 dimensiones: Visualización
• 5-10 dimensiones: Preprocesamiento para clustering (preserva mejor la densidad que 2D)
• 10-50 dimensiones: Ingeniería de características para modelos de ML posteriores

Recomendación: Usa 2 para visualización, 5-10 para clustering, valores más altos para pipelines de ML.

metric (valor predeterminado: 'euclidean')

Propósito: Especifica cómo se calcula la distancia entre los puntos de datos de entrada.

Métricas compatibles:

• Variantes de Minkowski: euclidean, manhattan, chebyshev
• Métricas espaciales: canberra, braycurtis, haversine
• Métricas de correlación: cosine, correlation (buenas para embeddings de texto/documentos)
• Métricas de datos binarios: hamming, jaccard, dice, russellrao, kulsinski, rogerstanimoto, sokalmichener, sokalsneath, yule
• Métricas personalizadas: Funciones de distancia definidas por el usuario a través de Numba

Recomendación: Usa euclidean para datos numéricos, cosine para vectores de texto/documentos, hamming para datos binarios.

Ejemplo de ajuste de parámetros

# Para visualización con énfasis en la estructura local
umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='euclidean')

# Para preprocesamiento de clustering
umap.UMAP(n_neighbors=30, min_dist=0.0, n_components=10, metric='euclidean')

# Para embeddings de documentos
umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='cosine')

# Para preservar la estructura global
umap.UMAP(n_neighbors=100, min_dist=0.5, n_components=2, metric='euclidean')

Reducción de dimensionalidad supervisada y semisupervisada

UMAP admite la incorporación de información de etiquetas para guiar el proceso de embedding, lo que permite la separación de clases mientras se preserva la estructura interna.

UMAP supervisado

Pasa las etiquetas objetivo a través del parámetro y al ajustar:

# Reducción de dimensionalidad supervisada
embedding = umap.UMAP().fit_transform(data, y=labels)

Beneficios clave:

• Logra clases claramente separadas
• Preserva la estructura interna dentro de cada clase
• Mantiene relaciones globales entre clases

UMAP semisupervisado

Para etiquetas parciales, marca los puntos no etiquetados con -1 siguiendo la convención de scikit-learn:

# Crear etiquetas semisupervisadas
semi_labels = labels.copy()
semi_labels[unlabeled_indices] = -1

# Ajustar con etiquetas parciales
embedding = umap.UMAP().fit_transform(data, y=semi_labels)

Cuándo usarlo: Cuando el etiquetado es costoso o tienes más datos que etiquetas disponibles.

UMAP para clustering

UMAP sirve como preprocesamiento efectivo para algoritmos de clustering basados en densidad como HDBSCAN, superando la maldición de la dimensionalidad.

Mejores prácticas para clustering

Principio clave: Configura UMAP de manera diferente para clustering que para visualización.

Parámetros recomendados:

• n_neighbors: Aumenta a ~30 (el valor predeterminado de 15 es demasiado local y puede crear clusters artificiales de grano fino)
• min_dist: Establece a 0.0 (empaqueta los puntos densamente dentro de los clusters para límites más claros)
• n_components: Usa 5-10 dimensiones (mantiene el rendimiento mientras mejora la preservación de la densidad en comparación con 2D)

Flujo de trabajo de clustering

Instala HDBSCAN por separado para clustering basado en densidad:

uv pip install hdbscan

import umap
import hdbscan
from sklearn.preprocessing import StandardScaler

# 1. Preprocesar datos
scaled_data = StandardScaler().fit_transform(data)

# 2. UMAP con parámetros optimizados para clustering
reducer = umap.UMAP(
    n_neighbors=30,
    min_dist=0.0,
    n_components=10,  # Mayor que 2 para mejor preservación de la densidad
    metric='euclidean',
    random_state=42
)
embedding = reducer.fit_transform(scaled_data)

# 3. Aplicar clustering HDBSCAN
clusterer = hdbscan.HDBSCAN(
    min_cluster_size=15,
    min_samples=5,
    metric='euclidean'
)
labels = clusterer.fit_predict(embedding)

# 4. Evaluar
from sklearn.metrics import adjusted_rand_score
score = adjusted_rand_score(true_labels, labels)
print(f"Puntuación Rand ajustada: {score:.3f}")
print(f"Número de clusters: {len(set(labels)) - (1 if -1 in labels else 0)}")
print(f"Puntos de ruido: {sum(labels == -1)}")

Visualización después del clustering

# Crear embedding 2D para visualización (separado del clustering)
vis_reducer = umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, random_state=42)
vis_embedding = vis_reducer.fit_transform(scaled_data)

# Graficar con etiquetas de cluster
import matplotlib.pyplot as plt
plt.scatter(vis_embedding[:, 0], vis_embedding[:, 1], c=labels, cmap='Spectral', s=5)
plt.colorbar()
plt.title('Visualización UMAP con clusters HDBSCAN')
plt.show()

Advertencia importante: UMAP no preserva completamente la densidad y puede crear divisiones artificiales de clusters. Siempre valida y explora los clusters resultantes.

Transformar nuevos datos

UMAP permite el preprocesamiento de nuevos datos a través de su método transform(), lo que permite que los modelos entrenados proyecten datos no vistos en el espacio de embedding aprendido.

Uso básico de transformación

# Entrenar con datos de entrenamiento
trans = umap.UMAP(n_neighbors=15, random_state=42).fit(X_train)

# Transformar datos de prueba
test_embedding = trans.transform(X_test)

Integración con pipelines de machine learning

from sklearn.svm import SVC
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler
import umap

# Dividir datos
X_train, X_test, y_train, y_test = train_test_split(data, labels, test_size=0.2)

# Preprocesar
scaler = StandardScaler()
X_train_scaled = scaler.fit_transform(X_train)
X_test_scaled = scaler.transform(X_test)

# Entrenar UMAP
reducer = umap.UMAP(n_components=10, random_state=42)
X_train_embedded = reducer.fit_transform(X_train_scaled)
X_test_embedded = reducer.transform(X_test_scaled)

# Entrenar clasificador en embeddings
clf = SVC()
clf.fit(X_train_embedded, y_train)
accuracy = clf.score(X_test_embedded, y_test)
print(f"Precisión en prueba: {accuracy:.3f}")

Consideraciones importantes

Consistencia de datos: El método transform asume que la distribución general en el espacio de alta dimensionalidad es consistente entre los datos de entrenamiento y prueba. Cuando esta suposición falla, considera usar UMAP paramétrico en su lugar.

Rendimiento: Las operaciones de transformación son eficientes (típicamente <1 segundo), aunque las llamadas iniciales pueden ser más lentas debido a la compilación JIT de Numba.

Compatibilidad con scikit-learn: UMAP sigue las convenciones estándar de sklearn y funciona en pipelines. Las versiones recientes 0.5.x también mejoraron el soporte de nombres de características y la compatibilidad con las API de validación actuales de scikit-learn:

from sklearn.pipeline import Pipeline

pipeline = Pipeline([
    ('scaler', StandardScaler()),
    ('umap', umap.UMAP(n_components=10)),
    ('classifier', SVC())
])

pipeline.fit(X_train, y_train)
predictions = pipeline.predict(X_test)
feature_names = pipeline.named_steps['umap'].get_feature_names_out()

Características avanzadas

UMAP paramétrico

El UMAP paramétrico reemplaza la optimización directa del embedding con una función de mapeo de red neuronal aprendida.

Diferencias clave con UMAP estándar:

• Usa TensorFlow/Keras para entrenar redes codificadoras
• Permite la transformación eficiente de nuevos datos
• Soporta reconstrucción a través de redes decodificadoras (transformación inversa)
• Permite arquitecturas personalizadas (CNN para imágenes, RNN para secuencias)

Instalación:

uv pip install "umap-learn[parametric-umap]==0.5.12"
# Instala el extra de UMAP paramétrico basado en TensorFlow.

Uso básico:

from umap.parametric_umap import ParametricUMAP

# Arquitectura predeterminada (red totalmente conectada de 3 capas de 100 neuronas)
embedder = ParametricUMAP()
embedding = embedder.fit_transform(data)

# Transformar nuevos datos eficientemente
new_embedding = embedder.transform(new_data)

Arquitectura personalizada:

import tensorflow as tf

# Definir codificador personalizado
encoder = tf.keras.Sequential([
    tf.keras.layers.InputLayer(shape=(input_dim,)),
    tf.keras.layers.Dense(128, activation='relu'),
    tf.keras.layers.Dense(64, activation='relu'),
    tf.keras.layers.Dense(2)  # Dimensión de salida
])

embedder = ParametricUMAP(encoder=encoder, dims=(input_dim,))
embedding = embedder.fit_transform(data)

Persistencia: Guarda UMAP paramétrico con sus métodos integrados compatibles con Keras en lugar de pickle simple:

embedder.save("parametric_umap_model", exclude_raw_data=True)

from umap.parametric_umap import load_ParametricUMAP
loaded = load_ParametricUMAP("parametric_umap_model")
new_embedding = loaded.transform(new_data)

Las correcciones recientes de 0.5.12 incluyen mejoras de estabilidad en el reentrenamiento de UMAP paramétrico y correcciones de gradiente de métrica, por lo que es preferible fijar la versión actual para flujos de trabajo con redes neuronales.

Cuándo usar UMAP paramétrico:

• Necesitas transformación eficiente de nuevos datos después del entrenamiento
• Requieres capacidades de reconstrucción (transformaciones inversas)
• Deseas combinar UMAP con autoencoders
• Trabajas con tipos de datos complejos (imágenes, secuencias) que se benefician de arquitecturas especializadas

Transformaciones inversas

Las transformaciones inversas permiten la reconstrucción de datos de alta dimensionalidad a partir de embeddings de baja dimensionalidad.

Uso básico:

reducer = umap.UMAP()
embedding = reducer.fit_transform(data)

# Reconstruir datos de alta dimensionalidad a partir de coordenadas de embedding
reconstructed = reducer.inverse_transform(embedding)

Limitaciones importantes:

• Operación computacionalmente costosa
• Funciona mal fuera del casco convexo del embedding
• La precisión disminuye en regiones con espacios entre clusters

Ejemplo: Explorar el espacio de embedding:

import numpy as np

# Crear cuadrícula de puntos en el espacio de embedding
x = np.linspace(embedding[:, 0].min(), embedding[:, 0].max(), 10)
y = np.linspace(embedding[:, 1].min(), embedding[:, 1].max(), 10)
xx, yy = np.meshgrid(x, y)
grid_points = np.c_[xx.ravel(), yy.ravel()]

# Reconstruir muestras de la cuadrícula
reconstructed_samples = reducer.inverse_transform(grid_points)

AlignedUMAP

Para conjuntos de datos temporales o relacionados que necesitan un sistema de coordenadas compartido (experimentos de series temporales, lotes), usa umap.AlignedUMAP().fit(datasets, relations=relations), donde relations mapea índices de muestra entre conjuntos de datos consecutivos y es necesario para una alineación significativa. Los parámetros, métodos y un ejemplo práctico están en references/api_reference.md bajo "Clase AlignedUMAP" y "Ejemplos de uso".

Reproducibilidad

Para garantizar resultados reproducibles, siempre establece el parámetro random_state:

reduc

... [truncado para traducción]