umap-learn

Que fait 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 non linéaire générale. Appliquez cette compétence pour des plongements rapides et évolutifs qui préservent la structure locale et globale, l'apprentissage supervisé et le prétraitement pour le clustering.

Démarrage rapide

Installation

Version stable actuelle : umap-learn 0.5.12 (publiée en avril 2026). Nécessite Python 3.9+ et dépend de scikit-learn>=1.6, numba, pynndescent, numpy, et scipy. Verrouillez une version vérifiée :

uv pip install umap-learn==0.5.12

Utilisation de base

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

import umap
from sklearn.preprocessing import StandardScaler

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

# Méthode 1 : Étape unique (ajustement et transformation)
embedding = umap.UMAP().fit_transform(scaled_data)

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

Exigence de prétraitement : Adaptez le prétraitement à la métrique. Pour les métriques numériques de type euclidien, mettez les caractéristiques à l'échelle avant l'ajustement afin que les colonnes à forte variance ne dominent pas. Pour les workflows cosinus, binaires, de distance précalculée ou à caractéristiques mixtes, choisissez un prétraitement adapté à la métrique au lieu de standardiser aveuglément chaque colonne.

Workflow typique

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

# 1. Prétraitement des données
scaler = StandardScaler()
scaled_data = scaler.fit_transform(raw_data)

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

Guide de réglage des paramètres

UMAP dispose de quatre paramètres principaux qui contrôlent le comportement du plongement. Comprendre ceux-ci est crucial pour une utilisation efficace.

n_neighbors (par défaut : 15)

Objectif : Équilibre la structure locale par rapport à la structure globale dans le plongement.

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

Effets par valeur :

• Valeurs faibles (2-5) : Met l'accent sur 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) : Priorise la structure topologique large au détriment des détails fins

Recommandation : Commencez par 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 dimension.

Fonctionnement : Définit la distance minimale que les points sont autorisés à avoir dans la représentation de sortie.

Effets par valeur :

• Valeurs faibles (0.0-0.1) : Crée des plongements agglomérés utiles pour le clustering ; révèle des 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 intégré.

Caractéristique clé : Contrairement à t-SNE, UMAP se comporte bien dans la dimension d'intégration, permettant une utilisation au-delà de la visualisation.

Utilisations courantes :

• 2-3 dimensions : Visualisation
• 5-10 dimensions : Prétraitement pour le clustering (préserve mieux la densité que la 2D)
• 10-50 dimensions : Ingénierie des caractéristiques pour les modèles ML en aval

Recommandation : Utilisez 2 pour la visualisation, 5-10 pour le clustering, plus 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 prises en charge :

• Variantes de Minkowski : euclidean, manhattan, chebyshev
• Métriques spatiales : canberra, braycurtis, haversine
• Métriques de corrélation : cosine, correlation (bonnes pour les plongements de texte/document)
• Métriques de 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 de texte/document, hamming pour les données binaires.

Exemple de réglage des 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 plongements 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 prend en charge l'intégration d'informations d'étiquettes pour guider le processus de plongement, permettant la séparation des classes tout en préservant la structure interne.

UMAP supervisé

Passez les étiquettes 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 :

• Obtient des classes bien séparées
• Préserve la structure interne au sein de chaque classe
• Maintient les relations globales entre les classes

UMAP semi-supervisé

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

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

# Ajuster avec des étiquettes partielles
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 d'étiquettes disponibles.

UMAP pour le clustering

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

Meilleures pratiques pour le clustering

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

Paramètres recommandés :

• n_neighbors : Augmentez à environ 30 (la valeur par défaut 15 est trop locale et peut créer des clusters fins artificiels)
• min_dist : Réglez à 0.0 (emballez 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 à la 2D)

Workflow de clustering

Installez HDBSCAN séparément pour le clustering basé sur la densité :

uv pip install hdbscan

import umap
import hdbscan
from sklearn.preprocessing import StandardScaler

