Introduction

Non-linear dimensionality reduction techniques such as t-SNE (Maaten and Hinton 2008) and UMAP (McInnes et al. 2020) produce a low-dimensional embedding that summarises the global structure of high-dimensional data. These techniques can be particularly useful when visualising high-dimensional data in a biological setting. However, these embeddings may not accurately represent the local density of data in the original space, resulting in misleading visualisations where the space given to clusters of data does not represent the fraction of the high dimensional space that they occupy. densvis implements the density-preserving objective function described by (Narayan et al. 2020) which aims to address this deficiency by including a density-preserving term in the t-SNE and UMAP optimisation procedures. This can enable the creation of visualisations that accurately capture differing degrees of transcriptional heterogeneity within different cell subpopulations in scRNAseq experiments, for example.

Setting up the data

We will illustrate the use of densvis using simulated data. We will first load the densvis and Rtsne libraries and set a random seed to ensure the t-SNE visualisation is reproducible (note: it is good practice to ensure that a t-SNE embedding is robust by running the algorithm multiple times).

library("densvis")
library("Rtsne")
library("uwot")
library("ggplot2")
theme_set(theme_bw())
set.seed(14)

data <- data.frame(
    x = c(rnorm(1000, 5), rnorm(1000, 0, 0.2)),
    y = c(rnorm(1000, 5), rnorm(1000, 0, 0.2)),
    class = c(rep("Class 1", 1000), rep("Class 2", 1000))
)
ggplot() +
    aes(data[, 1], data[, 2], colour = data$class) +
    geom_point(pch = 19) +
    scale_colour_discrete(name = "Cluster") +
    ggtitle("Original co-ordinates")

Running t-SNE

Density-preserving t-SNE can be generated using the densne function. This function returns a matrix of t-SNE co-ordinates. We set dens_frac (the fraction of optimisation steps that consider the density preservation) and dens_lambda (the weight given to density preservation relative to the standard t-SNE objective) each to 0.5.

fit1 <- densne(data[, 1:2], dens_frac = 0.5, dens_lambda = 0.5)
ggplot() +
    aes(fit1[, 1], fit1[, 2], colour = data$class) +
    geom_point(pch = 19) +
    scale_colour_discrete(name = "Class") +
    ggtitle("Density-preserving t-SNE") +
    labs(x = "t-SNE 1", y = "t-SNE 2")

If we run t-SNE on the same data, we can see that the density-preserving objective better represents the density of the data,

fit2 <- Rtsne(data[, 1:2])
ggplot() +
    aes(fit2$Y[, 1], fit2$Y[, 2], colour = data$class) +
    geom_point(pch = 19) +
    scale_colour_discrete(name = "Class") +
    ggtitle("Standard t-SNE") +
    labs(x = "t-SNE 1", y = "t-SNE 2")

Running UMAP

A density-preserving UMAP embedding can be generated using the densmap function. This function returns a matrix of UMAP co-ordinates. As with t-SNE, we set dens_frac (the fraction of optimisation steps that consider the density preservation) and dens_lambda (the weight given to density preservation relative to the standard t-SNE objective) each to 0.5.

fit1 <- densmap(data[, 1:2], dens_frac = 0.5, dens_lambda = 0.5)
#> Installing pyenv ...
#> Done! pyenv has been installed to '/github/home/.local/share/r-reticulate/pyenv/bin/pyenv'.
#> Using Python: /github/home/.pyenv/versions/3.12.10/bin/python3.12
#> Creating virtual environment '/github/home/.cache/R/basilisk/1.24.0/densvis/1.22.0/densvis' ...
#> Done!
#> Installing packages: pip, wheel, setuptools
#> Installing packages: 'umap-learn==0.5.9.post2', 'scikit-learn==1.7.0', 'numba==0.62.0', 'pynndescent==0.5.13', 'scipy==1.16.0', 'numpy==2.3.4', 'llvmlite==0.45.0'
#> Virtual environment '/github/home/.cache/R/basilisk/1.24.0/densvis/1.22.0/densvis' successfully created.
ggplot() +
    aes(fit1[, 1], fit1[, 2], colour = data$class) +
    geom_point(pch = 19) +
    scale_colour_discrete(name = "Class") +
    ggtitle("Density-preserving t-SNE") +
    labs(x = "t-SNE 1", y = "t-SNE 2")

If we run UMAP on the same data, we can see that the density-preserving objective better represents the density of the data,

fit2 <- umap(data[, 1:2])
ggplot() +
    aes(fit2[, 1], fit2[, 2], colour = data$class) +
    geom_point(pch = 19) +
    scale_colour_discrete(name = "Class") +
    ggtitle("Standard t-SNE") +
    labs(x = "t-SNE 1", y = "t-SNE 2")