Uniform Manifold Approximation and Projection in R

Creating a projection

Let’s load the umap package and apply the UMAP transformation.

library(umap)
iris.umap <- umap(iris.data)

The output is an object and we can get a summary of its contents by printing it.

iris.umap

## umap embedding of 150 items in 2 dimensions
## object components: layout, data, knn, config

The main component of the object is ‘layout’, which holds a matrix with coordinates.

head(iris.umap$layout, 3)

##          [,1]     [,2]
## [1,] 13.87556 2.547236
## [2,] 15.33267 4.432621
## [3,] 14.73109 4.198838

These coordinates can be used to visualize the dataset. (The custom plot function, plot.iris, is available at the end of this vignette.)

plot.iris(iris.umap, iris.labels)

Projecting new data

Once we have a ‘umap’ object describing an embedding of a dataset into a low-dimensional layout, we can project other data onto the same manifold.

To demonstrate this, we need a second dataset with the same data features as the training data. Let’s create such data by adding some noise to the original.

iris.wnoise <- iris.data + matrix(rnorm(150*40, 0, 0.1), ncol=4)
colnames(iris.wnoise) <- colnames(iris.data)
head(iris.wnoise, 3)

##   Sepal.Length Sepal.Width Petal.Length Petal.Width
## 1     5.183373    3.525821     1.515123   0.3285499
## 2     4.872395    3.096451     1.467537   0.2094982
## 3     4.664500    3.150872     1.421417   0.2190057

We can now arrange these perturbed observations onto the same layout as before. Following R’s design pattern for fitted models, this is performed via predict.

iris.wnoise.umap <- predict(iris.umap, iris.wnoise)
head(iris.wnoise.umap, 3)

##       [,1]     [,2]
## 1 13.55093 2.217609
## 2 15.59680 3.918772
## 3 14.66652 4.984972

The output is a matrix with coordinates. We can visualize these points alongside the original.

plot.iris(iris.umap, iris.labels)
plot.iris(iris.wnoise.umap, iris.labels,
          add=T, pch=4, legend.suffix=" (with noise)")

The new observations lie close to their original counterparts.

Configuration objects

The default configuration object is called umap.defaults. This is a list encoding default values for all the parameters used by the algorithm.

umap.defaults

## umap configuration parameters
##            n_neighbors: 15
##           n_components: 2
##                 metric: euclidean
##               n_epochs: 200
##                  input: data
##                   init: spectral
##               min_dist: 0.1
##       set_op_mix_ratio: 1
##     local_connectivity: 1
##              bandwidth: 1
##                  alpha: 1
##                  gamma: 1
##   negative_sample_rate: 5
##                      a: NA
##                      b: NA
##                 spread: 1
##           random_state: NA
##        transform_state: NA
##                    knn: NA
##            knn_repeats: 1
##                verbose: FALSE
##        umap_learn_args: NA

For a description of each field, see the documentation in help(umap.defaults) or the original publication.

To create a custom configuration, we can make a copy of the default object and then update its fields. For example, let’s change the seed for random number generation.

custom.config <- umap.defaults
custom.config$random_state <- 123

We can observe the changed settings by inspecting the object again (try it). To perform the UMAP projection with these settings, we can run the projection again and provide the configuration object as a second argument.

iris.umap.config <- umap(iris.data, config=custom.config)
plot.iris(iris.umap.config, iris.labels,
          main="Another UMAP visualization (different seed)")

The result is slightly different than before due to a new instantiation of the random number generator.

Additional arguments

Another way to customize the algorithm is to specify the parameter values one-by-one as arguments to the function call. The command below achieves equivalent results to the above.

iris.umap.args <- umap(iris.data, random_state=123)

The coordinates in this output object should match the ones from iris.umap.config (check it!).

Behind the scenes, the umap function call extracts most of the parameter values from the default configuration, and then replaces the value of random_state with the newly specified value. It is also possible to use a custom configuration and parameter values together.

Input types

