Umap Learn

K-DenseCommunityCreated by K-Dense Inc.

Skill
Tool integration
Data and AI
MIT
Low risk

From the author

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

— the description by K-Dense Inc.

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

UMAP (Uniform Manifold Approximation and Projection) is a versatile technique for non-linear dimensionality reduction. This skill provides the procedural knowledge to implement UMAP for tasks ranging from 2D/3D visualization to high-dimensional feature engineering for machine learning pipelines. It covers standard UMAP, supervised and semi-supervised variants, densMAP for density-aware embeddings, and Parametric UMAP for neural network-based projections. The skill emphasizes proper parameter tuning, preprocessing requirements, and best practices for clustering and reproducibility.

What it does

Performs non-linear dimensionality reduction for visualization and feature engineering.
Supports supervised and semi-supervised embedding using target labels.
Enables density-aware embeddings via densMAP.
Provides Parametric UMAP for deep learning-based embedding architectures.
Facilitates clustering workflows by preparing data for density-based algorithms like HDBSCAN.
Allows transformation of new, unseen data into existing learned embedding spaces.

When to use it

When you need to visualize high-dimensional data in 2D or 3D.
When preparing high-dimensional data for clustering to improve stability.
When you require efficient feature engineering for downstream machine learning models.
When you have partially labeled data and want to guide the embedding process.
When you need to project new, unseen data points into a previously learned manifold.

Advantages

Scales well to large datasets and higher embedding dimensions compared to t-SNE.
Preserves both local and global manifold structure.
Highly configurable with support for various distance metrics and custom architectures.
Integrates seamlessly with scikit-learn pipelines.
Supports advanced variants like Parametric UMAP for complex data types.

Usage examples

“How do I use UMAP to prepare data for clustering with HDBSCAN?”: The agent provides a workflow using UMAP with min_dist=0.0 and n_components=10, followed by HDBSCAN clustering, including validation steps to check cluster stability.
“Can I use UMAP to guide the embedding with my existing labels?”: The agent explains how to pass labels to the fit_transform method for supervised UMAP, or how to use -1 for unlabeled data in a semi-supervised approach.
“How do I transform new test data using a trained UMAP model?”: The agent demonstrates using the trained reducer's transform() method on new data, emphasizing the need for consistent preprocessing.
“What parameters should I tune for better global structure?”: The agent advises increasing the n_neighbors parameter (e.g., 50-200) to prioritize broader topological structure over fine-grained local details.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/k-dense-ai/umap-learn/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip umap-learn.zip -d .agents/skills

Documentation by K-Dense Inc.

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.

Typical Workflow

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()

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

# For visualization with emphasis on local structure
umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='euclidean')

# For clustering preprocessing
umap.UMAP(n_neighbors=30, min_dist=0.0, n_components=10, metric='euclidean')

# For document embeddings
umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='cosine')

# For emphasizing broader neighborhoods
umap.UMAP(n_neighbors=100, min_dist=0.5, n_components=2, metric='euclidean')

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:

# Supervised dimension reduction
embedding = umap.UMAP().fit_transform(data, y=labels)

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:

# Create semi-supervised labels
semi_labels = labels.copy()
semi_labels[unlabeled_indices] = -1

# Fit with partial labels
embedding = umap.UMAP().fit_transform(data, y=semi_labels)

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:

uv pip install hdbscan==0.8.44

import umap
import hdbscan
from sklearn.preprocessing import StandardScaler

# 1. Preprocess data
scaled_data = StandardScaler().fit_transform(data)

# 2. Candidate UMAP settings for clustering
reducer = umap.UMAP(
    n_neighbors=30,
    min_dist=0.0,
    n_components=10,  # Evaluate stability against other dimensions
    metric='euclidean',
    random_state=42
)
embedding = reducer.fit_transform(scaled_data)

# 3. Apply HDBSCAN clustering
clusterer = hdbscan.HDBSCAN(
    min_cluster_size=15,
    min_samples=5,
    metric='euclidean'
)
labels = clusterer.fit_predict(embedding)

# 4. Evaluate
from sklearn.metrics import adjusted_rand_score
# Only when independently known labels are available; ARI here includes noise as -1.
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)}")

Visualization After Clustering

# Create 2D embedding for visualization (separate from 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)

# Plot with cluster labels
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()

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

