UMAP-Learn

Vue d'ensemble

UMAP (Uniform Manifold Approximation and Projection) est une technique de réduction de dimensionnalité pour la visualisation et la réduction de dimensionnalité non-linéaire générale. Utilisez cette skill pour des embeddings rapides et évolutifs qui préservent la structure locale et globale, l'apprentissage supervisé et le prétraitement du clustering.

Démarrage rapide

Installation

uv pip install umap-learn

Utilisation basique

UMAP suit les conventions de scikit-learn et peut être utilisé comme remplaçant direct de t-SNE ou PCA.

import umap
from sklearn.preprocessing import StandardScaler

# Préparer les données (la standardisation est essentielle)
scaled_data = StandardScaler().fit_transform(data)

# Méthode 1 : Une seule étape (fit et transform)
embedding = umap.UMAP().fit_transform(scaled_data)

# Méthode 2 : Étapes séparées (pour réutiliser le modèle entraîné)
reducer = umap.UMAP(random_state=42)
reducer.fit(scaled_data)
embedding = reducer.embedding_  # Accès à l'embedding entraîné

Exigence de prétraitement critique : Standardisez toujours les features à des échelles comparables avant d'appliquer UMAP pour assurer une pondération égale entre les dimensions.

Workflow typique

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

# 1. Prétraiter les données
scaler = StandardScaler()
scaled_data = scaler.fit_transform(raw_data)

# 2. Créer et entraîner 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. Visualiser
plt.scatter(embedding[:, 0], embedding[:, 1], c=labels, cmap='Spectral', s=5)
plt.colorbar()
plt.title('UMAP Embedding')
plt.show()

Guide d'ajustement des paramètres

UMAP a quatre paramètres principaux qui contrôlent le comportement de l'embedding. Comprendre ces paramètres est crucial pour une utilisation efficace.

n_neighbors (par défaut : 15)

Objectif : Équilibre la structure locale par rapport à la structure globale de l'embedding.

Fonctionnement : Contrôle la taille du voisinage local qu'UMAP examine lors de l'apprentissage de la structure manifold.

Effets selon la valeur :

Valeurs basses (2-5) : Accentue les détails locaux fins mais peut fragmenter les données en composants déconnectés
Valeurs moyennes (15-20) : Vue équilibrée de la structure locale et des relations globales (point de départ recommandé)
Valeurs élevées (50-200) : Privilégie la structure topologique large au détriment des détails fins

Recommandation : Commencez avec 15 et ajustez selon les résultats. Augmentez pour plus de structure globale, diminuez pour plus de détails locaux.

min_dist (par défaut : 0,1)

Objectif : Contrôle la proximité avec laquelle les points se regroupent dans l'espace de faible dimensionnalité.

Fonctionnement : Définit la distance minimale autorisée entre les points dans la représentation de sortie.

Effets selon la valeur :

Valeurs basses (0,0-0,1) : Crée des embeddings agglomérés utiles pour le clustering ; révèle les détails topologiques fins
Valeurs élevées (0,5-0,99) : Empêche l'emballage serré ; met l'accent sur la préservation topologique large plutôt que sur la structure locale

Recommandation : Utilisez 0,0 pour les applications de clustering, 0,1-0,3 pour la visualisation, 0,5+ pour une structure lâche.

n_components (par défaut : 2)

Objectif : Détermine la dimensionnalité de l'espace de sortie de l'embedding.

Caractéristique clé : Contrairement à t-SNE, UMAP se met à l'échelle bien selon la dimension d'embedding, permettant une utilisation au-delà de la visualisation.

Utilisations courantes :