All the examples above apply the umap transformation on a raw dataset. The first stage in the algorithm is the calculation of nearest neighbors and distances between them. In cases when these distances or nearest neighbors are known a-priori, the umap function can start with those inputs instead.

To use a distance matrix instead of raw data, we can set the input argument to ‘dist’.

iris.dist <- as.matrix(dist(iris.data))
iris.umap.dist <- umap(iris.dist, config=custom.config, input="dist")
iris.umap.dist

## umap embedding of 150 items in 2 dimensions
## object components: layout, data, knn, config

Because iris.umap.dist is computed with the custom configuration, it holds the same embedding layout as iris.umap.config above (check it!). However, this object does not carry the original data. As such, it cannot be used to ‘predict’ new data into the embedding: attempting a command like predict(iris.umap.dist, iris.wnoise) will generate an error. This is because the algorithm will not have sufficient information to computing distances between new data points and previously embedded data.

Another way to provide data to function umap is via precomputed nearest neighbors. As we saw above, each object of class ‘umap’ has a component called ‘knn’. We can preview this component by printing it.

iris.umap$knn

## k-nearest neighbors for 150 items with k=15
## object components: indexes, distances
## Note: nearest neighbors may be approximate

This is actually a list with two matrices. One matrix associates each data point to a fixed number of nearest neighbors (the default is 15). The other matrix specifies the distances between them.

To see how to use this data structure, let’s construct an object describing 10 nearest neighbors, and then perform an embedding.

# extract information on 10 nearest neighbors from iris.umap
iris.neighbors <- iris.umap$knn$indexes[, 1:10]
iris.neighbors.distances <- iris.umap$knn$distances[, 1:10]
# construct an object with indexes and distances
iris.knn.10 <- umap.knn(indexes=iris.neighbors,
                        distances=iris.neighbors.distances)
iris.knn.10

## k-nearest neighbors for 150 items with k=10
## object components: indexes, distances
## Note: nearest neighbors may be approximate

# perform an embedding using the precomputed nearest neighbors
iris.umap.knn <- umap(iris.data, config=custom.config,
                      n_neighbors=10, knn=iris.knn.10)

In this function call, argument config specifies most of the parameter values. Because the custom configuration has n_neighbors at 15 and here we want to use 10 instead, the next argument sets this new value. The final argument provides our prepared object. Functions umap detect the availability of this object and can skip calculating nearest neighbors. This can substantially improve running times.

Initial embedding

As shown in the section on tuning, embedding of a raw dataset can be stabilized by setting a seed for random number generation. However, the results are stable only when the raw data are re-processed in exactly the same way. Results are bound to change if data are presented in a different order.

A separate consideration is about the effect of the randomness within the umap algorithms on the state of the random-number generator in the calling environment. By default, the umap function preserves the external random state. This has some pros and cons. One important consequence of the default setting is that when two umap calls are made one after the other, they both receive the same random state. If this is not a desired behavior, use one of the following strategies: (1) make each umap call with a distinct seed, (2) advance the random number generator manually, for example by calling runif() between subsequent calls to umap, or (3) set argument preserve.seed=FALSE.

Prediction

Projection of new data onto an existing embedding uses a separate random number generator, which is controlled via parameter transform_state. This seed ensures that predictions executed in exactly the same way produce identical output each time. The default algorithm further implements a mechanism by which predictions are consistent when performed individually or in batch. Let’s look at an example based on the Iris data.

# predict in batch, display first item
predict(iris.umap, iris.wnoise)[1, , drop=FALSE]

##       [,1]     [,2]
## 1 13.55093 2.217609

# predict only first item
predict(iris.umap, iris.wnoise[1, , drop=FALSE])

##       [,1]     [,2]
## 1 13.55093 2.217609

The mechanism that enables stability between batch and individual predictions also ensures that predictions are stable when data are presented in a different order. However, this mechanism is not enforced (for performance reasons) when the new data contain more than a thousand rows. This is an implementation detail and may change in future versions.