Skip to contents

Transform query points into an existing t-SNE embedding

Source: R/transform_tsne.R
transform_tsne.Rd

transform_tsne() places query observations into a fixed reference t-SNE embedding. It follows a fixed-reference t-SNE transform design: query-to-reference affinities are computed from KNN distances, query points are initialized from nearby reference points, and optimization moves only the query points.

Usage

transform_tsne(
  reference_layout,
  knn = NULL,
  reference_data = NULL,
  new_data = NULL,
  k = NULL,
  perplexity = 5,
  initialization = c("median", "weighted", "random"),
  Y_init = NULL,
  n_iter = 250L,
  early_exaggeration_iter = 0L,
  learning_rate = 0.1,
  early_exaggeration = 4,
  exaggeration = 1.5,
  initial_momentum = 0.8,
  final_momentum = 0.8,
  max_grad_norm = 0.25,
  max_step_norm = Inf,
  n_negatives = NULL,
  exact_repulsion_threshold = 4096L,
  n.cores = NULL,
  seed = 4L,
  backend = NULL,
  verbose = FALSE
)

Arguments

reference_layout

Numeric reference embedding matrix, or a fastEmbedR_embedding object.

knn

Optional query-to-reference KNN list with indices and distances.

reference_data

Reference observations in the same preprocessing space used to fit reference_layout. Required only when knn is NULL.

new_data

Query observations in the same preprocessing space as reference_data. Required only when knn is NULL.

k

Number of reference neighbors used for transform KNN. If NULL, uses ceiling(perplexity), matching the package's compact t-SNE support.

perplexity

Transform perplexity. The default is 5.

initialization

Initial query placement: "median" from reference neighbors, inverse-distance "weighted", or "random".

Y_init

Optional initial query embedding matrix. When supplied, it overrides initialization.

n_iter

Number of normal transform optimization iterations.

early_exaggeration_iter

Number of early-exaggeration iterations.

learning_rate

Transform learning rate.

early_exaggeration

Early exaggeration multiplier.

exaggeration

Normal transform exaggeration multiplier.

initial_momentum

Momentum used during early exaggeration.

final_momentum

Momentum used during normal optimization.

max_grad_norm

Maximum per-query gradient norm. Use Inf to disable.

max_step_norm

Maximum per-query step norm. Use Inf to disable.

n_negatives

Number of sampled reference points for repulsion when the reference set is larger than exact_repulsion_threshold. GPU sampled repulsion is native and experimental for large reference sets.

exact_repulsion_threshold

Use exact query-reference repulsion at or below this reference count.

n.cores

Number of CPU cores for the native optimizer.

seed

Random seed.

backend

Backend used for query KNN when knn is NULL; "metal" and "cuda" run their native fixed-reference transform optimizers when those backends were compiled. CUDA accepts 2D or 3D reference layouts; Metal currently accepts 2D. Explicit unavailable GPU requests fail; CPU work is never reported as Metal or CUDA.

verbose

Print native optimizer progress.

Value

A numeric matrix with one row per query observation.

Examples

reference <- matrix(c(0, 0, 1, 0, 0, 1, 1, 1), 4L, 2L, byrow = TRUE)
query_knn <- list(
    indices = matrix(c(1L, 2L, 3L, 4L), 2L, 2L, byrow = TRUE),
    distances = matrix(c(0.1, 0.2, 0.15, 0.25), 2L, 2L, byrow = TRUE)
)
query_layout <- transform_tsne(
    reference,
    knn = query_knn, perplexity = 0.5,
    n_iter = 2, exact_repulsion_threshold = 10, seed = 1
)