2-3 dimensions : Visualisation
5-10 dimensions : Prétraitement de clustering (préserve mieux la densité qu'en 2D)
10-50 dimensions : Ingénierie de features pour les modèles ML en aval

Recommandation : Utilisez 2 pour la visualisation, 5-10 pour le clustering, plus élevé pour les pipelines ML.

metric (par défaut : 'euclidean')

Objectif : Spécifie comment la distance est calculée entre les points de données d'entrée.

Métriques supportées :

Variantes Minkowski : euclidean, manhattan, chebyshev
Métriques spatiales : canberra, braycurtis, haversine
Métriques de corrélation : cosine, correlation (bonnes pour les embeddings texte/document)
Métriques pour données binaires : hamming, jaccard, dice, russellrao, kulsinski, rogerstanimoto, sokalmichener, sokalsneath, yule
Métriques personnalisées : Fonctions de distance définies par l'utilisateur via Numba

Recommandation : Utilisez euclidean pour les données numériques, cosine pour les vecteurs texte/document, hamming pour les données binaires.

Exemple d'ajustement de paramètres

# Pour la visualisation avec accent sur la structure locale
umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='euclidean')

# Pour le prétraitement de clustering
umap.UMAP(n_neighbors=30, min_dist=0.0, n_components=10, metric='euclidean')

# Pour les embeddings de documents
umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='cosine')

# Pour préserver la structure globale
umap.UMAP(n_neighbors=100, min_dist=0.5, n_components=2, metric='euclidean')

Réduction de dimensionnalité supervisée et semi-supervisée

UMAP supporte l'incorporation d'informations de labels pour guider le processus d'embedding, permettant la séparation des classes tout en préservant la structure interne.

UMAP supervisé

Passez les labels cibles via le paramètre y lors de l'ajustement :

# Réduction de dimensionnalité supervisée
embedding = umap.UMAP().fit_transform(data, y=labels)

Avantages clés :

Réalise une séparation nette des classes
Préserve la structure interne de chaque classe
Maintient les relations globales entre classes

Quand l'utiliser : Lorsque vous avez des données étiquetées et voulez séparer les classes connues tout en gardant des embeddings de points significatifs.

UMAP semi-supervisé

Pour les labels partiels, marquez les points non étiquetés avec -1 en suivant la convention scikit-learn :

# Créer des labels semi-supervisés
semi_labels = labels.copy()
semi_labels[unlabeled_indices] = -1

# Ajuster avec des labels partiels
embedding = umap.UMAP().fit_transform(data, y=semi_labels)

Quand l'utiliser : Lorsque l'étiquetage est coûteux ou que vous avez plus de données que de labels disponibles.

Apprentissage de métrique avec UMAP

Entraînez un embedding supervisé sur des données étiquetées, puis appliquez-le à de nouvelles données non étiquetées :

# Entraîner sur des données étiquetées
mapper = umap.UMAP().fit(train_data, train_labels)

# Transformer les données de test non étiquetées
test_embedding = mapper.transform(test_data)

# Utiliser comme ingénierie de features pour un classificateur en aval
from sklearn.svm import SVC
clf = SVC().fit(mapper.embedding_, train_labels)
predictions = clf.predict(test_embedding)

Quand l'utiliser : Pour l'ingénierie de features supervisée dans les pipelines d'apprentissage automatique.

UMAP pour le clustering

UMAP sert de prétraitement efficace pour les algorithmes de clustering basés sur la densité comme HDBSCAN, surmontant la malédiction de la dimensionnalité.

Bonnes pratiques pour le clustering

Principe clé : Configurez UMAP différemment pour le clustering que pour la visualisation.

Paramètres recommandés :

n_neighbors : Augmentez à ~30 (la valeur par défaut 15 est trop locale et peut créer des clusters artificiellement fins)
min_dist : Définissez à 0,0 (tassez les points densément dans les clusters pour des limites plus nettes)
n_components : Utilisez 5-10 dimensions (maintient les performances tout en améliorant la préservation de la densité par rapport à 2D)

Workflow de clustering

import umap
import hdbscan
from sklearn.preprocessing import StandardScaler