# Train on training data
trans = umap.UMAP(n_neighbors=15, random_state=42).fit(X_train)

# Transform test data
test_embedding = trans.transform(X_test)

Integration with Machine Learning Pipelines

from sklearn.svm import SVC
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler
import umap

# Split data
X_train, X_test, y_train, y_test = train_test_split(
    data, labels, test_size=0.2, random_state=42, stratify=labels
)

# Preprocess
scaler = StandardScaler()
X_train_scaled = scaler.fit_transform(X_train)
X_test_scaled = scaler.transform(X_test)

# Train 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)

# Train classifier on embeddings
clf = SVC()
clf.fit(X_train_embedded, y_train)
accuracy = clf.score(X_test_embedded, y_test)
print(f"Test accuracy: {accuracy:.3f}")

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:

from sklearn.pipeline import Pipeline

pipeline = Pipeline([
    ('scaler', StandardScaler()),
    ('umap', umap.UMAP(n_components=10, random_state=42, n_jobs=1)),
    ('classifier', SVC())
])

pipeline.fit(X_train, y_train)
predictions = pipeline.predict(X_test)
feature_names = pipeline.named_steps['umap'].get_feature_names_out()

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:

uv pip install "umap-learn[parametric-umap]==0.5.12"
# The released source also requires Keras >=3; verify the resolved TensorFlow/Keras pair.

Illustrative basic usage (TensorFlow runtime not exercised):

from umap.parametric_umap import ParametricUMAP

# Default architecture (3-layer 100-neuron fully-connected network)
embedder = ParametricUMAP()
embedding = embedder.fit_transform(data)

# Transform new data efficiently
new_embedding = embedder.transform(new_data)

Custom architecture:

import tensorflow as tf

# Define custom encoder
encoder = tf.keras.Sequential([
    tf.keras.layers.InputLayer(shape=(input_dim,)),
    tf.keras.layers.Dense(128, activation='relu'),
    tf.keras.layers.Dense(64, activation='relu'),
    tf.keras.layers.Dense(2)  # Output dimension
])

embedder = ParametricUMAP(encoder=encoder, dims=(input_dim,))
embedding = embedder.fit_transform(data)

Persistence: Save Parametric UMAP with its built-in Keras-aware methods rather than plain pickle:

from pathlib import Path
Path("parametric_umap_model").mkdir(exist_ok=True)
embedder.save("parametric_umap_model", exclude_raw_data=True)

from umap.parametric_umap import load_ParametricUMAP
loaded = load_ParametricUMAP("parametric_umap_model")
new_embedding = loaded.transform(new_data)

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 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:

reducer = umap.UMAP()
embedding = reducer.fit_transform(data)

# Reconstruct high-dimensional data from embedding coordinates
reconstructed = reducer.inverse_transform(embedding)

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:

reducer = umap.UMAP(random_state=42)

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 neighborhood sizes/dimensions, noise fractions, multiple seeds, and a baseline without UMAP

Issue: Transform results differ significantly from training

Solution: Check preprocessing and distribution shift; validate neighborhood support and downstream performance before reusing either UMAP variant.

Issue: Slow performance on large datasets

Solution: Profile neighbor search versus optimization. low_memory=True reduces memory use, not necessarily runtime; consider PCA or sparse TruncatedSVD only when their information loss is acceptable

Issue: NaN or inf values in input data

Solution: Impute or drop invalid rows before fitting. Current UMAP uses scikit-learn-style finite-value checks (ensure_all_finite) in fit() and update(), so clean numeric input is the safest default

Issue: All points collapsed to single cluster

Solution: Check constant/duplicate features, the distance metric and preprocessing; compare multiple settings without assuming multiple true clusters exist

Issue: Imports resolve to a local file instead of the real package

Solution: Do not keep project files named umap.py, sklearn.py, hdbscan.py, or tensorflow.py beside notebooks or scripts. Those names can shadow installed packages and break or poison examples.

Resources

Official documentation

references/

Contains detailed API documentation:

api_reference.md: Release-checked parameter contracts, return values, restrictions, and advanced recipes

Load these references when detailed parameter information or advanced method usage is needed.

Citing Scientific Agent Skills

This skill is part of Scientific Agent Skills by K-Dense. If it materially contributed to a manuscript, report, presentation, or code release, add the paper to the references or software section and tell the user you did so:

