umap-learn

UMAP-Learn

Overview

UMAP (Uniform Manifold Approximation and Projection) is a dimensionality reduction technique for visualization and general non-linear dimensionality reduction. Apply this skill for fast, scalable embeddings that approximate neighborhood structure, supervised learning, and clustering preprocessing.

Before interpreting an embedding, check finite coordinates, neighborhood retention, sensitivity to seeds/parameters, and domain evidence in the original space. UMAP axes, island areas, and gaps between clusters have no calibrated physical or probabilistic meaning. Keep predictive test data outside preprocessing and embedding fits.

Quick Start

Installation

Verified on 2026-10-01: umap-learn 0.5.12 is the current stable release (April 2026). Requires Python 3.9+ and depends on scikit-learn>=1.6, numba, pynndescent, numpy, and scipy. Pin to a verified release:

uv pip install umap-learn==0.5.12

Basic Usage

UMAP uses the scikit-learn estimator interface, but its geometry and supervised behavior differ from PCA and t-SNE. Core examples were exercised on small synthetic data with Python 3.13, scikit-learn 1.9.1, NumPy 2.5.3, and Numba 0.68.0. Parametric examples are source-checked illustrations, not executed TensorFlow tests. In snippets below, data is a finite samples-by-features array and labels must follow the same row order.

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

Preprocessing requirement: Match preprocessing to the metric. For numeric Euclidean-style metrics, decide whether scaling is scientifically appropriate; it changes the feature weighting. Fit preprocessing on training data only for predictive work. Use StandardScaler(with_mean=False) for sparse matrices to avoid densifying them. For cosine, binary, precomputed-distance, or mixed-feature workflows, choose preprocessing that matches the metric instead of blindly standardizing every column.