UMAP (Uniform Manifold Approximation and Projection)

Warnings

• gotcha UMAP is stochastic, and results are not reproducible without setting `random_state`. This applies to both `UMAP` initialization and any subsequent operations like `transform`.
  Fix: Always pass an integer value to the `random_state` parameter during `UMAP` object initialization, e.g., `umap.UMAP(random_state=42)`.
• gotcha The `n_neighbors` and `min_dist` parameters heavily influence the resulting manifold structure. Choosing appropriate values is critical for meaningful results, and defaults may not always be optimal for specific datasets.
  Fix: Experiment with different values for `n_neighbors` (e.g., 5 to 50) and `min_dist` (e.g., 0.0 to 0.5). Higher `n_neighbors` captures more global structure, while lower `min_dist` allows for tighter clustering.
• gotcha The `transform` method for new, out-of-sample data points performs an *approximate* projection. It is not guaranteed to perfectly preserve the relationships from the training data or match the quality of the `fit_transform` method.
  Fix: Understand that `transform` is an approximation. If exact embeddings for new data are critical, consider retraining UMAP on the combined dataset or evaluating the stability of the transformation for your application. For small changes to the dataset, `update` might be an option.
• gotcha UMAP's performance relies heavily on `numba` for just-in-time compilation. Issues with `numba` installation or environment configuration (e.g., older compilers) can lead to significant performance degradation or errors.
  Fix: Ensure `numba` is correctly installed and compatible with your Python environment. Check for any `numba` warnings upon import or during execution. Refer to the `numba` documentation for troubleshooting installation issues.
• gotcha UMAP is not inherently scale-invariant. Features with larger scales will have a disproportionately larger influence on the distance calculations and the resulting manifold structure.
  Fix: It is generally recommended to preprocess data by scaling or normalizing features before applying UMAP, e.g., using `sklearn.preprocessing.StandardScaler` or `MinMaxScaler`.

Install

• pip install umap-learn Install stable version

Imports

• UMAP

  import umap
  reducer = umap.UMAP()

  The primary class `UMAP` is typically imported from the top-level `umap` module, not `umap_learn`.
• UMAP

  from umap import UMAP

  Direct import from `umap` module.

Quickstart

This quickstart demonstrates how to use `umap-learn` to reduce the dimensionality of a synthetic dataset. It covers generating data, initializing the `UMAP` reducer with common parameters, and performing the fit and transform operation.

import umap
from sklearn.datasets import make_blobs

# 1. Generate some sample data
X, y = make_blobs(n_samples=500, centers=4, cluster_std=1.0, random_state=42)

# 2. Initialize UMAP reducer
# n_neighbors: Balances local vs. global structure. Larger values preserve more global structure.
# min_dist: Controls how tightly points are packed together. Smaller values lead to denser clusters.
# n_components: Desired dimensionality of the output embedding.
# random_state: For reproducible results.
reducer = umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, random_state=42)

# 3. Fit and transform the data
embedding = reducer.fit_transform(X)

# The 'embedding' now contains the 2D projection of the original data
print(f"Original data shape: {X.shape}")
print(f"UMAP embedding shape: {embedding.shape}")
# print(embedding[:5]) # Display first 5 embedded points