Kassis, T., Agarwal, V., He, Y., Patel, D., & Brueckner, A. M. (2026). Scientific Agent Skills: A Library of Procedural Knowledge for Research Agents. arXiv:2609.00065. https://doi.org/10.48550/arXiv.2609.00065

Always cite the current version. The DOI and https://arxiv.org/abs/2609.00065 resolve to the latest arXiv version, so never append a version suffix such as v1. When network access is available, fetch https://arxiv.org/abs/2609.00065 (or http://export.arxiv.org/api/query?id_list=2609.00065) before writing the reference and take the author list, year, and version from that record. If the record lists a journal reference or publisher DOI, cite the published version instead.

Files

ATTRIBUTION.mdAdded by AutoGineer977 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md21.0 KiB
references/api_reference.md27.9 KiB

references/api_reference.md

UMAP API Reference

Reference checked 2026-10-01 for umap-learn 0.5.12 (Python >=3.9; scikit-learn>=1.6). The hosted API guide still identifies 0.5.8; use the released implementation for exact signatures and return contracts. All calculations run locally; the package has no service endpoint, authentication, or pagination requirement. Examples assume finite numeric arrays with stable sample/feature ordering. Core synthetic checks used native Numba JIT; TensorFlow examples are illustrative and source-checked only.

UMAP Class

umap.UMAP(n_neighbors=15, n_components=2, metric='euclidean', metric_kwds=None, output_metric='euclidean', output_metric_kwds=None, n_epochs=None, learning_rate=1.0, init='spectral', min_dist=0.1, spread=1.0, low_memory=True, n_jobs=-1, set_op_mix_ratio=1.0, local_connectivity=1.0, repulsion_strength=1.0, negative_sample_rate=5, transform_queue_size=4.0, a=None, b=None, random_state=None, angular_rp_forest=False, target_n_neighbors=-1, target_metric='categorical', target_metric_kwds=None, target_weight=0.5, transform_seed=42, transform_mode='embedding', force_approximation_algorithm=False, verbose=False, tqdm_kwds=None, unique=False, densmap=False, dens_lambda=2.0, dens_frac=0.3, dens_var_shift=0.1, output_dens=False, disconnection_distance=None, precomputed_knn=(None, None, None))

Find low-dimensional embedding that approximates the underlying manifold of the data.

Core Parameters

n_neighbors (int, default: 15)

Size of the local neighborhood used for manifold approximation. Larger values result in more global views of the manifold, while smaller values preserve more local structure. Generally in the range 2 to 100.

Tuning guidance:

Use 2-5 for very local structure
Use 10-20 for balanced local/global structure (typical)
Use 50-200 for emphasizing global structure

n_components (int, default: 2)

Dimension of the embedding space. Unlike t-SNE, UMAP scales well with increasing embedding dimensions.

Common values:

2-3: Visualization
5-10: Clustering preprocessing
10-100: Feature engineering for downstream ML

metric (str or callable, default: 'euclidean')

Distance metric to use. Accepts:

Recognized names in UMAP/PyNNDescent; not every SciPy or scikit-learn metric is accepted, and sparse support differs from dense support
"precomputed": distances, not similarities; see the recipe below
Custom Numba-compatible callables returning a distance; return (distance, gradient) to enable inverse transformation

Common metrics:

'euclidean': Standard Euclidean distance (default)
'manhattan': L1 distance
'cosine': Cosine distance (good for text/document vectors)
'correlation': Correlation distance
'hamming': Hamming distance (for binary data)
'jaccard': Jaccard distance (for binary/set data)
'dice': Dice distance
'canberra': Canberra distance
'braycurtis': Bray-Curtis distance
'chebyshev': Chebyshev distance
'minkowski': Minkowski distance (specify p with metric_kwds)
'precomputed': Use precomputed distance matrix

output_metric (str or callable, default: 'euclidean')

Distance metric for the embedding space. Most workflows should keep the Euclidean default; advanced workflows can use a supported output metric with output_metric_kwds.

min_dist (float, default: 0.1)

A parameter of the fitted low-dimensional attraction curve, not a hard pairwise-distance bound. Smaller values favor clumpier embeddings. Require 0 <= min_dist <= spread.

Tuning guidance:

Use 0.0 for clustering applications
Use 0.1-0.3 for visualization (balanced)
Use 0.5-0.99 for loose structure preservation

