umap-learn

Was macht umap-learn?

Überblick

UMAP (Uniform Manifold Approximation and Projection) ist eine Technik zur Dimensionsreduktion für die Visualisierung und allgemeine nichtlineare Dimensionsreduktion. Wenden Sie dieses Skill an für schnelle, skalierbare Einbettungen, die lokale und globale Strukturen bewahren, überwachtes Lernen und die Vorverarbeitung von Clustern.

Schnellstart

Installation

Aktuelle stabile Version: umap-learn 0.5.12 (veröffentlicht April 2026). Erfordert Python 3.9+ und hängt ab von scikit-learn>=1.6, numba, pynndescent, numpy und scipy. Fixieren Sie eine verifizierte Version:

uv pip install umap-learn==0.5.12

Grundlegende Verwendung

UMAP folgt den scikit-learn Konventionen und kann als direkter Ersatz für t-SNE oder PCA verwendet werden.

import umap
from sklearn.preprocessing import StandardScaler

# Daten vorbereiten (Standardisierung ist entscheidend)
scaled_data = StandardScaler().fit_transform(data)

# Methode 1: Einzelschritt (anpassen und transformieren)
embedding = umap.UMAP().fit_transform(scaled_data)

# Methode 2: Getrennte Schritte (zur Wiederverwendung des trainierten Modells)
reducer = umap.UMAP(random_state=42)
reducer.fit(scaled_data)
embedding = reducer.embedding_  # Auf die trainierte Einbettung zugreifen

Vorverarbeitungsanforderung: Passen Sie die Vorverarbeitung an die Metrik an. Für numerische euklidische Metriken skalieren Sie die Merkmale vor dem Anpassen, sodass Spalten mit hoher Varianz nicht dominieren. Für Kosinus-, Binär-, vorberechnete Distanz- oder gemischte Merkmals-Workflows wählen Sie eine Vorverarbeitung, die zur Metrik passt, anstatt jede Spalte blind zu standardisieren.

Typischer Workflow

import umap
import matplotlib.pyplot as plt
from sklearn.preprocessing import StandardScaler

# 1. Daten vorverarbeiten
scaler = StandardScaler()
scaled_data = scaler.fit_transform(raw_data)

# 2. UMAP erstellen und anpassen
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. Visualisieren
plt.scatter(embedding[:, 0], embedding[:, 1], c=labels, cmap='Spectral', s=5)
plt.colorbar()
plt.title('UMAP Embedding')
plt.show()

Leitfaden zur Parametereinstellung

UMAP hat vier primäre Parameter, die das Einbettungsverhalten steuern. Das Verständnis dieser ist entscheidend für eine effektive Nutzung.

n_neighbors (Standard: 15)

Zweck: Balanciert lokale versus globale Struktur in der Einbettung.

Funktionsweise: Steuert die Größe der lokalen Nachbarschaft, die UMAP beim Lernen der Mannigfaltigkeitsstruktur untersucht.

Auswirkungen nach Wert:

• Niedrige Werte (2-5): Betont feine lokale Details, kann Daten jedoch in nicht zusammenhängende Komponenten fragmentieren
• Mittlere Werte (15-20): Ausgewogene Sicht auf sowohl lokale als auch globale Beziehungen (empfohlener Startpunkt)
• Hohe Werte (50-200): Priorisiert breite topologische Struktur auf Kosten feiner Details

Empfehlung: Beginnen Sie mit 15 und passen Sie basierend auf den Ergebnissen an. Erhöhen Sie für mehr globale Struktur, verringern Sie für mehr lokale Details.

min_dist (Standard: 0.1)

Zweck: Steuert, wie eng Punkte im niedrigdimensionalen Raum gruppiert werden.

Funktionsweise: Legt den minimalen Abstand fest, den Punkte in der Ausgabedarstellung haben dürfen.

Auswirkungen nach Wert:

• Niedrige Werte (0.0-0.1): Erzeugt klumpige Einbettungen, die für das Clustering nützlich sind; zeigt feine topologische Details
• Hohe Werte (0.5-0.99): Verhindert dichte Packung; betont breite topologische Bewahrung über lokale Struktur

Empfehlung: Verwenden Sie 0.0 für Clusteranwendungen, 0.1-0.3 für Visualisierung, 0.5+ für lose Struktur.

n_components (Standard: 2)

Zweck: Bestimmt die Dimensionalität des eingebetteten Ausgaberaums.

Schlüsselfunktion: Im Gegensatz zu t-SNE skaliert UMAP gut in der Einbettungsdimension und ermöglicht die Nutzung über die Visualisierung hinaus.

Häufige Verwendungen:

• 2-3 Dimensionen: Visualisierung
• 5-10 Dimensionen: Vorverarbeitung für das Clustering (bewahrt Dichte besser als 2D)
• 10-50 Dimensionen: Feature Engineering für nachgelagerte ML-Modelle

Empfehlung: Verwenden Sie 2 für Visualisierung, 5-10 für Clustering, höher für ML-Pipelines.

metric (Standard: 'euclidean')

