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 preserve local and global structure, supervised learning, and clustering preprocessing.

## Quick Start

### Installation

```bash
uv pip install umap-learn
```

### Basic Usage

UMAP follows scikit-learn conventions and can be used as a drop-in replacement for t-SNE or PCA.

```python
import umap
from sklearn.preprocessing import StandardScaler

# Prepare data (standardization is essential)
scaled_data = StandardScaler().fit_transform(data)

# Method 1: Single step (fit and transform)
embedding = umap.UMAP().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
```

**Critical preprocessing requirement:** Always standardize features to comparable scales before applying UMAP to ensure equal weighting across dimensions.

### Typical Workflow

```python
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 and adjust based on results. Increase for more global structure, decrease for more local detail.

### min_dist (default: 0.1)

**Purpose:** Controls how tightly points cluster in the low-dimensional space.

**How it works:** Sets the minimum distance apart that points are allowed to be in the output representation.

**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):** Prevents tight packing; emphasizes broad topological preservation over local structure

**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 (better preserves density than 2D)
- **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

```python
# 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 preserving global structure
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, enabling class separation while preserving internal structure.

### Supervised UMAP

Pass target labels via the `y` parameter when fitting:

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

**Key benefits:**
- Achieves cleanly separated classes
- Preserves internal structure within each class
- Maintains global relationships between classes

**When to use:** When you have labeled data and want to separate known classes while keeping meaningful point embeddings.

### Semi-Supervised UMAP

For partial labels, mark unlabeled points with `-1` following scikit-learn convention:

```python
# 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.

### Metric Learning with UMAP

Train a supervised embedding on labeled data, then apply to new unlabeled data:

```python
# Train on labeled data
mapper = umap.UMAP().fit(train_data, train_labels)

# Transform unlabeled test data
test_embedding = mapper.transform(test_data)

# Use as feature engineering for downstream classifier
from sklearn.svm import SVC
clf = SVC().fit(mapper.embedding_, train_labels)
predictions = clf.predict(test_embedding)
```

**When to use:** For supervised feature engineering in machine learning pipelines.

## UMAP for Clustering

UMAP serves as effective preprocessing for density-based clustering algorithms like HDBSCAN, overcoming the curse of dimensionality.

### Best Practices for Clustering

**Key principle:** Configure UMAP differently for clustering than for visualization.

**Recommended parameters:**
- **n_neighbors:** Increase to ~30 (default 15 is too local and can create artificial fine-grained clusters)
- **min_dist:** Set to 0.0 (pack points densely within clusters for clearer boundaries)
- **n_components:** Use 5-10 dimensions (maintains performance while improving density preservation vs. 2D)

### Clustering Workflow

```python
import umap
import hdbscan
from sklearn.preprocessing import StandardScaler

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

# 2. UMAP with clustering-optimized parameters
reducer = umap.UMAP(
    n_neighbors=30,
    min_dist=0.0,
    n_components=10,  # Higher than 2 for better density preservation
    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
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

```python
# 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()
```

**Important caveat:** UMAP does not completely preserve density and can create artificial cluster divisions. Always validate and explore resulting clusters.

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

```python
# 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

```python
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)

# 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:** The transform method assumes the overall distribution in the higher-dimensional space is consistent between training and test data. When this assumption fails, consider using Parametric UMAP instead.

**Performance:** Transform operations are efficient (typically <1 second), though initial calls may be slower due to Numba JIT compilation.

**Scikit-learn compatibility:** UMAP follows standard sklearn conventions and works seamlessly in pipelines:

```python
from sklearn.pipeline import Pipeline

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

pipeline.fit(X_train, y_train)
predictions = pipeline.predict(X_test)
```

## Advanced Features

### 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:**
```bash
uv pip install umap-learn[parametric_umap]
# Requires TensorFlow 2.x
```

**Basic usage:**
```python
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:**
```python
import tensorflow as tf