spread (float, default: 1.0)

Effective scale of embedded points. Combined with min_dist to control clumped vs. spread-out embeddings. Determines how spread out the clusters are in the embedding space.

Training Parameters

n_epochs (int, list of int, or None; default: None)

Optimization epochs. With None, standard UMAP uses 500 epochs up to 10,000 samples and 200 above that; densMAP adds 200. A list requests intermediate embeddings in embedding_list_, while embedding_ is the final result.

Manual tuning:

Smaller datasets may need 500+ epochs
Larger datasets may converge with 200 epochs
More epochs increase cost; scientific validity still requires external checks

learning_rate (float, default: 1.0)

Initial learning rate for the SGD optimizer. Higher values lead to faster convergence but may overshoot optimal solutions.

init (str or np.ndarray, default: 'spectral')

Initialization method for the embedding:

'spectral': Spectral initialization (default)
'random': Random initialization
'pca': Initialize with PCA (TruncatedSVD for sparse input)
'tswspectral': Truncated-SVD warm start for spectral initialization
numpy array: Custom initialization (shape: (n_samples, n_components))

Advanced Structural Parameters

local_connectivity (float, default: 1.0)

Number of nearest neighbors assumed to be locally connected. Higher values give more connected manifolds.

set_op_mix_ratio (float, default: 1.0)

Interpolation between union and intersection when constructing fuzzy set unions. Value of 1.0 uses pure union, 0.0 uses pure intersection.

repulsion_strength (float, default: 1.0)

Weighting applied to negative samples in low-dimensional embedding optimization. Higher values push embedded points further apart.

negative_sample_rate (int, default: 5)

Number of negative samples to select per positive sample. Higher values lead to greater repulsion between points and more spread-out embeddings but increase computational cost.

Supervised Learning Parameters

target_n_neighbors (int, default: -1)

Number of nearest neighbors to use when constructing target simplicial set. If -1, uses n_neighbors value.

target_metric (str or callable, default: 'categorical')

Distance metric for target values (labels):

'categorical': For classification tasks
A supported continuous metric such as "l2" for regression targets; -1 is not a generic missing-value marker

target_weight (float, default: 0.5)

Weight applied to target information vs. data structure. Range 0.0 to 1.0:

Lower values emphasize the feature graph; higher values emphasize target agreement
0.5 is the default
With categorical targets in 0.5.12, even 0.0 changes edges between classes; omit y for an unsupervised fit
1.0 strongly suppresses cross-class connections; it does not discard the feature graph

Transform Parameters

transform_queue_size (float, default: 4.0)

Size of the nearest neighbor search queue for transform operations. Larger values improve transform accuracy but increase memory usage and computation time.

transform_seed (int, default: 42)

Random seed for transform operations; keep query order and software environment fixed when checking reproducibility.

transform_mode (str, default: 'embedding')

Method for transforming new data:

'embedding': Standard approach (default)
'graph': fit_transform returns the sparse training graph (n_train, n_train); transform returns a bipartite graph (n_new, n_train), not embedding coordinates

Performance Parameters

low_memory (bool, default: True)

Whether to use a memory-efficient implementation. Set to False only if memory is not a constraint and you want faster performance.

n_jobs (int, default: -1)

Number of parallel jobs to use where supported. -1 uses all available processors. A non-None random_state forces n_jobs=1 in standard UMAP.

verbose (bool, default: False)

Whether to print progress messages during fitting.

tqdm_kwds (dict, default: None)

Keyword arguments passed to the tqdm progress bar when progress reporting is enabled.

unique (bool, default: False)

Fit unique feature rows and map the resulting coordinates back to input rows. Audit duplicate rows with conflicting labels. Unsupported with precomputed distances or precomputed neighbors.

force_approximation_algorithm (bool, default: False)

Use approximate search even below the usual small-data threshold. Large inputs already take that path; this is not a general large-data speed switch.

angular_rp_forest (bool, default: False)

Whether to use angular random projection forest for nearest neighbor search. Can improve performance for normalized data in high dimensions.

DensMAP Parameters

densMAP adds a local density correlation objective; it does not guarantee exact density preservation.

densmap (bool, default: False)

Whether to use the DensMAP algorithm instead of standard UMAP. Encourages local density relationships as well as neighborhood structure. Only Euclidean output is supported, and new-data transform/inverse transform are unavailable.

