mojolearn.manifold#

Manifold learning: spectral embedding (Laplacian eigenmaps) and UMAP.

Functions

spectral_embedding(A, *[, n_components, ...])

Spectral embedding of a dataset or affinity matrix, as a function.

Classes

SpectralEmbedding([n_components, affinity, ...])

Spectral embedding (Laplacian eigenmaps) for nonlinear dimensionality reduction.

UMAP([n_neighbors, n_components, min_dist, ...])

Uniform Manifold Approximation and Projection (UMAP) embedding.
class mojolearn.manifold.SpectralEmbedding(n_components=2, *, affinity='nearest_neighbors', random_state=None, n_neighbors=None, gamma=None, eigen_solver=None, eigen_tol=None, n_jobs=None, verbose=False)[source]#

Bases: object

Spectral embedding (Laplacian eigenmaps) for nonlinear dimensionality reduction.

Builds an affinity graph, forms the normalized graph Laplacian and returns its smallest nontrivial eigenvectors, computed with a thick-restart Lanczos solver. The first (trivial) eigenvector is dropped. Follows cuML’s manifold.SpectralEmbedding. There is no transform: the embedding covers the fitted rows only, as in scikit-learn.

Parameters:

  • n_components (int, default 2) – Dimension of the embedding; at least 1, and the eigenpairs needed must number fewer than n_samples.

  • affinity (str, default “nearest_neighbors”) – "nearest_neighbors" (symmetrized k-NN connectivity of X), "precomputed" (X is a square affinity matrix, dense or sparse), "rbf" (exp(-gamma * ||x_i - x_j||**2)) or "precomputed_nearest_neighbors" (X is a distance matrix or sparse distance graph; the n_neighbors nearest per row, symmetrized as 0.5 * (C + C.T)). A callable or any other name raises ValueError.

  • random_state (int or None, default None) – Seed in [0, 2**32). None means seed 0, so results are deterministic (unlike scikit-learn, where None draws a fresh seed).

  • n_neighbors (int or None, default None) – Neighbors per row; None uses max(n_samples // 10, 1).

  • gamma (float or None, default None) – Positive RBF coefficient, used only with affinity="rbf"; None means 1 / n_features (scikit-learn’s rule). Setting it with another affinity raises NotImplementedError.

  • eigen_solver (None) – Only None is accepted; any other value raises NotImplementedError.

  • eigen_tol (float, “auto” or None, default None) – Eigensolver tolerance. "auto" and None use 1e-5; otherwise a positive finite float.

  • n_jobs (int or None, default None) – Accepted for compatibility; it does not change the result.

  • verbose (bool, default False) – Accepted for compatibility; nothing is printed.

Variables:

  • embedding_ (Array of shape (n_samples, n_components), float32) – The embedding of the training rows.

  • affinity_matrix_ (array) – The dense affinity matrix built for "rbf" and "precomputed_nearest_neighbors".

  • n_neighbors_ (int) – Number of neighbors used, for the nearest-neighbor affinities.

  • gamma_ (float) – The RBF coefficient used, for affinity="rbf".

  • n_features_in_ (int) – Number of features of X, for "nearest_neighbors" and "rbf".

Notes

A precomputed affinity must be nonnegative and finite and must not repeat a (row, col) entry; its diagonal is ignored.

Examples

>>> import numpy as np, mojolearn
>>> X = np.random.default_rng(0).random((1000, 8), dtype=np.float32)
>>> Y = mojolearn.SpectralEmbedding(n_components=2).fit_transform(X)
fit(X, y=None)[source]#

Compute the embedding of X.

Parameters:

  • X (array-like of shape (n_samples, n_features) or (n_samples, n_samples)) – Training data, or a square affinity ("precomputed") or distance ("precomputed_nearest_neighbors") matrix, dense or sparse. Values must be finite.

  • y (ignored)

Returns:

self (SpectralEmbedding) – The fitted estimator.

Raises:

ValueError – If X is not finite, a precomputed matrix is not square or has a negative or repeated entry, or n_components needs as many eigenpairs as there are samples.

fit_transform(X, y=None)[source]#

Fit to X and return the embedding.

Parameters:

  • X (array-like) – As in fit.

  • y (ignored)

Returns:

embedding (Array of shape (n_samples, n_components), float32) – Same as embedding_.

class mojolearn.manifold.UMAP(n_neighbors=15, n_components=2, *, min_dist=0.1, spread=1.0, n_epochs=None, random_state=0, set_op_mix_ratio=1.0, local_connectivity=1.0, metric='euclidean', init='spectral', learning_rate=1.0, repulsion_strength=1.0, negative_sample_rate=5, a=None, b=None, metric_kwds=None, target_n_neighbors=-1, target_metric='categorical', target_weight=0.5, densmap=False, output_metric='euclidean')[source]#

Bases: NumericModeMixin

Uniform Manifold Approximation and Projection (UMAP) embedding.

Builds a fuzzy nearest-neighbor graph of the training rows with exact neighbor search, then optimizes a low-dimensional layout. Input is a dense array converted to C-order float32. The neighbor graph is stored in CSR form, so memory grows linearly with n_samples for a bounded n_neighbors; the exact neighbor search still compares every pair of rows. Parameters follow umap-learn; defaults that differ are n_epochs=None (200 epochs) and random_state=0.

At least 2 * n_components + 4 samples are needed for the spectral initialization.

Parameters:

  • n_neighbors (int, default 15) – Size of the local neighborhood; at least 2 and at most n_samples.

  • n_components (int, default 2) – Dimension of the embedding, 1 to 32.

  • min_dist (float, default 0.1) – Minimum distance between embedded points; 0 <= min_dist <= spread.

  • spread (float, default 1.0) – Scale of the embedded points; must be positive.

  • n_epochs (int or None, default None) – Number of optimization epochs; None uses 200.

  • random_state (int, default 0) – Seed for the optimizer and random initialization; a nonnegative integer.

  • set_op_mix_ratio (float, default 1.0) – Mix between fuzzy union (1.0) and fuzzy intersection (0.0), in [0, 1].

  • local_connectivity (float, default 1.0) – Number of nearest neighbors assumed locally connected; any value >= 0 (umap-learn’s interpolation for fractional values).

  • metric (str, default “euclidean”) – Input distance: "euclidean" ("l2"), "sqeuclidean", "cosine", "manhattan" ("l1", "cityblock", "taxicab"), "chebyshev" ("linf", "linfinity", "infinity") or "minkowski". A callable or any other name raises ValueError.

  • init ({“spectral”, “random”, “pca”} or array, default “spectral”) – Initial layout. "random" draws uniform(-10, 10); "pca" is umap-learn’s scaled PCA plus N(0, 1e-4) noise; an array must have shape (n_samples, n_components) and be finite.

  • learning_rate (float, default 1.0) – Initial learning rate; must be positive.

  • repulsion_strength (float, default 1.0) – Weight of negative samples; must be nonnegative.

  • negative_sample_rate (int, default 5) – Negative samples per positive sample.

  • a, b (float or None, default None) – Curve parameters of the low-dimensional similarity. Give both or neither; when None they are derived from min_dist and spread.

  • metric_kwds (dict or None, default None) – Extra metric arguments. Only {"p": p} for "minkowski" (p > 0, default 2.0); any other key raises ValueError.

  • target_n_neighbors (int, default -1) – Neighbors used for the target graph in supervised fits; -1 uses n_neighbors, otherwise at least 2.

  • target_metric ({“categorical”, “l2”, “euclidean”}, default “categorical”) – Distance on y for supervised fits. With "categorical", the label -1 means unknown. Other values raise NotImplementedError.

  • target_weight (float, default 0.5) – Weight of the target in [0, 1]; 0 ignores the data, 1 ignores y.

  • densmap (bool, default False) – densMAP is not supported; True raises NotImplementedError.

  • output_metric (str, default “euclidean”) – Only "euclidean" (or "l2") is supported; any other value raises NotImplementedError.

Variables:

  • embedding_ (Array of shape (n_samples, n_components)) – The float32 embedding of the training data.

  • n_features_in_ (int) – Number of features seen during fit.

  • input_copied_ (bool) – Whether X had to be copied to C-order float32.

Notes

transform keeps private copies of the training data and embedding, adding O(n_samples * (n_features + n_components)) memory. It finds each new row’s neighbors among the training rows, initializes it from their weighted embedding and refines it against the frozen training embedding for 100 epochs (max(1, n_epochs // 3) when n_epochs is set) at learning_rate / 4. The result for a row does not depend on the other rows in the call.

Examples

>>> import numpy as np, mojolearn
>>> X = np.random.default_rng(0).random((1000, 8), dtype=np.float32)
>>> model = mojolearn.UMAP(n_neighbors=15, n_components=2).fit(X)
>>> model.embedding_.shape
(1000, 2)
>>> Y = model.transform(X[:10])
fit(X, y=None)[source]#

Fit the embedding to X.

Parameters:

  • X (array-like of shape (n_samples, n_features)) – Training data; converted to C-order float32 and must be finite.

  • y (array-like of shape (n_samples,) or (n_samples, n_targets), optional) – Target for supervised UMAP. Categorical labels (one per row, -1 for unknown) or, with target_metric="l2", finite continuous values.

Returns:

self (UMAP) – The fitted estimator.

Raises:

  • ValueError – If X is not finite, n_neighbors exceeds n_samples, there are too few samples for spectral initialization, or a parameter is out of range.

  • NotImplementedError – For densmap=True, a non-euclidean output_metric or an unsupported target_metric.

fit_transform(X, y=None)[source]#

Fit to X and return the training embedding.

Parameters:

  • X (array-like of shape (n_samples, n_features)) – Training data.

  • y (array-like, optional) – Target for supervised UMAP (see fit).

Returns:

embedding (Array of shape (n_samples, n_components)) – The float32 embedding, the same object as embedding_.

transform(X)[source]#

Embed new rows in the fitted coordinate system without refitting.

Each row is embedded independently: a batch of rows returns the same values as embedding the rows one at a time. Passing the exact training data returns a copy of the training embedding. Later edits of embedding_ or of the original X do not change the model.

Parameters:

X (array-like of shape (n_queries, n_features)) – New rows; must be finite and have the training feature count.

Returns:

embedding (Array of shape (n_queries, n_components)) – The float32 embedding of the new rows.

Raises:

ValueError – If the model is not fitted, the parameters or numeric mode changed since fit (refit first), the feature count differs, or X is not finite.

save(path)[source]#

Save the fitted model to path as an .npz file.

The file holds the training rows, the embedding, the parameters and the numeric mode. A model loaded with UMAP.load (or mojolearn.host_model) can transform new rows, including on a CPU-only install, but cannot refit.

Parameters:

path (str or path-like) – Destination file.

Raises:

ValueError – If the model is not fitted.

classmethod load(path)[source]#

Load a model written by save.

The loaded model transforms new rows against the saved training rows and embedding; it does not refit.

Parameters:

path (str or path-like) – File written by UMAP.save.

Returns:

model (UMAP) – The restored model, with embedding_, n_features_in_ and input_copied_ set.

Raises:

ValueError – If the file is not a UMAP model or its contents are inconsistent.

mojolearn.manifold.spectral_embedding(A, *, n_components=8, affinity='nearest_neighbors', random_state=None, n_neighbors=None, norm_laplacian=True, drop_first=True)[source]#

Spectral embedding of a dataset or affinity matrix, as a function.

Equivalent to SpectralEmbedding(...).fit_transform(A), plus the two switches the class fixes. Follows cuML’s manifold.spectral_embedding; note that n_components defaults to 8 here, as in cuML.

Parameters:

  • A (array-like) – Data or matrix, interpreted according to affinity (see SpectralEmbedding).

  • n_components (int, default 8) – Dimension of the embedding.

  • affinity (str, default “nearest_neighbors”) – Affinity, as in SpectralEmbedding.

  • random_state (int or None, default None) – Seed; None means seed 0.

  • n_neighbors (int or None, default None) – Neighbors per row; None uses max(n_samples // 10, 1).

  • norm_laplacian (bool, default True) – Use the symmetric normalized graph Laplacian.

  • drop_first (bool, default True) – Drop the first (trivial) eigenvector.

Returns:

embedding (Array of shape (n_samples, n_components), float32) – The embedding.

Raises:

TypeError – If norm_laplacian or drop_first is not a bool.