umap-learn

UMAP-Learn

概要

UMAP（Uniform Manifold Approximation and Projection）は、可視化および汎用的な非線形次元削減のための次元削減手法です。局所構造と大域構造の両方を保持する、高速でスケーラブルな埋め込み、教師あり学習、クラスタリングの前処理にこのスキルを適用してください。

クイックスタート

インストール

uv pip install umap-learn

基本的な使い方

UMAP は scikit-learn の規約に従っており、t-SNE や PCA の代替としてそのまま使用できます。

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

重要な前処理の要件: UMAP を適用する前に、次元間で等しい重みが付くよう、必ず特徴量を比較可能なスケールに標準化してください。

典型的なワークフロー

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

パラメータチューニングガイド

UMAP には埋め込みの挙動を制御する主要なパラメータが 4 つあります。効果的に使用するには、これらを理解することが重要です。

n_neighbors（デフォルト: 15）

目的: 埋め込みにおける局所構造と大域構造のバランスを取ります。

仕組み: UMAP が多様体構造を学習する際に調べる局所近傍のサイズを制御します。

値ごとの効果:

• 低い値（2〜5）: 細かい局所的詳細を強調しますが、データが非連結な成分に分断されることがあります
• 中程度の値（15〜20）: 局所構造と大域的な関係の両方をバランス良く捉えます（推奨される出発点）
• 高い値（50〜200）: 細部よりも広い位相構造を優先します

推奨事項: 15 から始めて、結果に応じて調整してください。より大域的な構造を得たい場合は増やし、より局所的な詳細を得たい場合は減らしてください。

min_dist（デフォルト: 0.1）

目的: 低次元空間において点がどの程度密集するかを制御します。

仕組み: 出力表現において、点同士が取り得る最小距離を設定します。

値ごとの効果:

• 低い値（0.0〜0.1）: クラスタリングに有用な密集した埋め込みを生成し、細かい位相的詳細を明らかにします
• 高い値（0.5〜0.99）: 点が密集しすぎるのを防ぎ、局所構造よりも広い位相の保持を重視します

推奨事項: クラスタリングには 0.0、可視化には 0.1〜0.3、ゆるやかな構造には 0.5 以上を使用してください。

n_components（デフォルト: 2）

目的: 埋め込み後の出力空間の次元数を決定します。

主な特徴: t-SNE と異なり、UMAP は埋め込み次元が増えてもうまくスケールするため、可視化以外の用途にも使用できます。

一般的な用途:

• 2〜3 次元: 可視化
• 5〜10 次元: クラスタリングの前処理（2 次元よりも密度をよく保持します）
• 10〜50 次元: 後段の ML モデルのための特徴量エンジニアリング

推奨事項: 可視化には 2、クラスタリングには 5〜10、ML パイプラインにはより高い値を使用してください。

metric（デフォルト: 'euclidean'）

目的: 入力データ点間の距離の計算方法を指定します。

対応するメトリック:

• Minkowski 系: euclidean、manhattan、chebyshev
• 空間メトリック: canberra、braycurtis、haversine
• 相関メトリック: cosine、correlation（テキストや文書の埋め込みに適しています）
• バイナリデータ用メトリック: hamming、jaccard、dice、russellrao、kulsinski、rogerstanimoto、sokalmichener、sokalsneath、yule
• カスタムメトリック: Numba を介したユーザー定義の距離関数

推奨事項: 数値データには euclidean、テキストや文書ベクトルには cosine、バイナリデータには hamming を使用してください。

パラメータチューニングの例

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

教師ありおよび半教師ありの次元削減

UMAP は、内部構造を保持しながらクラスの分離を可能にするため、ラベル情報を埋め込みプロセスに取り込むことをサポートしています。

教師あり UMAP

フィット時に y パラメータで目標ラベルを渡します:

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

主な利点:

• クラスを明確に分離できます
• 各クラス内部の構造を保持します
• クラス間の大域的な関係を維持します

使用する場面: ラベル付きデータがあり、意味のある点の埋め込みを保ちながら既知のクラスを分離したい場合。

Semi-Supervised UMAP

部分的なラベルがある場合は、scikit-learn の慣例に従ってラベルのない点を -1 でマークします:

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

使用するタイミング: ラベル付けにコストがかかる場合、またはラベルよりもデータが多い場合。

Metric Learning with UMAP

ラベル付きデータで教師ありの埋め込みを学習し、その後で新しいラベルなしデータに適用します:

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

使用するタイミング: 機械学習パイプラインで教師あり特徴量エンジニアリングを行う場合。

UMAP for Clustering

UMAP は、HDBSCAN のような密度ベースのクラスタリングアルゴリズムに対する効果的な前処理として機能し、次元の呪いを克服します。

Best Practices for Clustering