dens_lambda (float, default: 2.0)

Weight of density preservation term in DensMAP optimization. Higher values emphasize density preservation.

dens_frac (float, default: 0.3)

Fraction of optimization epochs using the density objective, after the initial (1 - dens_frac) fraction uses the standard UMAP objective.

dens_var_shift (float, default: 0.1)

Positive stabilizer added to variance of embedded local radii in the density objective.

output_dens (bool, default: False)

Whether to output log-transformed local-radius estimates in addition to the embedding; larger radii indicate sparser neighborhoods. These are not density probabilities. Also supported with densmap=False. When enabled, fit_transform() returns (embedding, original_local_radii, embedded_local_radii) and fitted objects expose density-related attributes such as rad_orig_ and rad_emb_.

Other Parameters

a (float, default: None)

Parameter controlling embedding. If None, determined automatically from min_dist and spread.

b (float, default: None)

Parameter controlling embedding. If None, determined automatically from min_dist and spread.

random_state (int, RandomState instance, or None, default: None)

Random state for reproducibility within the same environment. Save input ordering, preprocessing and dependency versions; cross-version equality is not guaranteed.

metric_kwds (dict, default: None)

Additional keyword arguments for the distance metric.

disconnection_distance (float, default: None)

Prunes neighbor edges with distance greater than or equal to this threshold. None chooses a built-in cutoff for certain bounded metrics, otherwise infinity. It does not use the observed graph maximum. Inspect disconnected vertices and nonfinite coordinates.

precomputed_knn (tuple, default: (None, None, None))

Precomputed neighbors as (knn_indices, knn_dists, knn_search_index), or the two arrays alone. Arrays must correspond to the same input rows/metric and include each row itself first at zero distance. Supply at least n_neighbors columns; retain a compatible PyNNDescent NNDescent search index for new-data transforms. Without it, transform(new_data) is unsupported. Unlike metric="precomputed", X remains the feature matrix.

Methods and outputs

Method	Released 0.5.12 contract
`fit(X, y=None, ensure_all_finite=True, **kwargs)`	Returns `self`. `X` is samples by features, or square training distances for a precomputed metric.
`fit_transform(X, y=None, ensure_all_finite=True, **kwargs)`	Returns coordinates; with `output_dens=True` returns `(embedding, rad_orig, rad_emb)`; with graph mode returns a sparse graph.
`transform(X, ensure_all_finite=True)`	Coordinates for new rows, or bipartite graph in graph mode. Precomputed metrics require new-to-training distances with unchanged training-column order.
`inverse_transform(X)`	Approximate reconstruction from coordinates. Requires dense training features and a gradient-capable input metric; unavailable for densMAP, precomputed metric, or graph mode.
`update(X, ensure_all_finite=True)`	Mutates the fitted model and returns None. Adds feature rows and can move old points. Rejects supervised models and precomputed metrics; not equivalent to transforming new rows. Revalidate after an update.
`get_feature_names_out(input_features=None)`	Names such as `umap0`, `umap1`; `input_features` is ignored.

ensure_all_finite accepts True, False, or "allow-nan", but bypassing the check does not make distance calculations missing-value aware. Clean or impute inputs deliberately. Treat nonfinite outputs as a failed support check, even when inputs are finite.

Use embedding_, graph_, rad_orig_/rad_emb_ (when requested), and embedding_list_ (when requested) for results. Graph storage formats can vary; use .tocsr() when CSR operations are required. Attributes beginning with _ are implementation details, may be missing on different search paths, and are not portable persistence contracts. Keep training data, preprocessing, feature schema, row IDs, metric, and software versions with the model.

A transform is meaningful only for samples supported by the training distribution. It does not update the trained embedding. Inverse output is in the preprocessed feature space; use the fitted scaler's inverse_transform to restore units when appropriate. Avoid treating interpolated samples between separated groups as scientifically realizable observations.

ParametricUMAP Class

umap.parametric_umap.ParametricUMAP(batch_size=None, dims=None, encoder=None, decoder=None, parametric_reconstruction=False, parametric_reconstruction_loss_fcn=None, parametric_reconstruction_loss_weight=1.0, autoencoder_loss=False, reconstruction_validation=None, global_correlation_loss_weight=0, landmark_loss_fn=None, landmark_loss_weight=1.0, keras_fit_kwargs={}, **kwargs)

