# Umap Learn > Redução de dimensionalidade com UMAP. Aprendizado rápido e não-linear de variedades para visualização 2D/3D, pré-processamento de clustering (HDBSCAN), UMAP supervisionado/paramétrico, para dados de alta dimensionalidade. - Skill: `artubss/umap-learn` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add artubss/umap-learn` - Raw SKILL.md: https://api.skillmd.com/api/skills/artubss/umap-learn/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: artubss (https://skillmd.com/u/artubss) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/artubss/umap-learn --- # UMAP-Learn ## Visão Geral UMAP (Uniform Manifold Approximation and Projection) é uma técnica de redução de dimensionalidade para visualização e redução de dimensionalidade não-linear geral. Aplique essa habilidade para embeddings rápidos e escaláveis que preservam estrutura local e global, aprendizado supervisionado e pré-processamento de clustering. ## Quick Start ### Instalação ```bash uv pip install umap-learn ``` ### Uso Básico UMAP segue as convenções do scikit-learn e pode ser usado como um substituto direto para t-SNE ou PCA. ```python import umap from sklearn.preprocessing import StandardScaler # Preparar dados (padronização é essencial) scaled_data = StandardScaler().fit_transform(data) # Método 1: Passo único (fit e transform) embedding = umap.UMAP().fit_transform(scaled_data) # Método 2: Passos separados (para reutilizar modelo treinado) reducer = umap.UMAP(random_state=42) reducer.fit(scaled_data) embedding = reducer.embedding_ # Acessar o embedding treinado ``` **Requisito crítico de pré-processamento:** Sempre padronize as features para escalas comparáveis antes de aplicar UMAP, garantindo ponderação igual entre dimensões. ### Fluxo de Trabalho Típico ```python import umap import matplotlib.pyplot as plt from sklearn.preprocessing import StandardScaler # 1. Pré-processar dados scaler = StandardScaler() scaled_data = scaler.fit_transform(raw_data) # 2. Criar e 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('UMAP Embedding') plt.show() ``` ## Guia de Ajuste de Parâmetros UMAP possui quatro parâmetros primários que controlam o comportamento do embedding. Compreender esses é crucial para uso eficaz. ### n_neighbors (padrão: 15) **Propósito:** Equilibra estrutura local versus global no embedding. **Como funciona:** Controla o tamanho da vizinhança local que UMAP examina ao aprender a estrutura da variedade. **Efeitos por valor:** - **Valores baixos (2-5):** Enfatiza detalhe local fino, mas pode fragmentar dados em componentes desconectados - **Valores médios (15-20):** Visão equilibrada de estrutura local e relacionamentos globais (ponto de partida recomendado) - **Valores altos (50-200):** Prioriza estrutura topológica ampla em detrimento de detalhes refinados **Recomendação:** Comece com 15 e ajuste com base nos resultados. Aumente para mais estrutura global, diminua para mais detalhe local. ### min_dist (padrão: 0.1) **Propósito:** Controla como os pontos se agrupam no espaço de baixa dimensionalidade. **Como funciona:** Define a distância mínima que os pontos precisam manter na representação de saída. **Efeitos por valor:** - **Valores baixos (0.0-0.1):** Cria embeddings aglomerados úteis para clustering; revela detalhes topológicos finos - **Valores altos (0.5-0.99):** Impede compactação apertada; enfatiza preservação topológica ampla sobre estrutura local **Recomendação:** Use 0.0 para aplicações de clustering, 0.1-0.3 para visualização, 0.5+ para estrutura solta. ### n_components (padrão: 2) **Propósito:** Determina a dimensionalidade do espaço de saída incorporado. **Recurso-chave:** Diferente de t-SNE, UMAP dimensiona bem na dimensão de embedding, permitindo uso além de visualização. **Usos comuns:** - **2-3 dimensões:** Visualização - **5-10 dimensões:** Pré-processamento de clustering (melhor preserva densidade que 2D) - **10-50 dimensões:** Feature engineering para modelos de ML downstream **Recomendação:** Use 2 para visualização, 5-10 para clustering, superior para pipelines de ML. ### metric (padrão: 'euclidean') **Propósito:** Especifica como a distância é calculada entre pontos de dados de entrada. **Métricas suportadas:** - **Variantes Minkowski:** euclidean, manhattan, chebyshev - **Métricas espaciais:** canberra, braycurtis, haversine - **Métricas de correlação:** cosine, correlation (boas para embeddings de texto/documentos) - **Métricas para dados binários:** hamming, jaccard, dice, russellrao, kulsinski, rogerstanimoto, sokalmichener, sokalsneath, yule - **Métricas customizadas:** Funções de distância definidas pelo usuário via Numba **Recomendação:** Use euclidean para dados numéricos, cosine para vetores de texto/documentos, hamming para dados binários. ### Exemplo de Ajuste de Parâmetros ```python # Para visualização com ênfase em estrutura local umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='euclidean') # Para pré-processamento 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 estrutura global umap.UMAP(n_neighbors=100, min_dist=0.5, n_components=2, metric='euclidean') ``` ## Redução de Dimensionalidade Supervisionada e Semi-Supervisionada UMAP oferece suporte à incorporação de informação de rótulos para guiar o processo de embedding, permitindo separação de classes enquanto preserva a estrutura interna. ### UMAP Supervisionado Passe rótulos-alvo via parâmetro `y` ao fazer fit: ```python # Redução de dimensionalidade supervisionada embedding = umap.UMAP().fit_transform(data, y=labels) ``` **Benefícios-chave:** - Alcança classes claramente separadas - Preserva estrutura interna dentro de cada classe - Mantém relacionamentos globais entre classes **Quando usar:** Quando você tem dados rotulados e quer separar classes conhecidas enquanto mantém embeddings significativos de pontos. ### UMAP Semi-Supervisionado Para rótulos parciais, marque pontos não rotulados com `-1` seguindo a convenção do scikit-learn: ```python # Criar rótulos semi-supervisionados semi_labels = labels.copy() semi_labels[unlabeled_indices] = -1 # Fazer fit com rótulos parciais embedding = umap.UMAP().fit_transform(data, y=semi_labels) ``` **Quando usar:** Quando a rotulação é cara ou você tem mais dados do que rótulos disponíveis. ### Aprendizado de Métrica com UMAP Treine um embedding supervisionado em dados rotulados, depois aplique a dados não rotulados novos: ```python # Treinar em dados rotulados mapper = umap.UMAP().fit(train_data, train_labels) # Transformar dados de teste não rotulados test_embedding = mapper.transform(test_data) # Usar como feature engineering para classificador downstream from sklearn.svm import SVC clf = SVC().fit(mapper.embedding_, train_labels) predictions = clf.predict(test_embedding) ``` **Quando usar:** Para feature engineering supervisionado em pipelines de machine learning. ## UMAP para Clustering UMAP serve como pré-processamento eficaz para algoritmos de clustering baseados em densidade como HDBSCAN, superando a maldição da dimensionalidade. ### Melhores Práticas para Clustering **Princípio-chave:** Configure UMAP diferentemente para clustering do que para visualização. **Parâmetros recomendados:** - **n_neighbors:** Aumente para ~30 (padrão 15 é muito local e pode criar clusters artificialmente refinados) - **min_dist:** Defina para 0.0 (empacote pontos densamente dentro de clusters para limites mais claros) - **n_components:** Use 5-10 dimensões (mantém performance enquanto melhora preservação de densidade vs. 2D) ### Fluxo de Trabalho de Clustering ```python import umap import hdbscan from sklearn.preprocessing import StandardScaler # 1. Pré-processar dados scaled_data = StandardScaler().fit_transform(data) # 2. UMAP com parâmetros otimizados para clustering reducer = umap.UMAP( n_neighbors=30, min_dist=0.0, n_components=10, # Superior a 2 para melhor preservação de densidade 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. Avaliar from sklearn.metrics import adjusted_rand_score score = adjusted_rand_score(true_labels, labels) print(f"Adjusted Rand Score: {score:.3f}") print(f"Number of clusters: {len(set(labels)) - (1 if -1 in labels else 0)}") print(f"Noise points: {sum(labels == -1)}") ``` ### Visualização Após Clustering ```python # Criar embedding 2D para visualização (separado de 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) # Plotar com rótulos 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('UMAP Visualization with HDBSCAN Clusters') plt.show() ``` **Ressalva importante:** UMAP não preserva completamente a densidade e pode criar divisões de clusters artificiais. Sempre valide e explore os clusters resultantes. ## Transformando Dados Novos UMAP permite pré-processamento de dados novos através de seu método `transform()`, permitindo que modelos treinados projetem dados invistos no espaço de embedding aprendido. ### Uso Básico de Transform ```python # Treinar em dados de treinamento trans = umap.UMAP(n_neighbors=15, random_state=42).fit(X_train) # Transformar dados de teste test_embedding = trans.transform(X_test) ``` ### Integração com Pipelines de Machine Learning ```python from sklearn.svm import SVC from sklearn.model_selection import train_test_split from sklearn.preprocessing import StandardScaler import umap # Dividir dados X_train, X_test, y_train, y_test = train_test_split(data, labels, test_size=0.2) # Pré-processar scaler = StandardScaler() X_train_scaled = scaler.fit_transform(X_train) X_test_scaled = scaler.transform(X_test) # Treinar 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) # Treinar classificador nos embeddings clf = SVC() clf.fit(X_train_embedded, y_train) accuracy = clf.score(X_test_embedded, y_test) print(f"Test accuracy: {accuracy:.3f}") ``` ### Considerações Importantes **Consistência de dados:** O método transform assume que a distribuição geral no espaço de dimensionalidade superior é consistente entre dados de treinamento e teste. Quando essa suposição falha, considere usar Parametric UMAP. **Performance:** Operações de transform são eficientes (tipicamente <1 segundo), embora chamadas iniciais possam ser mais lentas devido à compilação JIT do Numba. **Compatibilidade com scikit-learn:** UMAP segue convenções padrão do sklearn e funciona perfeitamente em pipelines: ```python 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) ``` ## Recursos Avançados ### Parametric UMAP Parametric UMAP substitui otimização direta de embedding com uma função de mapeamento de rede neural aprendida. **Diferenças-chave de UMAP padrão:** - Usa TensorFlow/Keras para treinar redes codificadoras - Permite transformação eficiente de dados novos - Oferece suporte a reconstrução via redes decodificadoras (inverse transform) - Permite arquiteturas customizadas (CNNs para imagens, RNNs para sequências) **Instalação:** ```bash uv pip install umap-learn[parametric_umap] # Requer TensorFlow 2.x ``` **Uso básico:** ```python from umap.parametric_umap import ParametricUMAP # Arquitetura padrão (rede totalmente conectada de 3 camadas com 100 neurônios) embedder = ParametricUMAP() embedding = embedder.fit_transform(data) # Transformar dados novos eficientemente new_embedding = embedder.transform(new_data) ``` **Arquitetura customizada:** ```python import tensorflow as tf # Definir codificador customizado encoder = tf.keras.Sequential([ tf.keras.layers.InputLayer(input_shape=(input_dim,)), tf.keras.layers.Dense(128, activation='relu'), tf.keras.layers.Dense(64, activation='relu'), tf.keras.layers.Dense(2) # Dimensão de saída ]) embedder = ParametricUMAP(encoder=encoder, dims=(input_dim,)) embedding = embedder.fit_transform(data) ``` **Quando usar Parametric UMAP:** - Precisa de transformação eficiente de dados novos após treinamento - Requer capacidades de reconstrução (inverse transforms) - Quer combinar UMAP com autoencoders - Trabalha com tipos de dados complexos (imagens, sequências) que se beneficiam de arquiteturas especializadas **Quando usar UMAP padrão:** - Precisa de simplicidade e prototipagem rápida - Dataset é pequeno e eficiência computacional não é crítica - Não requer transformações aprendidas para dados futuros ### Inverse Transforms Inverse transforms permitem reconstrução de dados de alta dimensionalidade a partir de embeddings de baixa dimensionalidade. **Uso básico:** ```python reducer = umap.UMAP() embedding = reducer.fit_transform(data) # Reconstruir dados de alta dimensionalidade a partir de coordenadas de embedding reconstructed = reducer.inverse_transform(embedding) ``` **Limitações importantes:** - Operação computacionalmente cara - Funciona mal fora do convex hull do embedding - Precisão diminui em regiões com lacunas entre clusters **Casos de uso:** - Compreender estrutura de dados incorporados - Visualizar transições suaves entre clusters - Explorar interpolações entre pontos de dados - Gerar amostras sintéticas no espaço de embedding **Exemplo: Explorando espaço de embedding:** ```python 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) grid_points = np.c_[xx.ravel(), yy.ravel()] # Reconstruir amostras da grade reconstructed_samples = reducer.inverse_transform(grid_points) ``` ### AlignedUMAP Para analisar datasets temporais ou relacionados (ex: experimentos de série temporal, dados de lote): ```python from umap import AlignedUMAP # Lista de datasets relacionados datasets = [day1_data, day2_data, day3_data] # Criar embeddings alinhados mapper = AlignedUMAP().fit(datasets) aligned_embeddings = mapper.embeddings_ # Lista de embeddings ``` **Quando usar:** Comparar embeddings entre datasets relacionados mantendo sistemas de coordenadas consistentes. ## Reprodutibilidade Para garantir resultados reproduzíveis, sempre defina o parâmetro `random_state`: ```python reducer = umap.UMAP(random_state=42) ``` UMAP usa otimização estocástica, então resultados variarão ligeiramente entre execuções sem um estado aleatório fixo. ## Problemas Comuns e Soluções **Problema:** Componentes desconectados ou clusters fragmentados - **Solução:** Aumente `n_neighbors` para enfatizar mais estrutura global **Problema:** Clusters muito espalhados ou não bem separados - **Solução:** Diminua `min_dist` para permitir empacotamento mais apertado **Problema:** Resultados ruins de clustering - **Solução:** Use parâmetros específicos para clustering (n_neighbors=30, min_dist=0.0, n_components=5-10) **Problema:** Resultados de transform diferem significativamente do treinamento - **Solução:** Garanta que a distribuição de dados de teste corresponda ao treinamento, ou use Parametric UMAP **Problema:** Performance lenta em datasets grandes - **Solução:** Defina `low_memory=True` (padrão), ou considere redução de dimensionalidade com PCA primeiro **Problema:** Todos os pontos colapsados em um único cluster - **Solução:** Verifique pré-processamento de dados (garanta escalonamento apropriado), aumente `min_dist` ## Recursos ### references/ Contém documentação detalhada da API: - `api_reference.md`: Parâmetros e métodos completos da classe UMAP Carregue essas referências quando informação detalhada de parâmetros ou uso avançado de métodos for necessário.