umap-learn

UMAP-Learn

概要

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

クイックスタート

インストール

現在の安定版リリース：umap-learn 0.5.12（2026年4月リリース）。Python 3.9+ が必要で、scikit-learn>=1.6、numba、pynndescent、numpy、scipy に依存します。検証済みのリリースを固定してください。

uv pip install umap-learn==0.5.12

基本的な使い方

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

前処理の要件： メトリックに合わせて前処理を行ってください。数値データのユークリッド系メトリックでは、分散の大きい列が支配的にならないよう、適合前に特徴量をスケーリングします。コサイン、二値データ、事前計算済み距離、または混合特徴量のワークフローでは、すべての列を無条件に標準化するのではなく、メトリックに合った前処理を選択してください。

一般的なワークフロー

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'）

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

サポートされているメトリック：

• ミンコフスキー系： 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)

主なメリット：

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

半教師あり 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)

使用する場面： ラベル付けにコストがかかる場合や、利用できるラベルよりデータのほうが多い場合に使用します。

クラスタリングでの UMAP

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

クラスタリングのベストプラクティス

重要な原則： 可視化の場合とは異なる設定を UMAP に適用します。

推奨パラメーター：

• n_neighbors： 約30に増やします（デフォルトの15では局所的すぎて、人工的に細分化されたクラスタが生じる可能性があります）
• min_dist： 0.0に設定します（クラスタ内の点を密にまとめ、境界を明確にします）
• n_components： 5～10次元を使用します（2次元と比べて密度の保持を改善しつつ、パフォーマンスを維持します）

クラスタリングのワークフロー

密度ベースのクラスタリングを行うには、HDBSCAN を別途インストールします。

uv pip install hdbscan

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)}")

クラスタリング後の可視化

# 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 は密度を完全には保持せず、人工的なクラスタの分割を生じさせることがあります。結果として得られるクラスタは、必ず検証して詳しく調べてください。

新しいデータの変換

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

transform の基本的な使い方

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

機械学習パイプラインとの統合

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}")

重要な考慮事項

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

パフォーマンス： 変換処理は効率的です（通常は1秒未満）が、初回の呼び出しは Numba の JIT コンパイルにより遅くなる場合があります。

Scikit-learn との互換性： UMAP は標準的な sklearn の規約に従っており、パイプラインで動作します。最近の 0.5.x リリースでは、特徴量名のサポートと、現行の scikit-learn 検証 API との互換性も改善されています。

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)
feature_names = pipeline.named_steps['umap'].get_feature_names_out()

高度な機能

詳細、コード例、パラメーターテーブルについては、references/advanced-features.md を参照してください。この手順が該当する場合にお読みください。

再現性

再現可能な結果を得るには、必ず random_state パラメーターを設定してください。

reducer = umap.UMAP(random_state=42)

UMAP は確率的最適化を使用するため、乱数状態を固定しない場合、実行のたびに結果がわずかに異なります。

random_state を設定すると、決定論的な出力が優先されます。厳密な再現性より処理速度が重要な場合は、設定せずにおいてください。固定シードがないほうが、UMAP はより多くの並列処理を利用できます。

よくある問題と解決策

問題： コンポーネントが分断される、またはクラスターが細分化される

• 解決策： n_neighbors を大きくして、よりグローバルな構造を重視します

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

• 解決策： min_dist を小さくして、より密に配置できるようにします

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

• 解決策： クラスタリングに特化したパラメーター（n_neighbors=30、min_dist=0.0、n_components=5-10）を使用します

問題： 変換結果が学習時と大きく異なる

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

問題： 大規模なデータセットで処理が遅い

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

問題： 入力データに NaN または inf の値がある

• 解決策： フィッティングの前に、無効な行を補完するか削除します。現在の UMAP は fit() と update() で scikit-learn 形式の有限値チェック（ensure_all_finite）を使用しているため、数値入力をクリーンに保つのが最も安全なデフォルトです

問題： すべての点が単一のクラスターに集約される

• 解決策： データの前処理を確認し（適切にスケーリングされていることを確認）、min_dist を大きくします

問題： インポートが実際のパッケージではなくローカルファイルを参照する

• 解決策： ノートブックやスクリプトと同じ場所に、umap.py、sklearn.py、hdbscan.py、tensorflow.py という名前のプロジェクトファイルを置かないでください。これらの名前はインストール済みパッケージをシャドーイングし、サンプルを壊したり不正な状態にしたりする可能性があります。

リソース

公式ドキュメント

• UMAP ユーザーガイド
• リリースノート
• PyPI パッケージ（現在の安定版：0.5.12）
• GitHub リポジトリ

references/

詳細な API ドキュメントが含まれています：

• api_reference.md：UMAP クラスのパラメーターとメソッドの完全な一覧

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

エージェントの作業手順

1. 環境を確認します。 Python 環境とライブラリのバージョン（python -c "import pkg; print(pkg.__version__)"）を確認し、データの形状、型、欠損値を調べます。
2. 入力を確定します。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値は推測せず、質問してください。
3. まず小規模に実行します。 まずサンプルまたは単一のフォールドで実行し、実行時間とメモリを確認します。
4. 上記の指示とリファレンスを使用して、タスク全体を実行します。
5. 結果を検証します。 ホールドアウトデータ、固定したランダムシード、適切な指標を使用し、データ漏洩を確認して、不確実性（CI、シード間の標準偏差）を報告します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を明記します。

これが発生した場合	対応
メモリ不足、または実行が非常に遅い	サブサンプリング、チャンク化または遅延計算を使用するか、モデルのサイズを小さくし、変更内容をユーザーに伝えます。
この手順に記載された関数、フラグ、またはエンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して適宜対応し、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、またはパラメーターが曖昧	ユーザーに質問するか、実行前に前提を明示します。

インテグリティに関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造しないでください。実行または検証できない場合は、その旨を明確に伝えてください。
• このセッションで計算していない指標を報告してはいけません。すべての数値について、その生成に使ったコードの流れを示してください。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する操作、共有 GPU やクラウドのクォータを消費する操作、個人データや患者データを扱う操作、または元に戻せない操作を行う前に、確認を求めてください。

関連スキル

• scanpy：標準的なシングルセル RNA-seq 解析パイプラインです。
• tensorboard：PyTorch SummaryWriter と TensorFlow/Keras コールバックを使用して、TensorBoard で ML トレーニングデータを記録・表示します。スカラー値、画像、テキスト、ヒストグラムなどに対応します…
• sentence-transformers：事前学習済みの Hugging Fac… を使用し、Python の sentence-transformers（SBERT）ライブラリで文、テキスト、画像の埋め込みをローカルで生成します。