uwot

min_dist

This is a mainly aesthetic parameter, which defines how close points can get in the output space. A smaller value tends to make any clusters in the output more compact. You should experiment with values between 0 and 1, although don’t choose exactly zero. The default is 0.01, which seems like it’s a bit small for iris. Let’s crank up min_dist to 0.3:

set.seed(42)
iris_umap_md05 <- umap(iris, min_dist = 0.3)
plot_umap(iris_umap_md05)

This has made the clusters bigger and closer together, so we’ll use min_dist = 0.3 for the other examples with iris.

n_neighbors

This defines the number of items in the dataset that define the neighborhood around each point. Set it too low and you will get a more fragmented layout. Set it too high and you will get something that will miss a lot of local structure.

Here’s a result with 5 neighbors:

set.seed(42)
iris_umap_nbrs5 <- umap(iris, n_neighbors = 5, min_dist = 0.3)
plot_umap(iris_umap_nbrs5)

It’s not hugely different from the default of 15 neighbors, but the clusters are a bit more broken up.

There should be a more pronounced difference going the other way and looking at 100 neighbors:

set.seed(42)
iris_umap_nbrs100 <- umap(iris, n_neighbors = 100, min_dist = 0.3)
plot_umap(iris_umap_nbrs100)

Here there is a much more uniform appearance to the results. It’s always worth trying a few different values of n_neighbors, especially larger values, although larger values of n_neighbors will lead to longer run times. Sometimes small clusters that you think are meaningful may in fact be artifacts of setting n_neighbors too small, so starting with a larger value and looking at the effect of reducing n_neighbors can help you avoid over interpreting results.

init

The default initialization of UMAP is to use spectral initialization, which acts upon the (symmetrized) k-nearest neighbor graph that is in determined by your choice of n_neighbors. This is usually a good choice, but it involves a very sparse matrix, which can sometimes be a bit too sparse, which leads to numerical difficulties which manifest as slow run times or even hanging calculations. If your dataset causes these issues, you can either try increasing n_neighbors but I have seen cases where that would be inconvenient in terms of CPU and RAM usage. An alternative is to use the first two principal components of the data, which at least uses the data you provide to give a solid global picture of the data that UMAP can refine. It’s not appropriate for every dataset, but in most cases, it’s a perfectly good alternative.

The only gotcha with it is that depending on the scaling of your data, the initial coordinates can have large inter-point distances. UMAP will not optimize that well, so such an output should be scaled to a small standard deviation. If you set init = "spca", it will do all that for you, although to be more aligned with the UMAP coordinate initialization, I recommend you also set init_sdev = "range" as well. init_sdev can also take a numerical value for the standard deviation. Values from 1e-4 to 10 are reasonable, but I recommend you stick to the default of "range".

set.seed(42)
iris_umap_spca <-
  umap(iris,
    init = "spca",
    init_sdev = "range",
    min_dist = 0.3
  )
plot_umap(iris_umap_spca)

This doesn’t have a big effect on iris, but it’s good to know about this as an option: and it can also smooth out the effect of changing n_neighbors on the initial coordinates with the standard spectral initialization, which can make it easier to see the effect of changing n_neighbors on the final result.

Some other init options to know about:

• "random": if the worst comes to the worst, you can always fall back to randomly assigning the initial coordinates. You really want to avoid this if you can though, because it will take longer to optimize the coordinates to the same quality, so you will need to increase n_epochs to compensate. Even if you do that, it’s much more likely that you will end up in a minimum that is less desirable than one based on a good initialization. This will make interpreting the results harder, as you are more likely to end up with different clusters beings split or mixed with each other.
• If you have some coordinates you like from another method, you can pass them in as a matrix. But remember will probably want to scale them with init_sdev though.

dens_scale

The dens_scale parameter varies from 0 to 1 and controls how much of the relative densities of the input data is attempted to be preserved in the output.

set.seed(42)
iris_umapds <- umap(iris, min_dist = 0.3, dens_scale = 0.5)
plot_umap(iris_umapds)

This has shrunk the black cluster on the left of the plot (those are of species setosa), which reflect that the density of the setosa points is less spread out in the input data than the other two species. For more on dens_scale please read its dedicated article.