Install with uv pip install "umap-learn[parametric-umap]==0.5.12". The released module imports TensorFlow and Keras 3 (keras.ops) even though the package extra only declares tensorflow>=2.1; resolve a compatible modern pair. The parametric source was reviewed; neural training/persistence was not executed in this audit.

Additional Parameters (beyond UMAP)

encoder (Keras 3 Model, default: None)

Keras model for encoding data to embeddings. If None, uses default 3-layer architecture with 100 neurons per layer.

decoder (Keras 3 Model, default: None)

Keras model for decoding embeddings back to data space. Only used if parametric_reconstruction=True.

parametric_reconstruction (bool, default: False)

Enable a decoder-based inverse. A default decoder is built when none is supplied.

parametric_reconstruction_loss_fcn (callable, default: None)

Custom reconstruction loss. Default is binary cross entropy from logits, with targets in [0, 1] and a linear decoder output. For continuous standardized features, choose an appropriate loss such as mean squared error; inverse decoder outputs are logits under the default loss.

parametric_reconstruction_loss_weight (float, default: 1.0)

Weight applied to the parametric reconstruction loss.

autoencoder_loss (bool, default: False)

With parametric_reconstruction=True, also backpropagate reconstruction loss through the encoder; otherwise the encoder is trained on the embedding objective.

global_correlation_loss_weight (float, default: 0)

Weight for global correlation loss, used to encourage preservation of broad distance relationships.

reconstruction_validation (array, default: None)

Held-out feature array X_val, not an (X_val, y_val) tuple. Preprocess it using training-fitted transforms.

dims (tuple, default: None)

Input shape for reshaping features before neural fitting. Inferred for flat features; supply it for a structured input such as images. Encoder output dimension must match n_components. At inference, provide the encoder input shape; transform does not repeat training-time reshaping.

batch_size (int, default: None)

Batch size for neural network training. If None, determined automatically.

landmark_loss_fn (callable, default: None)

Loss function used when retraining with landmark positions.

landmark_loss_weight (float, default: 1.0)

Weight applied to landmark loss relative to the UMAP loss.

keras_fit_kwargs (dict, default: {})

Additional keyword arguments passed to the Keras fit() method.

Training epoch attributes

ParametricUMAP initializes n_training_epochs=1 and loss_report_frequency=10 internally. Set these attributes after construction when you need longer neural-network training.

Methods

fit and fit_transform accept (X, y=None, precomputed_distances=None, landmark_positions=None), not the base class finite-check keyword. transform(X, batch_size=None) calls the encoder. inverse_transform(X) calls a trained decoder only when parametric_reconstruction=True; otherwise it falls back to the ordinary approximate inverse. Do not assume every base-class mode or update method is a supported neural workflow.

fit(X, y=None, precomputed_distances=None, landmark_positions=None)

Fit the parametric model. landmark_positions can be used for landmarked retraining workflows.

save(save_location, verbose=True, exclude_raw_data=False)

Create save_location first, then save the object and networks. load_ParametricUMAP(save_location, verbose=True) reads a pickle and Keras files: load only trusted directories. In released 0.5.12 the saver writes parametric_model.keras, but the loader checks parametric_model. Validate encoder/decoder predictions after roundtrip and do not claim full training-state restoration. exclude_raw_data=True removes selected raw-data attributes during saving, not every possible training-data representation.

Utility functions

Import these from umap.umap_, not from the top-level umap package. They expose lower-level implementation details; ordinary workflows should use UMAP.

from umap.umap_ import (
    nearest_neighbors, fuzzy_simplicial_set, simplicial_set_embedding, find_ab_params,
)

nearest_neighbors(X, n_neighbors, metric, metric_kwds, angular, random_state, low_memory=True, use_pynndescent=True, n_jobs=-1, verbose=False) returns (indices, distances, search_index). The third value is an NNDescent index on the approximate-search path, or None for precomputed distances.
fuzzy_simplicial_set(X, n_neighbors, random_state, metric, metric_kwds={}, knn_indices=None, knn_dists=None, angular=False, set_op_mix_ratio=1.0, local_connectivity=1.0, apply_set_operations=True, verbose=False, return_dists=None) returns (graph, sigmas, rhos) when return_dists=None. Passing False or True adds a fourth item: None or the sparse distances.
simplicial_set_embedding(data, graph, n_components, initial_alpha, a, b, gamma, negative_sample_rate, n_epochs, init, random_state, metric, metric_kwds, densmap, densmap_kwds, output_dens, output_metric=euclidean_grad, output_metric_kwds={}, euclidean_output=True, parallel=False, verbose=False, tqdm_kwds=None) returns (embedding, auxiliary_data). euclidean_grad denotes the function in umap.distances, not a string metric.
find_ab_params(spread, min_dist) returns (a, b) for the embedding curve.

