Run native interpolation-based t-SNE from precomputed KNN

tsne_knn() is the direct KNN-input entry point for the native interpolation-based optimizer. It accepts either a list containing KNN indices and distances or separate KNN index and distance matrices. The supplied neighbors are used directly: this function performs no neighbor search or input scaling. PCA is computed only when init_data is supplied and Y_init is absent. The optimizer follows the sparse-affinity and interpolation-based t-SNE literature while using fastEmbedR's own R API and native kernels.

Usage

tsne_knn(
  indices,
  distances = NULL,
  n_neighbors = NULL,
  perplexity = NULL,
  n_components = 2L,
  init_data = NULL,
  Y_init = NULL,
  seed = 4L,
  verbose = FALSE,
  backend = NULL,
  n.cores = NULL,
  learning_rate = "auto",
  early_exaggeration_iter = NULL,
  early_exaggeration = "auto",
  n_iter = NULL,
  exaggeration = NULL,
  initial_momentum = 0.8,
  final_momentum = 0.8,
  max_step_norm = "auto",
  negative_gradient_method = "auto",
  record_costs = FALSE,
  auto_config = TRUE,
  ...
)

Arguments

indices

A list containing KNN indices and distances, or an integer KNN index matrix.

distances

Numeric KNN distance matrix matching indices. Leave NULL when indices is a KNN list.

n_neighbors

Optional number of non-self neighbor columns to use from the supplied KNN graph. This lets you compute a wide KNN once and reuse its first columns. If omitted, the compact affinity policy uses ceiling(perplexity) columns. An explicit value must equal that width.

perplexity

t-SNE perplexity. If NULL, the optimizer chooses a safe value from the supplied KNN width and sample size.

n_components

Output dimensionality, 2 or 3. FFT repulsion is used on every backend.

init_data

Optional original high-dimensional data matrix used only to compute PCA initialization for KNN-input runs. It is not used for neighbor search or optimization.

Y_init

Optional explicit initial layout. In full-graph massive mode this must be a 2D or 3D file-backed .f32 matrix. Use pca(data, tsne_init = TRUE)$tsne_init to precompute and reuse a PCA initialization.

seed

Random seed.

verbose

Print optimizer progress.

backend

Optimizer backend: "cpu", "cuda", or "metal". This selects affinity construction and layout optimization only; it does not trigger a nearest-neighbor search. Host KNN matrices can be consumed by any compiled backend. A CUDA-resident KNN object can be consumed directly only by the CUDA backend. Unavailable GPU requests fail without CPU fallback.

n.cores

Number of CPU cores used for CPU affinity construction and t-SNE optimization. NULL uses the package t-SNE thread option, which defaults to four. No KNN search is performed. Metal and CUDA optimizers ignore this argument.

learning_rate

Positive number or "auto". With "auto", the native optimizer uses n / exaggeration separately for each phase.

early_exaggeration_iter

Number of early-exaggeration iterations.

early_exaggeration

Early-exaggeration multiplier, or "auto" for the default t-SNE rule.

n_iter

Number of normal optimization iterations after early exaggeration.

exaggeration

Normal-phase exaggeration. NULL means 1.

initial_momentum

Momentum during early exaggeration.

final_momentum

Momentum during normal optimization.

max_step_norm

Maximum per-point update norm. "auto" uses the same validated limit on CPU, Metal, and CUDA. Use NULL or NA to disable clipping.

negative_gradient_method

"auto" or "fft"; both use FFT. Other methods fail explicitly. GPU FFT requires compiled native symbols.

record_costs

If TRUE, compute diagnostic KL/cost traces. CUDA and three-dimensional Metal fits reject this option explicitly.

auto_config

If TRUE, choose missing t-SNE settings with a native C++ opt-SNE-inspired policy. The policy uses n / early_exaggeration for "auto" learning rate, chooses missing iteration limits, and enables KLD-based early stopping on small CPU runs where the monitor is not prohibitively expensive. Explicit user-supplied values are respected.

...

Additional low-level optimizer controls, including theta and min_gain.

Value

An embedding matrix with settings stored in attr(layout, "fastEmbedR_config"). Float32 KNN distances, including a CUDA-resident KNN object, produce a float::float32 layout; host double distances produce a standard R double matrix. Native optimization uses float32 in both cases. The exact returned representation is recorded in attr(layout, "precision") and in fastEmbedR_config$output_precision.

Examples

x <- scale(as.matrix(iris[, 1:4]))
d <- as.matrix(stats::dist(x))
diag(d) <- Inf
k <- 15L
idx <- t(apply(d, 1L, order))[, seq_len(k), drop = FALSE]
dst <- matrix(d[cbind(rep(seq_len(nrow(d)), each = k), as.vector(t(idx)))],
    nrow = nrow(d), byrow = TRUE
)
layout <- tsne_knn(idx, dst,
    init_data = x, perplexity = 5,
    early_exaggeration_iter = 5, n_iter = 10
)