# Define custom encoder
encoder = tf.keras.Sequential([
    tf.keras.layers.InputLayer(input_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)
```

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

**When to use standard UMAP:**
- Need simplicity and quick prototyping
- Dataset is small and computational efficiency isn't critical
- Don't require learned transformations for future data

### Inverse Transforms

Inverse transforms enable reconstruction of high-dimensional data from low-dimensional embeddings.

**Basic usage:**
```python
reducer = umap.UMAP()
embedding = reducer.fit_transform(data)

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

**Important limitations:**
- Computationally expensive operation
- Works poorly outside the convex hull of the embedding
- Accuracy decreases in regions with gaps between clusters

**Use cases:**
- Understanding structure of embedded data
- Visualizing smooth transitions between clusters
- Exploring interpolations between data points
- Generating synthetic samples in embedding space

**Example: Exploring embedding space:**
```python
import numpy as np

# Create grid of points in embedding space
x = np.linspace(embedding[:, 0].min(), embedding[:, 0].max(), 10)
y = np.linspace(embedding[:, 1].min(), embedding[:, 1].max(), 10)
xx, yy = np.meshgrid(x, y)
grid_points = np.c_[xx.ravel(), yy.ravel()]

# Reconstruct samples from grid
reconstructed_samples = reducer.inverse_transform(grid_points)
```

### AlignedUMAP

For analyzing temporal or related datasets (e.g., time-series experiments, batch data):

```python
from umap import AlignedUMAP

# List of related datasets
datasets = [day1_data, day2_data, day3_data]

# Create aligned embeddings
mapper = AlignedUMAP().fit(datasets)
aligned_embeddings = mapper.embeddings_  # List of embeddings
```

**When to use:** Comparing embeddings across related datasets while maintaining consistent coordinate systems.

## Reproducibility

To ensure reproducible results, always set the `random_state` parameter:

```python
reducer = umap.UMAP(random_state=42)
```

UMAP uses stochastic optimization, so results will vary slightly between runs without a fixed random state.

## Common Issues and Solutions

**Issue:** Disconnected components or fragmented clusters
- **Solution:** Increase `n_neighbors` to emphasize more global structure

**Issue:** Clusters too spread out or not well separated
- **Solution:** Decrease `min_dist` to allow tighter packing

**Issue:** Poor clustering results
- **Solution:** Use clustering-specific parameters (n_neighbors=30, min_dist=0.0, n_components=5-10)

**Issue:** Transform results differ significantly from training
- **Solution:** Ensure test data distribution matches training, or use Parametric UMAP

**Issue:** Slow performance on large datasets
- **Solution:** Set `low_memory=True` (default), or consider dimensionality reduction with PCA first

**Issue:** All points collapsed to single cluster
- **Solution:** Check data preprocessing (ensure proper scaling), increase `min_dist`

## Resources

### references/

Contains detailed API documentation:
- `api_reference.md`: Complete UMAP class parameters and methods

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

{
  "format": "aiskill/v1",
  "skill": {
    "name": "umap-learn",
    "slug": "umap-learn",
    "version": "1.0.0",
    "description": "UMAP dimensionality reduction. Fast nonlinear manifold learning for 2D/3D visualization, clustering preprocessing (HDBSCAN), supervised/parametric UMAP, for high-dimensional data.",
    "category": "Research",
    "tags": [
      "research-science",
      "data-viz"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "BSD-3-CLAUSE LICENSE"
  },
  "prompts": {
    "system": "# UMAP-Learn\r\n\r\n## Overview\r\n\r\nUMAP (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 preserve local and global structure, supervised learning, and clustering preprocessing.\r\n\r\n## Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\nuv pip install umap-learn\r\n```\r\n\r\n### Basic Usage\r\n\r\nUMAP follows scikit-learn conventions and can be used as a drop-in replacement for t-SNE or PCA.\r\n\r\n```python\r\nimport umap\r\nfrom sklearn.preprocessing import StandardScaler\r\n\r\n# Prepare data (standardization is essential)\r\nscaled_data = StandardScaler().fit_transform(data)\r\n\r\n# Method 1: Single step (fit and transform)\r\nembedding = umap.UMAP().fit_transform(scaled_data)\r\n\r\n# Method 2: Separate steps (for reusing trained model)\r\nreducer = umap.UMAP(random_state=42)\r\nreducer.fit(scaled_data)\r\nembedding = reducer.embedding_  # Access the trained embedding\r\n```\r\n\r\n**Critical preprocessing requirement:** Always standardize features to comparable scales before applying UMAP to ensure equal weighting across dimensions.\r\n\r\n### Typical Workflow\r\n\r\n```python\r\nimport umap\r\nimport matplotlib.pyplot as plt\r\nfrom sklearn.preprocessing import StandardScaler\r\n\r\n# 1. Preprocess data\r\nscaler = StandardScaler()\r\nscaled_data = scaler.fit_transform(raw_data)\r\n\r\n# 2. Create and fit UMAP\r\nreducer = umap.UMAP(\r\n    n_neighbors=15,\r\n    min_dist=0.1,\r\n    n_components=2,\r\n    metric='euclidean',\r\n    random_state=42\r\n)\r\nembedding = reducer.fit_transform(scaled_data)\r\n\r\n# 3. Visualize\r\nplt.scatter(embedding[:, 0], embedding[:, 1], c=labels, cmap='Spectral', s=5)\r\nplt.colorbar()\r\nplt.title('UMAP Embedding')\r\nplt.show()\r\n```\r\n\r\n## Parameter Tuning Guide\r\n\r\nUMAP has four primary parameters that control the embedding behavior. Understanding these is crucial for effective usage.\r\n\r\n### n_neighbors (default: 15)\r\n\r\n**Purpose:** Balances local versus global structure in the embedding.\r\n\r\n**How it works:** Controls the size of the local neighborhood UMAP examines when learning manifold structure.\r\n\r\n**Effects by value:**\r\n- **Low values (2-5):** Emphasizes fine local detail but may fragment data into disconnected components\r\n- **Medium values (15-20):** Balanced view of both local structure and global relationships (recommended starting point)\r\n- **High values (50-200):** Prioritizes broad topological structure at the expense of fine-grained details\r\n\r\n**Recommendation:** Start with 15 and adjust based on results. Increase for more global structure, decrease for more local detail.\r\n\r\n### min_dist (default: 0.1)\r\n\r\n**Purpose:** Controls how tightly points cluster in the low-dimensional space.\r\n\r\n**How it works:** Sets the minimum distance apart that points are allowed to be in the output representation.\r\n\r\n**Effects by value:**\r\n- **Low values (0.0-0.1):** Creates clumped embeddings useful for clustering; reveals fine topological details\r\n- **High values (0.5-0.99):** Prevents tight packing; emphasizes broad topological preservation over local structure\r\n\r\n**Recommendation:** Use 0.0 for clustering applications, 0.1-0.3 for visualization, 0.5+ for loose structure.\r\n\r\n### n_components (default: 2)\r\n\r\n**Purpose:** Determines the dimensionality of the embedded output space.\r\n\r\n**Key feature:** Unlike t-SNE, UMAP scales well in the embedding dimension, enabling use beyond visualization.\r\n\r\n**Common uses:**\r\n- **2-3 dimensions:** Visualization\r\n- **5-10 dimensions:** Clustering preprocessing (better preserves density than 2D)\r\n- **10-50 dimensions:** Feature engineering for downstream ML models\r\n\r\n**Recommendation:** Use 2 for visualization, 5-10 for clustering, higher for ML pipelines.\r\n\r\n### metric (default: 'euclidean')\r\n\r\n**Purpose:** Specifies how distance is calculated between input data points.\r\n\r\n**Supported metrics:**\r\n- **Minkowski variants:** euclidean, manhattan, chebyshev\r\n- **Spatial metrics:** canberra, braycurtis, haversine\r\n- **Correlation metrics:** cosine, correlation (good for text/document embeddings)\r\n- **Binary data metrics:** hamming, jaccard, dice, russellrao, kulsinski, rogerstanimoto, sokalmichener, sokalsneath, yule\r\n- **Custom metrics:** User-defined distance functions via Numba\r\n\r\n**Recommendation:** Use euclidean for numeric data, cosine for text/document vectors, hamming for binary data.\r\n\r\n### Parameter Tuning Example\r\n\r\n```python\r\n# For visualization with emphasis on local structure\r\numap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='euclidean')\r\n\r\n# For clustering preprocessing\r\numap.UMAP(n_neighbors=30, min_dist=0.0, n_components=10, metric='euclidean')\r\n\r\n# For document embeddings\r\numap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='cosine')\r\n\r\n# For preserving global structure\r\numap.UMAP(n_neighbors=100, min_dist=0.5, n_components=2, metric='euclidean')\r\n```\r\n\r\n## Supervised and Semi-Supervised Dimension Reduction\r\n\r\nUMAP supports incorporating label information to guide the embedding process, enabling class separation while preserving internal structure.\r\n\r\n### Supervised UMAP\r\n\r\nPass target labels via the `y` parameter when fitting:\r\n\r\n```python\r\n# Supervised dimension reduction\r\nembedding = umap.UMAP().fit_transform(data, y=labels)\r\n```\r\n\r\n**Key benefits:**\r\n- Achieves cleanly separated classes\r\n- Preserves internal structure within each class\r\n- Maintains global relationships between classes\r\n\r\n**When to use:** When you have labeled data and want to separate known classes while keeping meaningful point embeddings.\r\n\r\n### Semi-Supervised UMAP\r\n\r\nFor partial labels, mark unlabeled points with `-1` following scikit-learn convention:\r\n\r\n```python\r\n# Create semi-supervised labels\r\nsemi_labels = labels.copy()\r\nsemi_labels[unlabeled_indices] = -1\r\n\r\n# Fit with partial labels\r\nembedding = umap.UMAP().fit_transform(data, y=semi_labels)\r\n```\r\n\r\n**When to use:** When labeling is expensive or you have more data than labels available.\r\n\r\n### Metric Learning with UMAP\r\n\r\nTrain a supervised embedding on labeled data, then apply to new unlabeled data:\r\n\r\n```python\r\n# Train on labeled data\r\nmapper = umap.UMAP().fit(train_data, train_labels)\r\n\r\n# Transform unlabeled test data\r\ntest_embedding = mapper.transform(test_data)\r\n\r\n# Use as feature engineering for downstream classifier\r\nfrom sklearn.svm import SVC\r\nclf = SVC().fit(mapper.embedding_, train_labels)\r\npredictions = clf.predict(test_embedding)\r\n```\r\n\r\n**When to use:** For supervised feature engineering in machine learning pipelines.\r\n\r\n## UMAP for Clustering\r\n\r\nUMAP serves as effective preprocessing for density-based clustering algorithms like HDBSCAN, overcoming the curse of dimensionality.\r\n\r\n### Best Practices for Clustering\r\n\r\n**Key principle:** Configure UMAP differently for clustering than for visualization.\r\n\r\n**Recommended parameters:**\r\n- **n_neighbors:** Increase to ~30 (default 15 is too local and can create artificial fine-grained clusters)\r\n- **min_dist:** Set to 0.0 (pack points densely within clusters for clearer boundaries)\r\n- **n_components:** Use 5-10 dimensions (maintains performance while improving density preservation vs. 2D)\r\n\r\n### Clustering Workflow\r\n\r\n```python\r\nimport umap\r\nimport hdbscan\r\nfrom sklearn.preprocessing import StandardScaler\r\n\r\n# 1. Preprocess data\r\nscaled_data = StandardScaler().fit_transform(data)\r\n\r\n# 2. UMAP with clustering-optimized parameters\r\nreducer = umap.UMAP(\r\n    n_neighbors=30,\r\n    min_dist=0.0,\r\n    n_components=10,  # Higher than 2 for better density preservation\r\n    metric='euclidean',\r\n    random_state=42\r\n)\r\nembedding = reducer.fit_transform(scaled_data)\r\n\r\n# 3. Apply HDBSCAN clustering\r\nclusterer = hdbscan.HDBSCAN(\r\n    min_cluster_size=15,\r\n    min_samples=5,\r\n    metric='euclidean'\r\n)\r\nlabels = clusterer.fit_predict(embedding)\r\n\r\n# 4. Evaluate\r\nfrom sklearn.metrics import adjusted_rand_score\r\nscore = adjusted_rand_score(true_labels, labels)\r\nprint(f\"Adjusted Rand Score: {score:.3f}\")\r\nprint(f\"Number of clusters: {len(set(labels)) - (1 if -1 in labels else 0)}\")\r\nprint(f\"Noise points: {sum(labels == -1)}\")\r\n```\r\n\r\n### Visualization After Clustering\r\n\r\n```python\r\n# Create 2D embedding for visualization (separate from clustering)\r\nvis_reducer = umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, random_state=42)\r\nvis_embedding = vis_reducer.fit_transform(scaled_data)\r\n\r\n# Plot with cluster labels\r\nimport matplotlib.pyplot as plt\r\nplt.scatter(vis_embedding[:, 0], vis_embedding[:, 1], c=labels, cmap='Spectral', s=5)\r\nplt.colorbar()\r\nplt.title('UMAP Visualization with HDBSCAN Clusters')\r\nplt.show()\r\n```\r\n\r\n**Important caveat:** UMAP does not completely preserve density and can create artificial cluster divisions. Always validate and explore resulting clusters.\r\n\r\n## Transforming New Data\r\n\r\nUMAP enables preprocessing of new data through its `transform()` method, allowing trained models to project unseen data into the learned embedding space.\r\n\r\n### Basic Transform Usage\r\n\r\n```python\r\n# Train on training data\r\ntrans = umap.UMAP(n_neighbors=15, random_state=42).fit(X_train)\r\n\r\n# Transform test data\r\ntest_embedding = trans.transform(X_test)\r\n```\r\n\r\n### Integration with Machine Learning Pipelines\r\n\r\n```python\r\nfrom sklearn.svm import SVC\r\nfrom sklearn.model_selection import train_test_split\r\nfrom sklearn.preprocessing import StandardScaler\r\nimport umap\r\n\r\n# Split data\r\nX_train, X_test, y_train, y_test = train_test_split(data, labels, test_size=0.2)\r\n\r\n# Preprocess\r\nscaler = StandardScaler()\r\nX_train_scaled = scaler.fit_transform(X_train)\r\nX_test_scaled = scaler.transform(X_test)\r\n\r\n# Train UMAP\r\nreducer = umap.UMAP(n_components=10, random_state=42)\r\nX_train_embedded = reducer.fit_transform(X_train_scaled)\r\nX_test_embedded = reducer.transform(X_test_scaled)\r\n\r\n# Train classifier on embeddings\r\nclf = SVC()\r\nclf.fit(X_train_embedded, y_train)\r\naccuracy = clf.score(X_test_embedded, y_test)\r\nprint(f\"Test accuracy: {accuracy:.3f}\")\r\n```\r\n\r\n### Important Considerations\r\n\r\n**Data consistency:** The transform method assumes the overall distribution in the higher-dimensional space is consistent between training and test data. When this assumption fails, consider using Parametric UMAP instead.\r\n\r\n**Performance:** Transform operations are efficient (typically <1 second), though initial calls may be slower due to Numba JIT compilation.\r\n\r\n**Scikit-learn compatibility:** UMAP follows standard sklearn conventions and works seamlessly in pipelines:\r\n\r\n```python\r\nfrom sklearn.pipeline import Pipeline\r\n\r\npipeline = Pipeline([\r\n    ('scaler', StandardScaler()),\r\n    ('umap', umap.UMAP(n_components=10)),\r\n    ('classifier', SVC())\r\n])\r\n\r\npipeline.fit(X_train, y_train)\r\npredictions = pipeline.predict(X_test)\r\n```\r\n\r\n## Advanced Features\r\n\r\n### Parametric UMAP\r\n\r\nParametric UMAP replaces direct embedding optimization with a learned neural network mapping function.\r\n\r\n**Key differences from standard UMAP:**\r\n- Uses TensorFlow/Keras to train encoder networks\r\n- Enables efficient transformation of new data\r\n- Supports reconstruction via decoder networks (inverse transform)\r\n- Allows custom architectures (CNNs for images, RNNs for sequences)\r\n\r\n**Installation:**\r\n```bash\r\nuv pip install umap-learn[parametric_umap]\r\n# Requires TensorFlow 2.x\r\n```\r\n\r\n**Basic usage:**\r\n```python\r\nfrom umap.parametric_umap import ParametricUMAP\r\n\r\n# Default architecture (3-layer 100-neuron fully-connected network)\r\nembedder = ParametricUMAP()\r\nembedding = embedder.fit_transform(data)\r\n\r\n# Transform new data efficiently\r\nnew_embedding = embedder.transform(new_data)\r\n```\r\n\r\n**Custom architecture:**\r\n```python\r\nimport tensorflow as tf\r\n\r\n# Define custom encoder\r\nencoder = tf.keras.Sequential([\r\n    tf.keras.layers.InputLayer(input_shape=(input_dim,)),\r\n    tf.keras.layers.Dense(128, activation='relu'),\r\n    tf.keras.layers.Dense(64, activation='relu'),\r\n    tf.keras.layers.Dense(2)  # Output dimension\r\n])\r\n\r\nembedder = ParametricUMAP(encoder=encoder, dims=(input_dim,))\r\nembedding = embedder.fit_transform(data)\r\n```\r\n\r\n**When to use Parametric UMAP:**\r\n- Need efficient transformation of new data after training\r\n- Require reconstruction capabilities (inverse transforms)\r\n- Want to combine UMAP with autoencoders\r\n- Working with complex data types (images, sequences) benefiting from specialized architectures\r\n\r\n**When to use standard UMAP:**\r\n- Need simplicity and quick prototyping\r\n- Dataset is small and computational efficiency isn't critical\r\n- Don't require learned transformations for future data\r\n\r\n### Inverse Transforms\r\n\r\nInverse transforms enable reconstruction of high-dimensional data from low-dimensional embeddings.\r\n\r\n**Basic usage:**\r\n```python\r\nreducer = umap.UMAP()\r\nembedding = reducer.fit_transform(data)\r\n\r\n# Reconstruct high-dimensional data from embedding coordinates\r\nreconstructed = reducer.inverse_transform(embedding)\r\n```\r\n\r\n**Important limitations:**\r\n- Computationally expensive operation\r\n- Works poorly outside the convex hull of the embedding\r\n- Accuracy decreases in regions with gaps between clusters\r\n\r\n**Use cases:**\r\n- Understanding structure of embedded data\r\n- Visualizing smooth transitions between clusters\r\n- Exploring interpolations between data points\r\n- Generating synthetic samples in embedding space\r\n\r\n**Example: Exploring embedding space:**\r\n```python\r\nimport numpy as np\r\n\r\n# Create grid of points in embedding space\r\nx = np.linspace(embedding[:, 0].min(), embedding[:, 0].max(), 10)\r\ny = np.linspace(embedding[:, 1].min(), embedding[:, 1].max(), 10)\r\nxx, yy = np.meshgrid(x, y)\r\ngrid_points = np.c_[xx.ravel(), yy.ravel()]\r\n\r\n# Reconstruct samples from grid\r\nreconstructed_samples = reducer.inverse_transform(grid_points)\r\n```\r\n\r\n### AlignedUMAP\r\n\r\nFor analyzing temporal or related datasets (e.g., time-series experiments, batch data):\r\n\r\n```python\r\nfrom umap import AlignedUMAP\r\n\r\n# List of related datasets\r\ndatasets = [day1_data, day2_data, day3_data]\r\n\r\n# Create aligned embeddings\r\nmapper = AlignedUMAP().fit(datasets)\r\naligned_embeddings = mapper.embeddings_  # List of embeddings\r\n```\r\n\r\n**When to use:** Comparing embeddings across related datasets while maintaining consistent coordinate systems.\r\n\r\n## Reproducibility\r\n\r\nTo ensure reproducible results, always set the `random_state` parameter:\r\n\r\n```python\r\nreducer = umap.UMAP(random_state=42)\r\n```\r\n\r\nUMAP uses stochastic optimization, so results will vary slightly between runs without a fixed random state.\r\n\r\n## Common Issues and Solutions\r\n\r\n**Issue:** Disconnected components or fragmented clusters\r\n- **Solution:** Increase `n_neighbors` to emphasize more global structure\r\n\r\n**Issue:** Clusters too spread out or not well separated\r\n- **Solution:** Decrease `min_dist` to allow tighter packing\r\n\r\n**Issue:** Poor clustering results\r\n- **Solution:** Use clustering-specific parameters (n_neighbors=30, min_dist=0.0, n_components=5-10)\r\n\r\n**Issue:** Transform results differ significantly from training\r\n- **Solution:** Ensure test data distribution matches training, or use Parametric UMAP\r\n\r\n**Issue:** Slow performance on large datasets\r\n- **Solution:** Set `low_memory=True` (default), or consider dimensionality reduction with PCA first\r\n\r\n**Issue:** All points collapsed to single cluster\r\n- **Solution:** Check data preprocessing (ensure proper scaling), increase `min_dist`\r\n\r\n## Resources\r\n\r\n### references/\r\n\r\nContains detailed API documentation:\r\n- `api_reference.md`: Complete UMAP class parameters and methods\r\n\r\nLoad these references when detailed parameter information or advanced method usage is needed.",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The umap-learn/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/umap-learn",
    "exported_at": "2026-11-03T07:44:18.046Z"
  }
}

format: aiskill/v1
skill:
  name: umap-learn
  slug: umap-learn
  version: 1.0.0
  description: >-
    UMAP dimensionality reduction. Fast nonlinear manifold learning for 2D/3D visualization,
    clustering preprocessing (HDBSCAN), supervised/parametric UMAP, for high-dimensional data.
  category: Research
  tags:
    - research-science
    - data-viz
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: BSD-3-CLAUSE LICENSE
prompts:
  system: "# UMAP-Learn\r\n\r\n## Overview\r\n\r\nUMAP (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 preserve local and global structure, supervised learning, and clustering preprocessing.\r\n\r\n## Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\nuv pip install umap-learn\r\n```\r\n\r\n### Basic Usage\r\n\r\nUMAP follows scikit-learn conventions and can be used as a drop-in replacement for t-SNE or PCA.\r\n\r\n```python\r\nimport umap\r\nfrom sklearn.preprocessing import StandardScaler\r\n\r\n# Prepare data (standardization is essential)\r\nscaled_data = StandardScaler().fit_transform(data)\r\n\r\n# Method 1: Single step (fit and transform)\r\nembedding = umap.UMAP().fit_transform(scaled_data)\r\n\r\n# Method 2: Separate steps (for reusing trained model)\r\nreducer = umap.UMAP(random_state=42)\r\nreducer.fit(scaled_data)\r\nembedding = reducer.embedding_  # Access the trained embedding\r\n```\r\n\r\n**Critical preprocessing requirement:** Always standardize features to comparable scales before applying UMAP to ensure equal weighting across dimensions.\r\n\r\n### Typical Workflow\r\n\r\n```python\r\nimport umap\r\nimport matplotlib.pyplot as plt\r\nfrom sklearn.preprocessing import StandardScaler\r\n\r\n# 1. Preprocess data\r\nscaler = StandardScaler()\r\nscaled_data = scaler.fit_transform(raw_data)\r\n\r\n# 2. Create and fit UMAP\r\nreducer = umap.UMAP(\r\n    n_neighbors=15,\r\n    min_dist=0.1,\r\n    n_components=2,\r\n    metric='euclidean',\r\n    random_state=42\r\n)\r\nembedding = reducer.fit_transform(scaled_data)\r\n\r\n# 3. Visualize\r\nplt.scatter(embedding[:, 0], embedding[:, 1], c=labels, cmap='Spectral', s=5)\r\nplt.colorbar()\r\nplt.title('UMAP Embedding')\r\nplt.show()\r\n```\r\n\r\n## Parameter Tuning Guide\r\n\r\nUMAP has four primary parameters that control the embedding behavior. Understanding these is crucial for effective usage.\r\n\r\n### n_neighbors (default: 15)\r\n\r\n**Purpose:** Balances local versus global structure in the embedding.\r\n\r\n**How it works:** Controls the size of the local neighborhood UMAP examines when learning manifold structure.\r\n\r\n**Effects by value:**\r\n- **Low values (2-5):** Emphasizes fine local detail but may fragment data into disconnected components\r\n- **Medium values (15-20):** Balanced view of both local structure and global relationships (recommended starting point)\r\n- **High values (50-200):** Prioritizes broad topological structure at the expense of fine-grained details\r\n\r\n**Recommendation:** Start with 15 and adjust based on results. Increase for more global structure, decrease for more local detail.\r\n\r\n### min_dist (default: 0.1)\r\n\r\n**Purpose:** Controls how tightly points cluster in the low-dimensional space.\r\n\r\n**How it works:** Sets the minimum distance apart that points are allowed to be in the output representation.\r\n\r\n**Effects by value:**\r\n- **Low values (0.0-0.1):** Creates clumped embeddings useful for clustering; reveals fine topological details\r\n- **High values (0.5-0.99):** Prevents tight packing; emphasizes broad topological preservation over local structure\r\n\r\n**Recommendation:** Use 0.0 for clustering applications, 0.1-0.3 for visualization, 0.5+ for loose structure.\r\n\r\n### n_components (default: 2)\r\n\r\n**Purpose:** Determines the dimensionality of the embedded output space.\r\n\r\n**Key feature:** Unlike t-SNE, UMAP scales well in the embedding dimension, enabling use beyond visualization.\r\n\r\n**Common uses:**\r\n- **2-3 dimensions:** Visualization\r\n- **5-10 dimensions:** Clustering preprocessing (better preserves density than 2D)\r\n- **10-50 dimensions:** Feature engineering for downstream ML models\r\n\r\n**Recommendation:** Use 2 for visualization, 5-10 for clustering, higher for ML pipelines.\r\n\r\n### metric (default: 'euclidean')\r\n\r\n**Purpose:** Specifies how distance is calculated between input data points.\r\n\r\n**Supported metrics:**\r\n- **Minkowski variants:** euclidean, manhattan, chebyshev\r\n- **Spatial metrics:** canberra, braycurtis, haversine\r\n- **Correlation metrics:** cosine, correlation (good for text/document embeddings)\r\n- **Binary data metrics:** hamming, jaccard, dice, russellrao, kulsinski, rogerstanimoto, sokalmichener, sokalsneath, yule\r\n- **Custom metrics:** User-defined distance functions via Numba\r\n\r\n**Recommendation:** Use euclidean for numeric data, cosine for text/document vectors, hamming for binary data.\r\n\r\n### Parameter Tuning Example\r\n\r\n```python\r\n# For visualization with emphasis on local structure\r\numap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='euclidean')\r\n\r\n# For clustering preprocessing\r\numap.UMAP(n_neighbors=30, min_dist=0.0, n_components=10, metric='euclidean')\r\n\r\n# For document embeddings\r\numap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='cosine')\r\n\r\n# For preserving global structure\r\numap.UMAP(n_neighbors=100, min_dist=0.5, n_components=2, metric='euclidean')\r\n```\r\n\r\n## Supervised and Semi-Supervised Dimension Reduction\r\n\r\nUMAP supports incorporating label information to guide the embedding process, enabling class separation while preserving internal structure.\r\n\r\n### Supervised UMAP\r\n\r\nPass target labels via the `y` parameter when fitting:\r\n\r\n```python\r\n# Supervised dimension reduction\r\nembedding = umap.UMAP().fit_transform(data, y=labels)\r\n```\r\n\r\n**Key benefits:**\r\n- Achieves cleanly separated classes\r\n- Preserves internal structure within each class\r\n- Maintains global relationships between classes\r\n\r\n**When to use:** When you have labeled data and want to separate known classes while keeping meaningful point embeddings.\r\n\r\n### Semi-Supervised UMAP\r\n\r\nFor partial labels, mark unlabeled points with `-1` following scikit-learn convention:\r\n\r\n```python\r\n# Create semi-supervised labels\r\nsemi_labels = labels.copy()\r\nsemi_labels[unlabeled_indices] = -1\r\n\r\n# Fit with partial labels\r\nembedding = umap.UMAP().fit_transform(data, y=semi_labels)\r\n```\r\n\r\n**When to use:** When labeling is expensive or you have more data than labels available.\r\n\r\n### Metric Learning with UMAP\r\n\r\nTrain a supervised embedding on labeled data, then apply to new unlabeled data:\r\n\r\n```python\r\n# Train on labeled data\r\nmapper = umap.UMAP().fit(train_data, train_labels)\r\n\r\n# Transform unlabeled test data\r\ntest_embedding = mapper.transform(test_data)\r\n\r\n# Use as feature engineering for downstream classifier\r\nfrom sklearn.svm import SVC\r\nclf = SVC().fit(mapper.embedding_, train_labels)\r\npredictions = clf.predict(test_embedding)\r\n```\r\n\r\n**When to use:** For supervised feature engineering in machine learning pipelines.\r\n\r\n## UMAP for Clustering\r\n\r\nUMAP serves as effective preprocessing for density-based clustering algorithms like HDBSCAN, overcoming the curse of dimensionality.\r\n\r\n### Best Practices for Clustering\r\n\r\n**Key principle:** Configure UMAP differently for clustering than for visualization.\r\n\r\n**Recommended parameters:**\r\n- **n_neighbors:** Increase to ~30 (default 15 is too local and can create artificial fine-grained clusters)\r\n- **min_dist:** Set to 0.0 (pack points densely within clusters for clearer boundaries)\r\n- **n_components:** Use 5-10 dimensions (maintains performance while improving density preservation vs. 2D)\r\n\r\n### Clustering Workflow\r\n\r\n```python\r\nimport umap\r\nimport hdbscan\r\nfrom sklearn.preprocessing import StandardScaler\r\n\r\n# 1. Preprocess data\r\nscaled_data = StandardScaler().fit_transform(data)\r\n\r\n# 2. UMAP with clustering-optimized parameters\r\nreducer = umap.UMAP(\r\n    n_neighbors=30,\r\n    min_dist=0.0,\r\n    n_components=10,  # Higher than 2 for better density preservation\r\n    metric='euclidean',\r\n    random_state=42\r\n)\r\nembedding = reducer.fit_transform(scaled_data)\r\n\r\n# 3. Apply HDBSCAN clustering\r\nclusterer = hdbscan.HDBSCAN(\r\n    min_cluster_size=15,\r\n    min_samples=5,\r\n    metric='euclidean'\r\n)\r\nlabels = clusterer.fit_predict(embedding)\r\n\r\n# 4. Evaluate\r\nfrom sklearn.metrics import adjusted_rand_score\r\nscore = adjusted_rand_score(true_labels, labels)\r\nprint(f\"Adjusted Rand Score: {score:.3f}\")\r\nprint(f\"Number of clusters: {len(set(labels)) - (1 if -1 in labels else 0)}\")\r\nprint(f\"Noise points: {sum(labels == -1)}\")\r\n```\r\n\r\n### Visualization After Clustering\r\n\r\n```python\r\n# Create 2D embedding for visualization (separate from clustering)\r\nvis_reducer = umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, random_state=42)\r\nvis_embedding = vis_reducer.fit_transform(scaled_data)\r\n\r\n# Plot with cluster labels\r\nimport matplotlib.pyplot as plt\r\nplt.scatter(vis_embedding[:, 0], vis_embedding[:, 1], c=labels, cmap='Spectral', s=5)\r\nplt.colorbar()\r\nplt.title('UMAP Visualization with HDBSCAN Clusters')\r\nplt.show()\r\n```\r\n\r\n**Important caveat:** UMAP does not completely preserve density and can create artificial cluster divisions. Always validate and explore resulting clusters.\r\n\r\n## Transforming New Data\r\n\r\nUMAP enables preprocessing of new data through its `transform()` method, allowing trained models to project unseen data into the learned embedding space.\r\n\r\n### Basic Transform Usage\r\n\r\n```python\r\n# Train on training data\r\ntrans = umap.UMAP(n_neighbors=15, random_state=42).fit(X_train)\r\n\r\n# Transform test data\r\ntest_embedding = trans.transform(X_test)\r\n```\r\n\r\n### Integration with Machine Learning Pipelines\r\n\r\n```python\r\nfrom sklearn.svm import SVC\r\nfrom sklearn.model_selection import train_test_split\r\nfrom sklearn.preprocessing import StandardScaler\r\nimport umap\r\n\r\n# Split data\r\nX_train, X_test, y_train, y_test = train_test_split(data, labels, test_size=0.2)\r\n\r\n# Preprocess\r\nscaler = StandardScaler()\r\nX_train_scaled = scaler.fit_transform(X_train)\r\nX_test_scaled = scaler.transform(X_test)\r\n\r\n# Train UMAP\r\nreducer = umap.UMAP(n_components=10, random_state=42)\r\nX_train_embedded = reducer.fit_transform(X_train_scaled)\r\nX_test_embedded = reducer.transform(X_test_scaled)\r\n\r\n# Train classifier on embeddings\r\nclf = SVC()\r\nclf.fit(X_train_embedded, y_train)\r\naccuracy = clf.score(X_test_embedded, y_test)\r\nprint(f\"Test accuracy: {accuracy:.3f}\")\r\n```\r\n\r\n### Important Considerations\r\n\r\n**Data consistency:** The transform method assumes the overall distribution in the higher-dimensional space is consistent between training and test data. When this assumption fails, consider using Parametric UMAP instead.\r\n\r\n**Performance:** Transform operations are efficient (typically <1 second), though initial calls may be slower due to Numba JIT compilation.\r\n\r\n**Scikit-learn compatibility:** UMAP follows standard sklearn conventions and works seamlessly in pipelines:\r\n\r\n```python\r\nfrom sklearn.pipeline import Pipeline\r\n\r\npipeline = Pipeline([\r\n    ('scaler', StandardScaler()),\r\n    ('umap', umap.UMAP(n_components=10)),\r\n    ('classifier', SVC())\r\n])\r\n\r\npipeline.fit(X_train, y_train)\r\npredictions = pipeline.predict(X_test)\r\n```\r\n\r\n## Advanced Features\r\n\r\n### Parametric UMAP\r\n\r\nParametric UMAP replaces direct embedding optimization with a learned neural network mapping function.\r\n\r\n**Key differences from standard UMAP:**\r\n- Uses TensorFlow/Keras to train encoder networks\r\n- Enables efficient transformation of new data\r\n- Supports reconstruction via decoder networks (inverse transform)\r\n- Allows custom architectures (CNNs for images, RNNs for sequences)\r\n\r\n**Installation:**\r\n```bash\r\nuv pip install umap-learn[parametric_umap]\r\n# Requires TensorFlow 2.x\r\n```\r\n\r\n**Basic usage:**\r\n```python\r\nfrom umap.parametric_umap import ParametricUMAP\r\n\r\n# Default architecture (3-layer 100-neuron fully-connected network)\r\nembedder = ParametricUMAP()\r\nembedding = embedder.fit_transform(data)\r\n\r\n# Transform new data efficiently\r\nnew_embedding = embedder.transform(new_data)\r\n```\r\n\r\n**Custom architecture:**\r\n```python\r\nimport tensorflow as tf\r\n\r\n# Define custom encoder\r\nencoder = tf.keras.Sequential([\r\n    tf.keras.layers.InputLayer(input_shape=(input_dim,)),\r\n    tf.keras.layers.Dense(128, activation='relu'),\r\n    tf.keras.layers.Dense(64, activation='relu'),\r\n    tf.keras.layers.Dense(2)  # Output dimension\r\n])\r\n\r\nembedder = ParametricUMAP(encoder=encoder, dims=(input_dim,))\r\nembedding = embedder.fit_transform(data)\r\n```\r\n\r\n**When to use Parametric UMAP:**\r\n- Need efficient transformation of new data after training\r\n- Require reconstruction capabilities (inverse transforms)\r\n- Want to combine UMAP with autoencoders\r\n- Working with complex data types (images, sequences) benefiting from specialized architectures\r\n\r\n**When to use standard UMAP:**\r\n- Need simplicity and quick prototyping\r\n- Dataset is small and computational efficiency isn't critical\r\n- Don't require learned transformations for future data\r\n\r\n### Inverse Transforms\r\n\r\nInverse transforms enable reconstruction of high-dimensional data from low-dimensional embeddings.\r\n\r\n**Basic usage:**\r\n```python\r\nreducer = umap.UMAP()\r\nembedding = reducer.fit_transform(data)\r\n\r\n# Reconstruct high-dimensional data from embedding coordinates\r\nreconstructed = reducer.inverse_transform(embedding)\r\n```\r\n\r\n**Important limitations:**\r\n- Computationally expensive operation\r\n- Works poorly outside the convex hull of the embedding\r\n- Accuracy decreases in regions with gaps between clusters\r\n\r\n**Use cases:**\r\n- Understanding structure of embedded data\r\n- Visualizing smooth transitions between clusters\r\n- Exploring interpolations between data points\r\n- Generating synthetic samples in embedding space\r\n\r\n**Example: Exploring embedding space:**\r\n```python\r\nimport numpy as np\r\n\r\n# Create grid of points in embedding space\r\nx = np.linspace(embedding[:, 0].min(), embedding[:, 0].max(), 10)\r\ny = np.linspace(embedding[:, 1].min(), embedding[:, 1].max(), 10)\r\nxx, yy = np.meshgrid(x, y)\r\ngrid_points = np.c_[xx.ravel(), yy.ravel()]\r\n\r\n# Reconstruct samples from grid\r\nreconstructed_samples = reducer.inverse_transform(grid_points)\r\n```\r\n\r\n### AlignedUMAP\r\n\r\nFor analyzing temporal or related datasets (e.g., time-series experiments, batch data):\r\n\r\n```python\r\nfrom umap import AlignedUMAP\r\n\r\n# List of related datasets\r\ndatasets = [day1_data, day2_data, day3_data]\r\n\r\n# Create aligned embeddings\r\nmapper = AlignedUMAP().fit(datasets)\r\naligned_embeddings = mapper.embeddings_  # List of embeddings\r\n```\r\n\r\n**When to use:** Comparing embeddings across related datasets while maintaining consistent coordinate systems.\r\n\r\n## Reproducibility\r\n\r\nTo ensure reproducible results, always set the `random_state` parameter:\r\n\r\n```python\r\nreducer = umap.UMAP(random_state=42)\r\n```\r\n\r\nUMAP uses stochastic optimization, so results will vary slightly between runs without a fixed random state.\r\n\r\n## Common Issues and Solutions\r\n\r\n**Issue:** Disconnected components or fragmented clusters\r\n- **Solution:** Increase `n_neighbors` to emphasize more global structure\r\n\r\n**Issue:** Clusters too spread out or not well separated\r\n- **Solution:** Decrease `min_dist` to allow tighter packing\r\n\r\n**Issue:** Poor clustering results\r\n- **Solution:** Use clustering-specific parameters (n_neighbors=30, min_dist=0.0, n_components=5-10)\r\n\r\n**Issue:** Transform results differ significantly from training\r\n- **Solution:** Ensure test data distribution matches training, or use Parametric UMAP\r\n\r\n**Issue:** Slow performance on large datasets\r\n- **Solution:** Set `low_memory=True` (default), or consider dimensionality reduction with PCA first\r\n\r\n**Issue:** All points collapsed to single cluster\r\n- **Solution:** Check data preprocessing (ensure proper scaling), increase `min_dist`\r\n\r\n## Resources\r\n\r\n### references/\r\n\r\nContains detailed API documentation:\r\n- `api_reference.md`: Complete UMAP class parameters and methods\r\n\r\nLoad these references when detailed parameter information or advanced method usage is needed."
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The umap-learn/ folder contains
        SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/umap-learn
  exported_at: "2026-11-03T07:44:18.046Z"