# 1. Prétraitement des 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"Score de Rand ajusté : {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 plongement 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 étiquettes 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 les clusters HDBSCAN')
plt.show()

Mise en garde importante : UMAP ne préserve pas complètement la densité et peut créer des divisions artificielles entre les clusters. Validez et explorez toujours les clusters résultants.

Transformation de nouvelles données

UMAP permet le prétraitement de nouvelles données via sa méthode transform(), permettant à des modèles entraînés de projeter des données inédites dans l'espace de plongement appris.

Utilisation de base 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 de machine learning

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 un classifieur sur les plongements
clf = SVC()
clf.fit(X_train_embedded, y_train)
accuracy = clf.score(X_test_embedded, y_test)
print(f"Précision du test : {accuracy:.3f}")

Considérations importantes

Cohérence des données : La méthode transform suppose que la distribution globale dans l'espace de haute dimension 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.

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

Compatibilité scikit-learn : UMAP suit les conventions sklearn standard et fonctionne dans les pipelines. Les versions récentes 0.5.x ont également amélioré la prise en charge des noms de caractéristiques et la compatibilité avec les API de validation scikit-learn actuelles :

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

Fonctionnalités avancées

UMAP paramétrique

UMAP paramétrique remplace l'optimisation directe du plongement 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 encodeurs
• Permet une transformation efficace des nouvelles données
• Prend en charge la reconstruction via des réseaux décodeurs (transformation inverse)
• Permet des architectures personnalisées (CNN pour les images, RNN pour les séquences)

Installation :

uv pip install "umap-learn[parametric-umap]==0.5.12"
# Installe l'extension UMAP paramétrique basée sur TensorFlow.

Utilisation de base :

from umap.parametric_umap import ParametricUMAP

# Architecture par défaut (réseau entièrement connecté à 3 couches de 100 neurones)
embedder = ParametricUMAP()
embedding = embedder.fit_transform(data)

# Transformer efficacement de nouvelles données
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(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)

Persistance : Sauvegardez Parametric UMAP avec ses méthodes intégrées compatibles Keras plutôt qu'avec pickle simple :

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

from umap.parametric_umap import load_ParametricUMAP
loaded = load_ParametricUMAP("model_umap_parametrique")
new_embedding = loaded.transform(new_data)

Les correctifs récents de la version 0.5.12 incluent des améliorations de la stabilité du réentraînement de Parametric UMAP et des corrections de gradient de métrique. Privilégiez donc la version actuelle verrouillée pour les workflows de réseaux de neurones.

Quand utiliser UMAP paramétrique :

• Besoin d'une transformation efficace des nouvelles données après l'entraînement
• Nécessité de capacités de reconstruction (transformations inverses)
• Souhaitez combiner UMAP avec des autoencodeurs
• Travaillez avec des types de données complexes (images, séquences) bénéficiant d'architectures spécialisées

Transformations inverses

Les transformations inverses permettent la reconstruction de données de haute dimension à partir de plongements de faible dimension.

Utilisation de base :

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

# Reconstruire les données de haute dimension à partir des coordonnées du plongement
reconstructed = reducer.inverse_transform(embedding)

Limitations importantes :

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

Exemple : Exploration de l'espace de plongement :

import numpy as np

# Créer une grille de points dans l'espace de plongement
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 des échantillons à partir de la grille
reconstructed_samples = reducer.inverse_transform(grid_points)

AlignedUMAP

Pour des jeux de données temporels ou connexes nécessitant un système de coordonnées partagé (expériences de séries temporelles, lots), utilisez umap.AlignedUMAP().fit(datasets, relations=relations), où relations mappe les indices d'échantillons entre des jeux de données consécutifs et est requis pour un alignement significatif. Les paramètres, les méthodes et un exemple concret se trouvent dans references/api_reference.md sous "Classe AlignedUMAP" et "Exemples d'utilisation".

Reproductibilité

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

reduc

…

[truncé pour la traduction]