# 1. Prétraiter les données
scaled_data = StandardScaler().fit_transform(data)

# 2. UMAP avec paramètres optimisés pour le clustering
reducer = umap.UMAP(
    n_neighbors=30,
    min_dist=0.0,
    n_components=10,  # Plus élevé que 2 pour une meilleure préservation de la densité
    metric='euclidean',
    random_state=42
)
embedding = reducer.fit_transform(scaled_data)

# 3. Appliquer le clustering HDBSCAN
clusterer = hdbscan.HDBSCAN(
    min_cluster_size=15,
    min_samples=5,
    metric='euclidean'
)
labels = clusterer.fit_predict(embedding)

# 4. Évaluer
from sklearn.metrics import adjusted_rand_score
score = adjusted_rand_score(true_labels, labels)
print(f"Adjusted Rand Score: {score:.3f}")
print(f"Nombre de clusters: {len(set(labels)) - (1 if -1 in labels else 0)}")
print(f"Points de bruit: {sum(labels == -1)}")

Visualisation après clustering

# Créer un embedding 2D pour la visualisation (séparé du 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)

# Tracer avec les labels de cluster
import matplotlib.pyplot as plt
plt.scatter(vis_embedding[:, 0], vis_embedding[:, 1], c=labels, cmap='Spectral', s=5)
plt.colorbar()
plt.title('Visualisation UMAP avec clusters HDBSCAN')
plt.show()

Avertissement important : UMAP ne préserve pas complètement la densité et peut créer des divisions de clusters artificielles. Toujours valider et explorer les clusters résultants.

Transformer de nouvelles données

UMAP permet le prétraitement de nouvelles données via sa méthode transform(), permettant aux modèles entraînés de projeter des données non vues dans l'espace d'embedding appris.

Utilisation basique de Transform

# Entraîner sur les données d'entraînement
trans = umap.UMAP(n_neighbors=15, random_state=42).fit(X_train)

# Transformer les données de test
test_embedding = trans.transform(X_test)

Intégration avec les pipelines d'apprentissage automatique

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

# Diviser les données
X_train, X_test, y_train, y_test = train_test_split(data, labels, test_size=0.2)

# Prétraiter
scaler = StandardScaler()
X_train_scaled = scaler.fit_transform(X_train)
X_test_scaled = scaler.transform(X_test)

# Entraîner 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)

# Entraîner le classificateur sur les embeddings
clf = SVC()
clf.fit(X_train_embedded, y_train)
accuracy = clf.score(X_test_embedded, y_test)
print(f"Précision sur le test: {accuracy:.3f}")

Considérations importantes

Cohérence des données : La méthode transform suppose que la distribution globale dans l'espace de dimensionnalité plus élevée est cohérente entre les données d'entraînement et de test. Lorsque cette hypothèse échoue, envisagez d'utiliser Parametric UMAP à la place.

Performance : Les opérations de transform sont efficaces (généralement <1 seconde), bien que les appels initiaux puissent être plus lents en raison de la compilation JIT Numba.

Compatibilité scikit-learn : UMAP suit les conventions standard sklearn et fonctionne parfaitement dans les pipelines :

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)

Fonctionnalités avancées

Parametric UMAP

Parametric UMAP remplace l'optimisation d'embedding direct par une fonction de mappage de réseau de neurones apprise.

Différences clés par rapport à UMAP standard :

Utilise TensorFlow/Keras pour entraîner des réseaux d'encodeurs
Permet une transformation efficace de nouvelles données
Supporte la reconstruction via des réseaux de décodeurs (inverse transform)
Permet des architectures personnalisées (CNN pour images, RNN pour séquences)

Installation :

uv pip install umap-learn[parametric_umap]
# Nécessite TensorFlow 2.x

Utilisation basique :

from umap.parametric_umap import ParametricUMAP

# Architecture par défaut (réseau complètement connecté 3 couches 100 neurones)
embedder = ParametricUMAP()
embedding = embedder.fit_transform(data)