AlignedUMAP Class

umap.AlignedUMAP(n_neighbors=15, n_components=2, metric='euclidean', metric_kwds=None, n_epochs=None, learning_rate=1.0, init='spectral', alignment_regularisation=0.01, alignment_window_size=3, min_dist=0.1, spread=1.0, low_memory=False, set_op_mix_ratio=1.0, local_connectivity=1.0, repulsion_strength=1.0, negative_sample_rate=5, transform_queue_size=4.0, a=None, b=None, random_state=None, angular_rp_forest=False, target_n_neighbors=-1, target_metric='categorical', target_metric_kwds=None, target_weight=0.5, transform_seed=42, force_approximation_algorithm=False, verbose=False, unique=False)

UMAP variant for aligning multiple related datasets.

Additional Parameters

alignment_regularisation (float, default: 1e-2)

Strength of alignment regularization between datasets.

alignment_window_size (int, default: 3)

Number of slices to consider on either side; consecutive mappings are chained across the window.

Methods

fit(X, y=None, **fit_params)

Fit model to multiple datasets.

Parameters:

X: list of arrays - List of datasets to align
relations: required keyword in fit_params; list of len(X)-1 dictionaries mapping previous-slice row index -> next-slice row index. Use stable scientific IDs to construct one-to-one matches; validate ranges and missing/duplicate matches. Each mapping must be nonempty. Partial mappings are allowed; unrelated rows need no match.
fit returns self; fit_transform returns embeddings_. No ordinary new-row transform is implemented.

update(X, y=None, **fit_params)

Append a dataset using one dictionary passed as relations={previous_slice_index: new_slice_index}. This has the same forward direction as each dictionary used by fit, not a backward mapping from the new slice. The method mutates the model and returns None in 0.5.12. Do not assign its return to the mapper.

Attributes

embeddings_

list of arrays - List of aligned embeddings, one per input dataset.

Usage Examples

Basic Usage with All Common Parameters

import umap

# Standard 2D visualization embedding
reducer = umap.UMAP(
    n_neighbors=15,          # Balance local/global structure
    n_components=2,          # Output dimensions
    metric='euclidean',      # Distance metric
    min_dist=0.1,           # Effective packing parameter, not a hard bound
    spread=1.0,             # Scale of embedded points
    random_state=42,        # Reproducibility
    n_epochs=200,           # Training iterations (None = auto)
    learning_rate=1.0,      # SGD learning rate
    init='spectral',        # Initialization method
    low_memory=True,        # Memory-efficient mode
    verbose=True            # Print progress
)

embedding = reducer.fit_transform(data)

Supervised Learning

# Train with labels for class separation
reducer = umap.UMAP(
    n_neighbors=15,
    target_weight=0.5,           # Balance data structure vs labels
    target_metric='categorical',  # Metric for labels
    random_state=42
)

embedding = reducer.fit_transform(data, y=labels)

Clustering Preprocessing

# Candidate settings for clustering; compare to an unreduced baseline
reducer = umap.UMAP(
    n_neighbors=30,      # More global structure
    min_dist=0.0,        # Allow tight packing
    n_components=10,     # Higher-dimensional candidate; density is still distorted
    metric='euclidean',
    random_state=42
)

embedding = reducer.fit_transform(data)

Custom Distance Metric

from numba import njit

@njit()
def custom_distance(x, y):
    """Custom distance function (must be Numba-compatible)"""
    result = 0.0
    for i in range(x.shape[0]):
        result += abs(x[i] - y[i])
    return result

reducer = umap.UMAP(metric=custom_distance, random_state=42, n_jobs=1)
embedding = reducer.fit_transform(data)

Parametric UMAP with Custom Architecture (illustrative, not executed)

import keras
from umap.parametric_umap import ParametricUMAP