Zweck: Gibt an, wie der Abstand zwischen Eingabedatenpunkten berechnet wird.

Unterstützte Metriken:

• Minkowski-Varianten: euclidean, manhattan, chebyshev
• Räumliche Metriken: canberra, braycurtis, haversine
• Korrelationsmetriken: cosine, correlation (gut für Text-/Dokumenteinbettungen)
• Binäre Datenmetriken: hamming, jaccard, dice, russellrao, kulsinski, rogerstanimoto, sokalmichener, sokalsneath, yule
• Benutzerdefinierte Metriken: Benutzerdefinierte Distanzfunktionen über Numba

Empfehlung: Verwenden Sie euclidean für numerische Daten, cosine für Text-/Dokumentvektoren, hamming für binäre Daten.

Beispiel zur Parametereinstellung

# Für Visualisierung mit Betonung auf lokale Struktur
umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='euclidean')

# Für Cluster-Vorverarbeitung
umap.UMAP(n_neighbors=30, min_dist=0.0, n_components=10, metric='euclidean')

# Für Dokumenteinbettungen
umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='cosine')

# Zum Bewahren der globalen Struktur
umap.UMAP(n_neighbors=100, min_dist=0.5, n_components=2, metric='euclidean')

Überwachte und halbüberwachte Dimensionsreduktion

UMAP unterstützt die Einbeziehung von Label-Informationen zur Steuerung des Einbettungsprozesses, was Klassentrennung unter Bewahrung der internen Struktur ermöglicht.

Überwachtes UMAP

Übergeben Sie Ziel-Labels über den Parameter y beim Anpassen:

# Überwachte Dimensionsreduktion
embedding = umap.UMAP().fit_transform(data, y=labels)

Wichtige Vorteile:

• Erzielt sauber getrennte Klassen
• Bewahrt die interne Struktur innerhalb jeder Klasse
• Behält globale Beziehungen zwischen Klassen bei

Halbüberwachtes UMAP

Für partielle Labels markieren Sie nicht gekennzeichnete Punkte mit -1 gemäß der scikit-learn Konvention:

# Halbüberwachte Labels erstellen
semi_labels = labels.copy()
semi_labels[unlabeled_indices] = -1

# Mit partiellen Labels anpassen
embedding = umap.UMAP().fit_transform(data, y=semi_labels)

Wann verwenden: Wenn das Labeln teuer ist oder Sie mehr Daten als Labels haben.

UMAP für Clustering

UMAP dient als effektive Vorverarbeitung für dichtebasierte Cluster-Algorithmen wie HDBSCAN und überwindet den Fluch der Dimensionalität.

Best Practices für Clustering

Schlüsselprinzip: Konfigurieren Sie UMAP für Clustering anders als für die Visualisierung.

Empfohlene Parameter:

• n_neighbors: Erhöhen Sie auf ~30 (Standardwert 15 ist zu lokal und kann künstliche feinkörnige Cluster erzeugen)
• min_dist: Setzen Sie auf 0.0 (packt Punkte dicht in Clustern für klarere Grenzen)
• n_components: Verwenden Sie 5-10 Dimensionen (behält die Leistung bei, während die Dichtebewahrung im Vergleich zu 2D verbessert wird)

Cluster-Workflow

Installieren Sie HDBSCAN separat für dichtebasiertes Clustering:

uv pip install hdbscan

import umap
import hdbscan
from sklearn.preprocessing import StandardScaler

# 1. Daten vorverarbeiten
scaled_data = StandardScaler().fit_transform(data)

# 2. UMAP mit clusteroptimierten Parametern
reducer = umap.UMAP(
    n_neighbors=30,
    min_dist=0.0,
    n_components=10,  # Höher als 2 für bessere Dichtebewahrung
    metric='euclidean',
    random_state=42
)
embedding = reducer.fit_transform(scaled_data)

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

# 4. Evaluieren
from sklearn.metrics import adjusted_rand_score
score = adjusted_rand_score(true_labels, labels)
print(f"Adjusted Rand Score: {score:.3f}")
print(f"Anzahl der Cluster: {len(set(labels)) - (1 if -1 in labels else 0)}")
print(f"Rauschpunkte: {sum(labels == -1)}")

Visualisierung nach dem Clustering

# 2D-Einbettung für die Visualisierung erstellen (getrennt vom 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)

# Mit Cluster-Labels plotten
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 mit HDBSCAN Clustern')
plt.show()

Wichtiger Hinweis: UMAP bewahrt die Dichte nicht vollständig und kann künstliche Clustergrenzen erzeugen. Überprüfen und erforschen Sie die resultierenden Cluster immer.

Transformieren neuer Daten

UMAP ermöglicht die Vorverarbeitung neuer Daten über die Methode transform(), die es trainierten Modellen erlaubt, unsichtbare Daten in den gelernten Einbettungsraum zu projizieren.

Grundlegende Transform-Verwendung

# Auf Trainingsdaten trainieren
trans = umap.UMAP(n_neighbors=15, random_state=42).fit(X_train)

# Testdaten transformieren
test_embedding = trans.transform(X_test)

