Performs DREAMS dimensionality reduction on the input data. DREAMS is t-SNE with a pull towards a global reference embedding, PCA by default. You get the local cluster structure of t-SNE, and the relative positions of the clusters still mean something. Plain t-SNE makes no such promise. This function provides a user-friendly interface with input validation before calling the Rust implementation.
Usage
dreams(
data,
knn = NULL,
reference = NULL,
n_dim = 2L,
perplexity = 20,
approx_type = c("bh", "bh_qd", "fft", "fft_3k"),
knn_method = c("ivf", "kmknn", "balltree", "hnsw", "annoy", "nndescent", "exhaustive"),
nn_params = params_nn(),
tsne_params = params_tsne(),
dreams_params = params_dreams(),
seed = 42L,
.verbose = TRUE
)Arguments
- data
Numerical matrix or data frame. The data to embed of shape samples x features. Will be coerced to a matrix.
- knn
Optional
NearestNeighboursclass. If provided, DREAMS will skip the k-nearest neighbour graph generation and use this one. Needs more neighbours thanperplexity; the internal search uses3 * perplexity. Defaults toNULL.- reference
Optional numerical matrix or data frame of shape samples x 2. Global reference embedding to regularise towards, e.g. a PHATE or MDS result. If
NULL, the first two principal components are used. Defaults toNULL.- n_dim
Integer. Number of dimensions in the embedding space. Currently only
2Lis supported. Defaults to2L.- perplexity
Numeric. Perplexity parameter, related to the number of nearest neighbours used in manifold learning. Typical values are between 5 and 50. Defaults to
20.0.- approx_type
Character. Approximation method for computing repulsive forces. One of
"bh"for Barnes-Hut,"bh_qd"for the quick-and-dirty Barnes-Hut of qdtsne (tree depth capped atmax_depthinparams_tsne(), repulsion computed once per leaf),"fft"for FFT-accelerated interpolation or"fft_3k"for the three-kernel variant of the latter (one forward and three inverse FFTs per epoch instead of four each). Defaults to"bh".- knn_method
Character. (Approximate) Nearest neighbour method to use. One of
"kmknn","hnsw","annoy","nndescent","balltree","ivf"or"exhaustive". Defaults to"ivf".- nn_params
Named list. Nearest neighbour search parameters, see
params_nn().- tsne_params
Named list. t-SNE algorithm parameters, see
params_tsne().- dreams_params
Named list. DREAMS parameters, see
params_dreams().- seed
Integer. Random seed for reproducibility.
- .verbose
Logical or integer. Controls verbosity.
TRUEor1Lprints timed stages and epochs every 50,2Ladds parameters and the kNN internals,FALSEor0Lis silent. Defaults toTRUE.
Details
The number of neighbours will be 3 * perplexity, as this is a
usual default in tSNE. Setting lambda to 0 in params_dreams() gives
t-SNE started from the reference, 1 returns the (scaled) reference. The
init element of tsne_params is ignored: DREAMS always initialises from
its reference.
Examples
d <- manifold_synthetic_data(type = "clusters", n_samples = 500L)
emb <- dreams(d$data, .verbose = FALSE)
dim(emb)
#> [1] 500 2
