Skip to contents

This article shows how the main parameters of stat_umap(), geom_umap() and umap_embed() change an embedding. The data has nested structure: three groups, each made of three clusters of different spread.

set.seed(1)
groups <- matrix(rnorm(3 * 20, sd = 12), 3)
clusters <- groups[rep(1:3, each = 3), ] + matrix(rnorm(9 * 20, sd = 4), 9)
label <- rep(1:9, each = 150)
x <- clusters[label, ] + matrix(rnorm(length(label) * 20, sd = rep(c(0.5, 1, 2), each = 150)), ncol = 20)
df <- data.frame(x, group = factor(LETTERS[(label - 1) %/% 3 + 1]), cluster = factor(label))

n_neighbors and min_dist

n_neighbors sets the size of the neighbourhood that UMAP tries to preserve. Small values focus on fine, local structure; large values on the global arrangement. min_dist controls how tightly points may be packed: small values give dense clumps, large values a more even spread.

grid <- expand.grid(n_neighbors = c(5, 15, 50), min_dist = c(0.01, 0.1, 0.5, 0.99))
embeddings <- Map(
  function(k, d) {
    emb <- umap_embed(df, starts_with("X"), n_neighbors = k, min_dist = d, seed = 1)
    cbind(emb, df[c("group", "cluster")], n_neighbors = k, min_dist = d)
  },
  grid$n_neighbors, grid$min_dist
)
embeddings <- do.call(rbind, embeddings)

ggplot(embeddings, aes(UMAP1, UMAP2, colour = group)) +
  geom_point(size = 0.3) +
  facet_grid(
    vars(n_neighbors), vars(min_dist),
    scales = "free", labeller = label_both
  ) +
  guides(colour = guide_legend(override.aes = list(size = 2))) +
  theme_umap()

Within a plot, you would write each of these as a single layer, e.g.

ggplot(df, aes(colour = group)) +
  geom_umap(features = starts_with("X"), n_neighbors = 50, min_dist = 0.5)

Distance metrics

metric defines distances in the input space. Cosine and correlation distances ignore the magnitude of the feature vectors, which is useful for text embeddings, counts and other data where only the direction matters.

metrics <- c("euclidean", "manhattan", "cosine", "correlation")
by_metric <- do.call(rbind, lapply(metrics, function(m) {
  emb <- umap_embed(df, starts_with("X"), metric = m, seed = 1)
  cbind(emb, df["group"], metric = m)
}))
ggplot(by_metric, aes(UMAP1, UMAP2, colour = group)) +
  geom_point(size = 0.3) +
  facet_wrap(vars(metric), nrow = 1, scales = "free") +
  theme_umap()

Flavour and initialisation

flavour = "0.5" (the default) reproduces the classic umap-learn pipeline: a spectral initialisation followed by stochastic gradient descent. flavour = "0.6" uses umap-learn 0.6’s recursive initialisation and the Adam optimiser; it is faster and deterministic for a fixed number of threads. init overrides the initialisation of either flavour.

combos <- expand.grid(flavour = c("0.5", "0.6"), init = c("auto", "pca", "random"), stringsAsFactors = FALSE)
by_flavour <- do.call(rbind, Map(function(f, i) {
  emb <- umap_embed(df, starts_with("X"), flavour = f, init = i, seed = 1)
  cbind(emb, df["group"], flavour = f, init = i)
}, combos$flavour, combos$init))
ggplot(by_flavour, aes(UMAP1, UMAP2, colour = group)) +
  geom_point(size = 0.3) +
  facet_grid(vars(flavour), vars(init), scales = "free", labeller = label_both) +
  theme_umap()

Scaling

UMAP uses the features as they are. When they are measured in different units, the feature with the largest range dominates the distances. scale = TRUE standardises every feature first.

penguins <- palmerpenguins::penguins
p <- ggplot(penguins, aes(colour = species)) + theme_umap()
patch <- list(
  p + geom_umap(features = bill_length_mm:body_mass_g, na.rm = TRUE) + ggtitle("scale = FALSE"),
  p + geom_umap(features = bill_length_mm:body_mass_g, scale = TRUE, na.rm = TRUE) + ggtitle("scale = TRUE")
)
has_patchwork <- requireNamespace("patchwork", quietly = TRUE)
if (has_patchwork) {
  patchwork::wrap_plots(patch, guides = "collect")
} else {
  for (pl in patch) print(pl)
}

Advanced settings

umap_control() holds the remaining parameters of the algorithm. The most useful are repulsion_strength (how strongly unrelated points repel each other) and negative_sample_rate (how many repulsive samples are drawn per attractive one).

strengths <- c(0.25, 1, 4)
by_strength <- do.call(rbind, lapply(strengths, function(s) {
  emb <- umap_embed(df, starts_with("X"), seed = 1, control = umap_control(repulsion_strength = s))
  cbind(emb, df["group"], repulsion_strength = s)
}))
ggplot(by_strength, aes(UMAP1, UMAP2, colour = group)) +
  geom_point(size = 0.3) +
  facet_wrap(vars(repulsion_strength), labeller = label_both, scales = "free") +
  theme_umap()