Use UMAP-learn for nonlinear dimensionality reduction, 2D/3D embeddings, clustering preprocessing, supervised or semi-supervised UMAP, DensMAP, AlignedUMAP, and Parametric UMAP workflows.

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: 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. 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. Typical Workflow Parameter Tuning Guide UMAP has four primary parameters that control the embedding behavior. Understanding these is crucial for effective usage. n neighbors (default: 15) Purpose: Balances local versus global structure in the embedding. How it works: Controls the size of the local neighborhood UMAP examines when learning manifold structure. Effects by value: Low values (2 5): Emphasizes fine local detail but may fragment data into disconnected components Medium values (15 20): Balanced view of both local structure and global relationships (recommended starting point) High values (50 200): Prioritizes broad topological structure at the expense of fine grained details Recommendation: Start with 15, keep it below the number of fitted samples, and compare several values. Larger neighborhoods do not make inter cluster distances quantitatively reliable. min dist (default: 0.1) Purpose: Controls how tightly points cluster in the low dimensional space. How it works: Adjusts the attraction curve and typical packing in the embedding; it is not a hard lower bound on pairwise distances. Require 0 <= min dist <= spread . Effects by value: Low values (0.0 0.1): Creates clumped embeddings useful for clustering; reveals fine topological details High values (0.5 0.99): Encourages looser packing; does not certify preservation of global distances Recommendation: Use 0.0 for clustering applications, 0.1 0.3 for visualization, 0.5+ for loose structure. n components (default: 2) Purpose: Determines the dimensionality of the embedded output space. Key feature: Unlike t SNE, UMAP scales well in the embedding dimension, enabling use beyond visualization. Common uses: 2 3 dimensions: Visualization 5 10 dimensions: Clustering preprocessing (may retain more useful structure than 2D; does not guarantee density preservation) 10 50 dimensions: Feature engineering for downstream ML models Recommendation: Use 2 for visualization, 5 10 for clustering, higher for ML pipelines. metric (default: 'euclidean') Purpose: Specifies how distance is calculated between input data points. Supported metrics: Minkowski variants: euclidean, manhattan, chebyshev Spatial metrics: canberra, braycurtis, haversine Correlation metrics: cosine, correlation (good for text/document embeddings) Binary data metrics: hamming, jaccard, dice, russellrao, kulsinski, rogerstanimoto, sokalmichener, sokalsneath, yule Custom metrics: User defined distance functions via Numba Recommendation: Use euclidean for numeric data, cosine for text/document vectors, hamming for binary data. Parameter Tuning Example Supervised and Semi Supervised Dimension Reduction UMAP supports incorporating label information to guide the embedding process, encouraging class separation while retaining parts of the feature neighborhood graph. Supervised UMAP Pass target labels via the y parameter when fitting: Interpretation: Label guided separation is part of the objective, not independent evidence of discovered classes. Tune using training folds and evaluate on held out samples. To obtain an unsupervised fit, omit y ; target weight=0 with categorical labels still modifies graph edges in 0.5.12. Semi Supervised UMAP For target metric="categorical" , encode known classes as nonnegative integers and unlabeled points as 1 . This sentinel does not extend to arbitrary regression targets: When to use: When labeling is expensive or you have more data than labels available. UMAP for Clustering UMAP can help HDBSCAN on high dimensional data, but reduction can create or erase clusters. Compare against clustering in the original or PCA space. Best Practices for Clustering Key principle: Configure UMAP differently for clustering than for visualization. Starting candidates, to validate on the actual data: n neighbors: Compare 15, 30, and larger valid values; there is no universally correct neighborhood size min dist: Set to 0.0 (pack points densely within clusters for clearer boundaries) n components: Try 5 10 dimensions and compare cluster stability; standard UMAP does not preserve density Clustering Workflow Install HDBSCAN separately for density based clustering: Visualization After Clustering Validation: Report noise fraction and clusters found across seeds and parameter choices. Check cluster membership and domain evidence in the original feature space. A silhouette score computed only in the optimized embedding can be misleading. No cluster or all noise output is a possible result, not a reason to tune until attractive islands appear. Transforming New Data UMAP enables preprocessing of new data through its transform() method, allowing trained models to project unseen data into the learned embedding space. Basic Transform Usage Integration with Machine Learning Pipelines Important Considerations Data consistency: Validate transforms on held out data representative of deployment. Inspect out of distribution inputs and neighborhood support before interpreting their locations; neither standard nor Parametric UMAP guarantees meaningful extrapolation under distribution shift. Retraining on representative data requires a new downstream validation. Performance: Measure fit and transform with your sample size and metric; first calls include Numba compilation. There is no fixed latency guarantee. Standard transform preserves the trained coordinate system; update refits with added samples and can move existing points. Scikit learn compatibility: Pipeline.fit(X, y) forwards y to UMAP, so the following is a supervised UMAP pipeline. Keep the whole pipeline inside cross validation; fitting the embedding once before cross validation leaks information. The manual example above deliberately fits UMAP without labels: Advanced Features densMAP Use UMAP(densmap=True, output dens=True) when local density is part of the question. fit transform then returns (embedding, rad orig, rad emb) : the radii are log transformed local radius estimates, not probabilities or raw density values. dens frac=0.3 applies the density objective during the final 30% of optimization epochs, not to 30% of samples. densMAP supports Euclidean output and cannot transform unseen data or use inverse transform in 0.5.12. See the reference for a runnable recipe. Parametric UMAP Parametric UMAP replaces direct embedding optimization with a learned neural network mapping function. Key differences from standard UMAP: Uses TensorFlow/Keras to train encoder networks Enables efficient transformation of new data Supports reconstruction via decoder networks (inverse transform) Allows custom architectures (CNNs for images, RNNs for sequences) Installation: Illustrative basic usage (TensorFlow runtime not exercised): Custom architecture: Persistence: Save Parametric UMAP with its built in Keras aware methods rather than plain pickle: Only load trusted model directories: loading reads a pickle. Verify transformed outputs after saving/loading. In 0.5.12, save writes parametric model.keras while the loader checks parametric model ; do not assume full training state restoration. exclude raw data=True is not a privacy/anonymization guarantee. The [released source](https://github.com/lmcinnes/umap/blob/release 0.5.12/umap/parametric umap.py) is authoritative where hosted examples differ. When to use Parametric UMAP: Need efficient transformation of new data after training Require reconstruction capabilities (inverse transforms) Want to combine UMAP with autoencoders Working with complex data types (images, sequences) benefiting from specialized architectures Inverse Transforms Inverse transforms enable reconstruction of high dimensional data from low dimensional embeddings. Basic usage: Important limitations: Approximate reconstruction, not a bijective inverse or evidence that a generated sample is plausible Unsupported for sparse training data, precomputed or gradient free metrics, densMAP, and graph mode Computationally expensive; poor support outside the training embedding or between disconnected clusters Explore inverse coordinates only where the training embedding supports them; rectangular grids often cross unsupported gaps. Check domain constraints on every generated reconstruction. AlignedUMAP For temporal or related datasets that need a shared coordinate system (time series experiments, batches), use umap.AlignedUMAP().fit(datasets, relations=relations) , where relations maps sample indices between consecutive datasets and is required for meaningful alignment. Parameters, methods, and a worked example are in references/api reference.md under "AlignedUMAP Class" and "Usage Examples". Reproducibility For reproducibility in the same software/hardware environment, set random state and retain the data order, preprocessing, package versions, and parameters: UMAP is stochastic; unseeded runs can differ substantially. Compare neighborhood or cluster stability rather than unaligned coordinates, which can rotate or reflect. In standard UMAP, setting random state forces n jobs=1 . transform seed separately controls transform randomness. Exact cross version or GPU/CPU equivalence is not promised. Leave it unset when throughput matters more than exact repeatability, because UMAP can use more parallelism without a fixed seed. Common Issues and Solutions Issue: Disconnected components or fragmented clusters Solution: Inspect graph connected components, duplicates, metric support and outliers before increasing n neighbors . Fully disconnected vertices can receive NaN coordinates; do not silently drop them from the analysis. Issue: Clusters too spread out or not well separated Solution: Compare several min dist values; visual separation is not a scientific validation criterion Issue: Poor clustering results Solution: Compare n

umap-learn