Integration mit Machine-Learning-Pipelines

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

# Daten aufteilen
X_train, X_test, y_train, y_test = train_test_split(data, labels, test_size=0.2)

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

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

# Klassifikator auf Einbettungen trainieren
clf = SVC()
clf.fit(X_train_embedded, y_train)
accuracy = clf.score(X_test_embedded, y_test)
print(f"Testgenauigkeit: {accuracy:.3f}")

Wichtige Überlegungen

Datenkonsistenz: Die Transform-Methode setzt voraus, dass die Gesamtverteilung im höherdimensionalen Raum zwischen Trainings- und Testdaten konsistent ist. Wenn diese Annahme nicht zutrifft, ziehen Sie die Verwendung von Parametrischem UMAP in Betracht.

Leistung: Transform-Operationen sind effizient (typischerweise <1 Sekunde), obwohl anfängliche Aufrufe aufgrund der Numba-JIT-Kompilierung langsamer sein können.

Scikit-learn-Kompatibilität: UMAP folgt den standardmäßigen sklearn-Konventionen und funktioniert in Pipelines. Neuere 0.5.x-Versionen haben auch die Unterstützung für Merkmalsnamen und die Kompatibilität mit aktuellen scikit-learn-Validierungs-APIs verbessert:

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

Erweiterte Funktionen

Parametrisches UMAP

Parametrisches UMAP ersetzt die direkte Einbettungsoptimierung durch eine gelernte neuronale Netzwerkzuordnungsfunktion.

Wesentliche Unterschiede zum Standard-UMAP:

• Verwendet TensorFlow/Keras zum Trainieren von Encoder-Netzwerken
• Ermöglicht effiziente Transformation neuer Daten
• Unterstützt Rekonstruktion über Decoder-Netzwerke (inverse Transformation)
• Ermöglicht benutzerdefinierte Architekturen (CNNs für Bilder, RNNs für Sequenzen)

Installation:

uv pip install "umap-learn[parametric-umap]==0.5.12"
# Installiert das TensorFlow-gestützte Parametrische UMAP-Extra.

Grundlegende Verwendung:

from umap.parametric_umap import ParametricUMAP

# Standardarchitektur (3-schichtiges 100-Neuron-fully-connected Netzwerk)
embedder = ParametricUMAP()
embedding = embedder.fit_transform(data)

# Neue Daten effizient transformieren
new_embedding = embedder.transform(new_data)

Benutzerdefinierte Architektur:

import tensorflow as tf

# Benutzerdefinierten Encoder definieren
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)  # Ausgabedimension
])

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

Persistenz: Speichern Sie Parametrisches UMAP mit seinen integrierten Keras-bewussten Methoden anstelle von einfachem Pickle:

embedder.save("parametric_umap_model", exclude_raw_data=True)

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

Aktuelle 0.5.12-Fixes beinhalten Verbesserungen der Stabilität beim Neutrainieren von Parametrischem UMAP und Korrekturen der Metrik-Gradienten. Bevorzugen Sie daher die fixierte aktuelle Version für neuronale Netzwerk-Workflows.

Wann Parametrisches UMAP verwenden:

• Sie benötigen eine effiziente Transformation neuer Daten nach dem Training
• Sie benötigen Rekonstruktionsfähigkeiten (inverse Transformationen)
• Sie möchten UMAP mit Autoencodern kombinieren
• Sie arbeiten mit komplexen Datentypen (Bilder, Sequenzen), die von spezialisierten Architekturen profitieren

Inverse Transformationen

Inverse Transformationen ermöglichen die Rekonstruktion hochdimensionaler Daten aus niedrigdimensionalen Einbettungen.

Grundlegende Verwendung:

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

# Hochdimensionale Daten aus Einbettungskoordinaten rekonstruieren
reconstructed = reducer.inverse_transform(embedding)

Wichtige Einschränkungen:

• Rechenintensive Operation
• Funktioniert außerhalb der konvexen Hülle der Einbettung schlecht
• Genauigkeit nimmt in Bereichen mit Lücken zwischen Clustern ab

Beispiel: Einbettungsraum erkunden:

import numpy as np

# Gitter von Punkten im Einbettungsraum erstellen
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()]

# Stichproben aus dem Gitter rekonstruieren
reconstructed_samples = reducer.inverse_transform(grid_points)

AlignedUMAP

Für zeitliche oder verwandte Datensätze, die ein gemeinsames Koordinatensystem benötigen (z.B. Zeitreihenexperimente, Batches), verwenden Sie umap.AlignedUMAP().fit(datasets, relations=relations), wobei relations Stichprobenindizes zwischen aufeinanderfolgenden Datensätzen abbildet und für eine sinnvolle Ausrichtung erforderlich ist. Parameter, Methoden und ein ausführliches Beispiel finden Sie in references/api_reference.md unter "AlignedUMAP Class" und "Usage Examples".

Reproduzierbarkeit

Um reproduzierbare Ergebnisse zu gewährleisten, setzen Sie immer den Parameter random_state:

reduc

…

[gekürzt für die Übersetzung]