# Transformer de nouvelles données efficacement
new_embedding = embedder.transform(new_data)

Architecture personnalisée :

import tensorflow as tf

# Définir un encodeur personnalisé
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)  # Dimension de sortie
])

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

Quand utiliser Parametric UMAP :

Besoin d'une transformation efficace de nouvelles données après entraînement
Nécessité de capacités de reconstruction (inverse transforms)
Souhait de combiner UMAP avec des autoencodeurs
Travail avec des types de données complexes (images, séquences) bénéficiant d'architectures spécialisées

Quand utiliser UMAP standard :

Besoin de simplicité et de prototypage rapide
L'ensemble de données est petit et l'efficacité computationnelle n'est pas critique
Pas besoin de transformations apprises pour les futures données

Inverse Transforms

Les inverse transforms permettent la reconstruction de données de dimensionnalité élevée à partir d'embeddings de faible dimensionnalité.

Utilisation basique :

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

# Reconstruire les données de dimensionnalité élevée à partir des coordonnées d'embedding
reconstructed = reducer.inverse_transform(embedding)

Limitations importantes :

Opération coûteuse en termes de calcul
Fonctionne mal en dehors de l'enveloppe convexe de l'embedding
La précision diminue dans les régions avec des lacunes entre les clusters

Cas d'utilisation :

Comprendre la structure des données intégrées
Visualiser les transitions fluides entre clusters
Explorer les interpolations entre des points de données
Générer des échantillons synthétiques dans l'espace d'embedding

Exemple : Explorer l'espace d'embedding :

import numpy as np

# Créer une grille de points dans l'espace d'embedding
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()]

# Reconstruire les échantillons à partir de la grille
reconstructed_samples = reducer.inverse_transform(grid_points)

AlignedUMAP

Pour analyser les ensembles de données temporels ou connexes (par exemple, expériences de séries chronologiques, données par batch) :

from umap import AlignedUMAP

# Liste d'ensembles de données connexes
datasets = [day1_data, day2_data, day3_data]

# Créer des embeddings alignés
mapper = AlignedUMAP().fit(datasets)
aligned_embeddings = mapper.embeddings_  # Liste d'embeddings

Quand l'utiliser : Comparer les embeddings entre des ensembles de données connexes tout en maintenant des systèmes de coordonnées cohérents.

Reproductibilité

Pour assurer des résultats reproductibles, définissez toujours le paramètre random_state :

reducer = umap.UMAP(random_state=42)

UMAP utilise l'optimisation stochastique, donc les résultats varieront légèrement entre les exécutions sans un état aléatoire fixe.

Problèmes courants et solutions

Problème : Composants déconnectés ou clusters fragmentés

Solution : Augmentez n_neighbors pour accentuer la structure plus globale

Problème : Clusters trop dispersés ou mal séparés

Solution : Diminuez min_dist pour permettre un emballage plus serré

Problème : Mauvais résultats de clustering

Solution : Utilisez des paramètres spécifiques au clustering (n_neighbors=30, min_dist=0.0, n_components=5-10)

Problème : Les résultats de transform diffèrent significativement de l'entraînement

Solution : Assurez-vous que la distribution des données de test correspond à l'entraînement, ou utilisez Parametric UMAP

Problème : Performance lente sur les grands ensembles de données

Solution : Définissez low_memory=True (par défaut), ou envisagez une réduction de dimensionnalité avec PCA d'abord

Problème : Tous les points regroupés en un seul cluster

Solution : Vérifiez le prétraitement des données (assurez une mise à l'échelle appropriée), augmentez min_dist

Ressources

references/

Contient la documentation API détaillée :

api_reference.md : Paramètres et méthodes complets de la classe UMAP

Chargez ces références lorsque vous avez besoin d'informations détaillées sur les paramètres ou d'une utilisation avancée des méthodes.