# Define custom encoder
encoder = keras.Sequential([
    keras.layers.InputLayer(shape=(input_dim,)),
    keras.layers.Dense(256, activation='relu'),
    keras.layers.Dropout(0.3),
    keras.layers.Dense(128, activation='relu'),
    keras.layers.Dropout(0.3),
    keras.layers.Dense(2)  # Output dimension
])

# Define decoder for reconstruction
decoder = keras.Sequential([
    keras.layers.InputLayer(shape=(2,)),
    keras.layers.Dense(128, activation='relu'),
    keras.layers.Dense(256, activation='relu'),
    keras.layers.Dense(input_dim)
])

# Linear decoder and MSE suit continuous features (e.g., training-standardized data).
# Train parametric UMAP with autoencoder
embedder = ParametricUMAP(
    encoder=encoder,
    decoder=decoder,
    dims=(input_dim,),
    parametric_reconstruction=True,
    parametric_reconstruction_loss_fcn=keras.losses.MeanSquaredError(),
    autoencoder_loss=True,
    batch_size=128,
    n_neighbors=15,
    min_dist=0.1,
    random_state=42
)
embedder.n_training_epochs = 10

embedding = embedder.fit_transform(data)
new_embedding = embedder.transform(new_data)
reconstructed = embedder.inverse_transform(embedding)

DensMAP for Density Preservation

# Preserve local density information
reducer = umap.UMAP(
    densmap=True,           # Enable DensMAP
    dens_lambda=2.0,       # Weight of density preservation
    dens_frac=0.3,         # Final fraction of optimization epochs
    output_dens=True,      # Output log local radii, not probabilities
    n_neighbors=15,
    min_dist=0.1,
    random_state=42
)

embedding, rad_orig, rad_emb = reducer.fit_transform(data)
assert rad_orig.shape == rad_emb.shape == (len(data),)

Aligned UMAP for Time Series

from umap import AlignedUMAP

# Multiple related datasets (e.g., different time points)
datasets = [day1_data, day2_data, day3_data, day4_data]
relations = [
    {day1_idx: day2_idx for day1_idx, day2_idx in matched_day1_to_day2},
    {day2_idx: day3_idx for day2_idx, day3_idx in matched_day2_to_day3},
    {day3_idx: day4_idx for day3_idx, day4_idx in matched_day3_to_day4},
]

# Align embeddings
mapper = AlignedUMAP(
    n_neighbors=15,
    alignment_regularisation=1e-2,  # Alignment strength
    alignment_window_size=2,        # Align with adjacent datasets
    n_components=2,
    random_state=42
)

mapper.fit(datasets, relations=relations)

# Access aligned embeddings
aligned_embeddings = mapper.embeddings_
# aligned_embeddings[0] is day1 embedding
# aligned_embeddings[1] is day2 embedding, etc.

Precomputed distances and neighbors

Distance matrices must be nonnegative and finite with training shape (n, n), symmetric with zero diagonal. Do not pass a similarity matrix or a new-to-new matrix to transform. Dense storage costs quadratic memory.

from sklearn.metrics import pairwise_distances

D_train = pairwise_distances(X_train)
D_test_to_train = pairwise_distances(X_test, X_train)
mapper = umap.UMAP(metric="precomputed", n_neighbors=10,
                   random_state=42, n_jobs=1)
train_embedding = mapper.fit_transform(D_train)
test_embedding = mapper.transform(D_test_to_train)
assert test_embedding.shape == (len(X_test), 2)

For repeated fits on the same features, reuse a neighbor search instead:

from sklearn.utils import check_random_state
from umap.umap_ import nearest_neighbors

knn = nearest_neighbors(data, n_neighbors=30, metric="euclidean",
                        metric_kwds={}, angular=False,
                        random_state=check_random_state(42), n_jobs=1)
mapper = umap.UMAP(n_neighbors=30, precomputed_knn=knn,
                   random_state=42, n_jobs=1).fit(data)
new_embedding = mapper.transform(new_data)

Do not reuse neighbors after changing row order, features, scaling, metric, or training folds. Retain the compatible search index for transforms; just the two neighbor arrays suffice for fitting but not for transforming new samples.

Official sources reviewed

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs network access, Needs Python

The author says: Requires Python 3.9+ and umap-learn; optional HDBSCAN, Matplotlib, and TensorFlow with Keras 3. Network access is needed for installation, not local fitting.