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 em geral. Aplique essa habilidade para obter embeddings rápidos e escaláveis que aproximam a estrutura de vizinhança, aprendizado supervisionado e pré-processamento para clustering.

Antes de interpretar um embedding, verifique coordenadas finitas, retenção de vizinhança, sensibilidade a sementes/parâmetros e evidências de domínio no espaço original. Eixos do UMAP, áreas de ilhas e lacunas entre clusters não têm significado físico ou probabilístico calibrado. Mantenha dados de teste preditivos fora do pré-processamento e dos ajustes de embedding.

Início Rápido

Instalação

Verificado em 01/10/2026: umap-learn 0.5.12 é a versão estável atual (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

UMAP usa a interface de estimador do scikit-learn, mas sua geometria e comportamento supervisionado diferem de PCA e t-SNE. Exemplos centrais foram exercitados em dados sintéticos pequenos com Python 3.13, scikit-learn 1.9.1, NumPy 2.5.3 e Numba 0.68.0. Exemplos paramétricos são ilustrações verificadas pela fonte, não testes TensorFlow executados. Nos trechos abaixo, data é um array finito de amostras por features e os rótulos devem seguir a mesma ordem de linhas.

import umap
from sklearn.preprocessing import StandardScaler

# Scale continuous features when their units should carry equal weight
scaled_data = StandardScaler().fit_transform(data)

# Method 1: Single step (fit and transform)
embedding = umap.UMAP(random_state=42, n_jobs=1).fit_transform(scaled_data)

# Method 2: Separate steps (for reusing trained model)
reducer = umap.UMAP(random_state=42)
reducer.fit(scaled_data)
embedding = reducer.embedding_  # Access the trained embedding

Requisito de pré-processamento: Combine o pré-processamento com a métrica. Para métricas numéricas do tipo Euclidiano, decida se o escalonamento é cientificamente apropriado; ele altera o peso das features. Ajuste o pré-processamento apenas nos dados de treinamento para trabalhos preditivos. Use StandardScaler(with_mean=False) para matrizes esparsas para evitar densificá-las. Para fluxos de trabalho com cosseno, binário, distância pré-computada ou features mistas, 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. Preprocess data
scaler = StandardScaler()
scaled_data = scaler.fit_transform(raw_data)

# 2. Create and fit 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. Visualize
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 principais que controlam o comportamento do embedding. Compreendê-los é crucial para um uso eficaz.

n_neighbors (padrão: 15)

Propósito: Equilibra a estrutura local versus global no embedding.

Como funciona: Controla o tamanho do vizinho 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 das 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, mantenha-o abaixo do número de amostras ajustadas e compare vários valores. Vizinhanças maiores não tornam as distâncias inter-cluster quantitativamente confiáveis.

min_dist (padrão: 0.1)

Propósito: Controla o quão juntos os pontos se agrupam no espaço de baixa dimensão.

Como funciona: Ajusta a curva de atração e o empacotamento típico no embedding; não é um limite inferior rígido para distâncias par a par. Requer 0 <= min_dist <= spread.

Efeitos por valor:

• Valores baixos (0.0-0.1): Cria embeddings agrupados úteis para clustering; revela detalhes topológicos finos
• Valores altos (0.5-0.99): Incentiva um empacotamento mais solto; não certifica a preservação de distâncias globais

…