重要な原則: クラスタリングの場合は、可視化の場合とは異なる方法で UMAP を設定します。

推奨パラメータ:

• n_neighbors: 約 30 に増やします(デフォルトの 15 は局所的すぎて、人為的に細かいクラスターを生成することがあります)
• min_dist: 0.0 に設定します(クラスター内で点を密に詰め、より明確な境界を得ます)
• n_components: 5〜10 次元を使用します(2D と比べて、性能を維持しつつ密度の保存を改善します)

Clustering Workflow

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

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

重要な注意点: UMAP は密度を完全には保存できず、人為的なクラスターの分割を生じさせることがあります。得られたクラスターは必ず検証し、探索してください。

Transforming New Data

UMAP は transform() メソッドを通じて新しいデータの前処理を可能にし、学習済みモデルで未見のデータを学習済みの埋め込み空間に射影できます。

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)

# 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

データの一貫性: transform メソッドは、学習データとテストデータの間で高次元空間における全体の分布が一貫していることを前提としています。この前提が成り立たない場合は、代わりに Parametric UMAP の使用を検討してください。

パフォーマンス: transform の処理は効率的です(通常 1 秒未満)が、最初の呼び出しは Numba の JIT コンパイルにより遅くなることがあります。

scikit-learn との互換性: UMAP は標準的な sklearn の慣例に従っており、パイプラインにシームレスに組み込めます:

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 は、直接的な埋め込みの最適化を、学習されたニューラルネットワークによる写像関数に置き換えます。

標準 UMAP との主な違い:

• TensorFlow/Keras を使用してエンコーダーネットワークを学習します
• 新しいデータの効率的な変換を可能にします
• デコーダーネットワークによる再構成(逆変換)をサポートします
• カスタムアーキテクチャを許可します(画像向けの CNN、系列向けの RNN など)

インストール:

uv pip install umap-learn[parametric_umap]
# Requires TensorFlow 2.x

基本的な使い方:

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)

カスタムアーキテクチャ:

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)

Parametric UMAP を使用するタイミング:

• 学習後に新しいデータを効率的に変換する必要がある場合
• 再構成機能(逆変換)が必要な場合
• UMAP をオートエンコーダーと組み合わせたい場合
• 専用のアーキテクチャの恩恵を受ける複雑なデータ型(画像、系列)を扱う場合

標準 UMAP を使用するタイミング:

• シンプルさと迅速なプロトタイピングが必要な場合
• データセットが小さく、計算効率がそれほど重要でない場合
• 将来のデータに対する学習済みの変換が不要な場合

Inverse Transforms

逆変換は、低次元の埋め込みから高次元データを再構成することを可能にします。

基本的な使い方:

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

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

重要な制限事項:

• 計算コストの高い操作です
• 埋め込みの凸包の外側では精度が低くなります
• クラスター間に隙間がある領域では精度が低下します

ユースケース:

• 埋め込まれたデータの構造を理解する
• クラスター間の滑らかな遷移を可視化する
• データ点間の補間を調べる
• 埋め込み空間で合成サンプルを生成する

例: 埋め込み空間の探索:

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

時系列実験やバッチデータなど、時間的に関連するデータセットや関連するデータセットの分析には:

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

使用するタイミング: 関連するデータセット間で、一貫した座標系を維持しながら埋め込みを比較する場合。

再現性

結果を再現可能にするため、必ず random_state パラメーターを設定してください:

reducer = umap.UMAP(random_state=42)

UMAP は確率的最適化を使用するため、固定の random state を指定しない場合、実行ごとに結果がわずかに変わります。

よくある問題と解決策

問題: 非連結成分や断片化したクラスター

• 解決策: n_neighbors を大きくして、より大域的な構造を重視する

問題: クラスターが広がりすぎている、または十分に分離されていない

• 解決策: min_dist を小さくして、より密にまとめる

問題: クラスタリング結果が良くない

• 解決策: クラスタリング向けのパラメーター（n_neighbors=30, min_dist=0.0, n_components=5-10）を使用する

問題: transform の結果が学習時と大きく異なる

• 解決策: テストデータの分布が学習データと一致していることを確認するか、Parametric UMAP を使用する

問題: 大規模データセットでの処理速度が遅い

• 解決策: low_memory=True（デフォルト）を設定するか、先に PCA による次元削減を行うことを検討する

問題: すべての点が単一のクラスターに潰れてしまう

• 解決策: データの前処理（適切なスケーリングが行われているか）を確認し、min_dist を大きくする

リソース

references/

詳細な API ドキュメントを含みます:

• api_reference.md: UMAP クラスのパラメーターとメソッドの完全なリファレンス

詳細なパラメーター情報や高度なメソッドの使い方が必要な場合は、これらのリファレンスを読み込んでください。