O que umap-learn faz?
Visão Geral
UMAP (Aproximação e Projeção de Variedades Uniformes) é uma técnica de redução de dimensionalidade para visualização e redução de dimensionalidade não linear em geral. Use este skill para embeddings rápidos e escaláveis que preservam a estrutura local e global, aprendizado supervisionado e pré-processamento para clusterização.
Início Rápido
Instalação
Versão estável atual: umap-learn 0.5.12 (lançada em abril de 2026). Requer Python 3.9+ e depende de scikit-learn>=1.6, numba, pynndescent, numpy e scipy. Fixe em uma versão verificada:
uv pip install umap-learn==0.5.12
Uso Básico
O UMAP segue as convenções do scikit-learn e pode ser usado como substituto direto para t-SNE ou PCA.
import umap
from sklearn.preprocessing import StandardScaler
# Preparar dados (padronização é essencial)
dados_escalados = StandardScaler().fit_transform(dados)
# Método 1: Etapa única (ajustar e transformar)
embedding = umap.UMAP().fit_transform(dados_escalados)
# Método 2: Etapas separadas (para reutilizar modelo treinado)
redutor = umap.UMAP(random_state=42)
redutor.fit(dados_escalados)
embedding = redutor.embedding_ # Acessar o embedding treinado
Requisito de pré-processamento: Adeque o pré-processamento à métrica. Para métricas numéricas do tipo euclidiano, escale os recursos antes do ajuste para que colunas de alta variância não dominem. Para fluxos de trabalho com cosseno, binário, distância pré-computada ou recursos mistos, escolha um pré-processamento que corresponda à métrica em vez de padronizar cegamente cada coluna.
Fluxo de Trabalho Típico
import umap
import matplotlib.pyplot as plt
from sklearn.preprocessing import StandardScaler
# 1. Pré-processar dados
scaler = StandardScaler()
dados_escalados = scaler.fit_transform(dados_brutos)
# 2. Criar e ajustar UMAP
redutor = umap.UMAP(
n_neighbors=15,
min_dist=0.1,
n_components=2,
metric='euclidean',
random_state=42
)
embedding = redutor.fit_transform(dados_escalados)
# 3. Visualizar
plt.scatter(embedding[:, 0], embedding[:, 1], c=rotulos, cmap='Spectral', s=5)
plt.colorbar()
plt.title('Embedding UMAP')
plt.show()
Guia de Ajuste de Parâmetros
O UMAP possui quatro parâmetros principais que controlam o comportamento do embedding. Compreendê-los é crucial para um uso eficaz.
n_neighbors (padrão: 15)
Finalidade: Equilibra a estrutura local versus global no embedding.
Como funciona: Controla o tamanho da vizinhança local que o UMAP examina ao aprender a estrutura da variedade.
Efeitos por valor:
- Valores baixos (2-5): Enfatiza detalhes locais finos, mas pode fragmentar os dados em componentes desconectados
- Valores médios (15-20): Visão equilibrada da estrutura local e relações globais (ponto de partida recomendado)
- Valores altos (50-200): Prioriza a estrutura topológica ampla em detrimento de detalhes finos
Recomendação: Comece com 15 e ajuste com base nos resultados. Aumente para mais estrutura global, diminua para mais detalhes locais.
min_dist (padrão: 0.1)
Finalidade: Controla o quão próximos os pontos se agrupam no espaço de baixa dimensionalidade.
Como funciona: Define a distância mínima que os pontos podem ter na representação de saída.
Efeitos por valor:
- Valores baixos (0.0-0.1): Cria embeddings agrupados úteis para clusterização; revela detalhes topológicos finos
- Valores altos (0.5-0.99): Evita agrupamento apertado; enfatiza a preservação topológica ampla em vez da estrutura local
Recomendação: Use 0.0 para aplicações de clusterização, 0.1-0.3 para visualização, 0.5+ para estrutura solta.
n_components (padrão: 2)
Finalidade: Determina a dimensionalidade do espaço de saída do embedding.
Característica chave: Ao contrário do t-SNE, o UMAP escala bem na dimensão do embedding, permitindo uso além da visualização.
Usos comuns:
- 2-3 dimensões: Visualização
- 5-10 dimensões: Pré-processamento para clusterização (preserva melhor a densidade do que 2D)
- 10-50 dimensões: Engenharia de recursos para modelos de ML downstream
Recomendação: Use 2 para visualização, 5-10 para clusterização, valores mais altos para pipelines de ML.
metric (padrão: 'euclidean')
Finalidade: Especifica como a distância é calculada entre pontos de dados de entrada.
Métricas suportadas:
- Variantes de Minkowski: euclidean, manhattan, chebyshev
- Métricas espaciais: canberra, braycurtis, haversine
- Métricas de correlação: cosine, correlation (boa para embeddings de texto/documento)
- Métricas para dados binários: hamming, jaccard, dice, russellrao, kulsinski, rogerstanimoto, sokalmichener, sokalsneath, yule
- Métricas personalizadas: Funções de distância definidas pelo usuário via Numba
Recomendação: Use euclidean para dados numéricos, cosine para vetores de texto/documento, hamming para dados binários.
Exemplo de Ajuste de Parâmetros
# Para visualização com ênfase na estrutura local
umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='euclidean')
# Para pré-processamento de clusterização
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 estrutura global
umap.UMAP(n_neighbors=100, min_dist=0.5, n_components=2, metric='euclidean')
Redução de Dimensionalidade Supervisionada e Semi-Supervisionada
O UMAP suporta a incorporação de informações de rótulos para guiar o processo de embedding, permitindo a separação de classes enquanto preserva a estrutura interna.
UMAP Supervisionado
Passe os rótulos alvo através do parâmetro y ao ajustar:
# Redução de dimensionalidade supervisionada
embedding = umap.UMAP().fit_transform(dados, y=rotulos)
Benefícios chave:
- Alcança classes claramente separadas
- Preserva a estrutura interna dentro de cada classe
- Mantém relações globais entre classes
UMAP Semi-Supervisionado
Para rótulos parciais, marque pontos não rotulados com -1 seguindo a convenção do scikit-learn:
# Criar rótulos semi-supervisionados
rotulos_semi = rotulos.copy()
rotulos_semi[indices_nao_rotulados] = -1
# Ajustar com rótulos parciais
embedding = umap.UMAP().fit_transform(dados, y=rotulos_semi)
Quando usar: Quando a rotulagem é cara ou você tem mais dados do que rótulos disponíveis.
UMAP para Clusterização
O UMAP serve como pré-processamento eficaz para algoritmos de clusterização baseados em densidade, como HDBSCAN, superando a maldição da dimensionalidade.
Melhores Práticas para Clusterização
Princípio chave: Configure o UMAP de forma diferente para clusterização do que para visualização.
Parâmetros recomendados:
- n_neighbors: Aumente para ~30 (o padrão 15 é muito local e pode criar agrupamentos finos artificiais)
- min_dist: Defina como 0.0 (agrupa pontos densamente dentro dos clusters para limites mais claros)
- n_components: Use 5-10 dimensões (mantém o desempenho enquanto melhora a preservação da densidade em relação a 2D)
Fluxo de Trabalho de Clusterização
Instale o HDBSCAN separadamente para clusterização baseada em densidade:
uv pip install hdbscan
import umap
import hdbscan
from sklearn.preprocessing import StandardScaler
# 1. Pré-processar dados
dados_escalados = StandardScaler().fit_transform(dados)
# 2. UMAP com parâmetros otimizados para clusterização
redutor = umap.UMAP(
n_neighbors=30,
min_dist=0.0,
n_components=10, # Maior que 2 para melhor preservação de densidade
metric='euclidean',
random_state=42
)
embedding = redutor.fit_transform(dados_escalados)
# 3. Aplicar clusterização HDBSCAN
clusterizador = hdbscan.HDBSCAN(
min_cluster_size=15,
min_samples=5,
metric='euclidean'
)
rotulos = clusterizador.fit_predict(embedding)
# 4. Avaliar
from sklearn.metrics import adjusted_rand_score
pontuacao = adjusted_rand_score(rotulos_verdadeiros, rotulos)
print(f"Pontuação Rand Ajustada: {pontuacao:.3f}")
print(f"Número de clusters: {len(set(rotulos)) - (1 if -1 in rotulos else 0)}")
print(f"Pontos de ruído: {sum(rotulos == -1)}")
Visualização Após Clusterização
# Criar embedding 2D para visualização (separado da clusterização)
vis_redutor = umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, random_state=42)
vis_embedding = vis_redutor.fit_transform(dados_escalados)
# Plotar com rótulos dos clusters
import matplotlib.pyplot as plt
plt.scatter(vis_embedding[:, 0], vis_embedding[:, 1], c=rotulos, cmap='Spectral', s=5)
plt.colorbar()
plt.title('Visualização UMAP com Clusters HDBSCAN')
plt.show()
Aviso importante: O UMAP não preserva completamente a densidade e pode criar divisões artificiais de clusters. Sempre valide e explore os clusters resultantes.
Transformando Novos Dados
O UMAP permite o pré-processamento de novos dados através do método transform(), permitindo que modelos treinados projetem dados não vistos no espaço de embedding aprendido.
Uso Básico do Transform
# Treinar nos dados de treino
trans = umap.UMAP(n_neighbors=15, random_state=42).fit(X_treino)
# Transformar dados de teste
embedding_teste = trans.transform(X_teste)
Integração com Pipelines de Aprendizado de Máquina
from sklearn.svm import SVC
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler
import umap
# Dividir dados
X_treino, X_teste, y_treino, y_teste = train_test_split(dados, rotulos, test_size=0.2)
# Pré-processar
scaler = StandardScaler()
X_treino_escalado = scaler.fit_transform(X_treino)
X_teste_escalado = scaler.transform(X_teste)
# Treinar UMAP
redutor = umap.UMAP(n_components=10, random_state=42)
X_treino_embed = redutor.fit_transform(X_treino_escalado)
X_teste_embed = redutor.transform(X_teste_escalado)
# Treinar classificador nos embeddings
clf = SVC()
clf.fit(X_treino_embed, y_treino)
acuracia = clf.score(X_teste_embed, y_teste)
print(f"Acurácia no teste: {acuracia:.3f}")
Considerações Importantes
Consistência dos dados: O método transform assume que a distribuição geral no espaço de alta dimensionalidade é consistente entre os dados de treino e teste. Quando essa suposição falhar, considere usar Parametric UMAP.
Desempenho: As operações de transform são eficientes (tipicamente <1 segundo), embora as chamadas iniciais possam ser mais lentas devido à compilação JIT do Numba.
Compatibilidade com scikit-learn: O UMAP segue as convenções padrão do sklearn e funciona em pipelines. Lançamentos recentes 0.5.x também melhoraram o suporte a nomes de recursos e a compatibilidade com APIs de validação atuais do scikit-learn:
from sklearn.pipeline import Pipeline
pipeline = Pipeline([
('scaler', StandardScaler()),
('umap', umap.UMAP(n_components=10)),
('classifier', SVC())
])
pipeline.fit(X_treino, y_treino)
predicoes = pipeline.predict(X_teste)
nomes_recursos = pipeline.named_steps['umap'].get_feature_names_out()
Recursos Avançados
UMAP Paramétrico
O UMAP Paramétrico substitui a otimização direta de embedding por uma função de mapeamento de rede neural aprendida.
Principais diferenças do UMAP padrão:
- Usa TensorFlow/Keras para treinar redes codificadoras
- Permite transformação eficiente de novos dados
- Suporta reconstrução através de redes decodificadoras (transformação inversa)
- Permite arquiteturas personalizadas (CNNs para imagens, RNNs para sequências)
Instalação:
uv pip install "umap-learn[parametric-umap]==0.5.12"
# Instala o extra Parametric UMAP baseado em TensorFlow.
Uso básico:
from umap.parametric_umap import ParametricUMAP
# Arquitetura padrão (rede totalmente conectada de 3 camadas com 100 neurônios)
incorporador = ParametricUMAP()
embedding = incorporador.fit_transform(dados)
# Transformar novos dados eficientemente
novo_embedding = incorporador.transform(novos_dados)
Arquitetura personalizada:
import tensorflow as tf
# Definir codificador personalizado
codificador = tf.keras.Sequential([
tf.keras.layers.InputLayer(shape=(dimensao_entrada,)),
tf.keras.layers.Dense(128, activation='relu'),
tf.keras.layers.Dense(64, activation='relu'),
tf.keras.layers.Dense(2) # Dimensão de saída
])
incorporador = ParametricUMAP(encoder=codificador, dims=(dimensao_entrada,))
embedding = incorporador.fit_transform(dados)
Persistência: Salve UMAP Paramétrico com seus métodos integrados conscientes do Keras em vez de pickle simples:
incorporador.save("modelo_umap_parametrico", exclude_raw_data=True)
from umap.parametric_umap import load_ParametricUMAP
carregado = load_ParametricUMAP("modelo_umap_parametrico")
novo_embedding = carregado.transform(novos_dados)
As correções recentes na versão 0.5.12 incluem melhorias na estabilidade do treinamento do UMAP Paramétrico e correções de gradiente de métrica; portanto, prefira a versão fixa atual para fluxos de trabalho com redes neurais.
Quando usar UMAP Paramétrico:
- Precisa de transformação eficiente de novos dados após o treinamento
- Requer capacidades de reconstrução (transformações inversas)
- Deseja combinar UMAP com autoencoders
- Trabalha com tipos de dados complexos (imagens, sequências) que se beneficiam de arquiteturas especializadas
Transformações Inversas
Transformações inversas permitem a reconstrução de dados de alta dimensionalidade a partir de embeddings de baixa dimensionalidade.
Uso básico:
redutor = umap.UMAP()
embedding = redutor.fit_transform(dados)
# Reconstruir dados de alta dimensionalidade a partir das coordenadas do embedding
reconstruido = redutor.inverse_transform(embedding)
Limitações importantes:
- Operação computacionalmente cara
- Funciona mal fora da envoltória convexa do embedding
- A precisão diminui em regiões com lacunas entre clusters
Exemplo: Explorando o espaço de embedding:
import numpy as np
# Criar grade de pontos no espaço 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)
pontos_grade = np.c_[xx.ravel(), yy.ravel()]
# Reconstruir amostras a partir da grade
amostras_reconstruidas = redutor.inverse_transform(pontos_grade)
AlignedUMAP
Para conjuntos de dados temporais ou relacionados que precisam de um sistema de coordenadas compartilhado (experimentos de séries temporais, lotes), use umap.AlignedUMAP().fit(conjuntos_dados, relations=relacoes), onde relacoes mapeia índices de amostra entre conjuntos consecutivos e é necessário para um alinhamento significativo. Parâmetros, métodos e um exemplo prático estão em references/api_reference.md sob "Classe AlignedUMAP" e "Exemplos de Uso".