Performs densMAP dimensionality reduction on the input data. densMAP is UMAP with an added density-preserving term, so a tight cluster stays tight and a diffuse one stays diffuse. Plain UMAP gives you no such guarantee: relative sizes in the embedding mean nothing. This function provides a user-friendly interface with input validation before calling the Rust implementation.
Usage
densmap(
data,
knn = NULL,
n_dim = 2L,
k = 15L,
min_dist = 0.5,
spread = 1,
knn_method = c("nndescent", "kmknn", "balltree", "hnsw", "annoy", "exhaustive", "ivf"),
nn_params = params_nn(),
umap_params = params_umap(),
dens_params = params_densmap(),
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, densMAP will skip the k-nearest neighbour graph generation and use this one. A wider graph is cut tok, with a warning on stderr. Defaults toNULL.- n_dim
Integer. Number of dimensions in the embedding space. Defaults to
2L.- k
Integer. Number of nearest neighbours to consider for manifold approximation. Larger values result in more global structure being preserved. Defaults to
15L.- min_dist
Numeric. Minimum distance between points in the embedding. Controls how tightly points are packed. Smaller values result in more clustered embeddings. Must be >= 0. Defaults to
0.5. If you use SGD, consider reducing this!- spread
Numeric. Effective scale of embedded points. Determines the scale at which embedded points will be spread out. Defaults to
1.0.- knn_method
Character. (Approximate) Nearest neighbour method to use. One of
"kmknn","hnsw","annoy","nndescent","balltree","ivf"or"exhaustive". Defaults to"nndescent".- nn_params
Named list. Nearest neighbour search parameters, see
params_nn().- umap_params
Named list. UMAP algorithm parameters, see
params_umap().- dens_params
Named list. Density-preservation parameters, see
params_densmap().- seed
Integer. Random seed for reproducibility. Defaults to
42L.- .verbose
Logical or integer. Controls verbosity.
TRUEor1Lprints timed stages and epochs every 50,2Ladds parameters and the kNN internals,FALSEor0Lis silent. Defaults toTRUE.
Details
Setting lambda to 0 in params_densmap() recovers plain
umap() exactly. The density term is only active over the final frac of
the epochs, which is why it costs comparatively little.
Examples
d <- manifold_synthetic_data(type = "clusters", n_samples = 500L)
emb <- densmap(d$data, .verbose = FALSE)
dim(emb)
#> [1] 500 2
