Run native interpolation-based t-SNE from a data matrix

tsne() computes or reuses a KNN graph, then runs the package-native two-phase t-SNE optimizer. The default optimizer is CPU-native. Explicit backend = "metal" and backend = "cuda" requests use the matching package-native GPU optimizer when compiled and fail clearly if the requested backend is unavailable. The implementation follows published sparse-affinity and interpolation-based t-SNE methods and provides independent CPU, Metal, and CUDA kernels.

Usage

tsne(
  data,
  perplexity = NULL,
  n_components = 2L,
  init_data = NULL,
  Y_init = NULL,
  standardize = FALSE,
  pca_dims = NULL,
  metric = c("euclidean", "cosine", "correlation"),
  nn = NULL,
  seed = 4L,
  backend = NULL,
  keep_knn = FALSE,
  verbose = FALSE,
  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,
  landmarks = FALSE,
  transform_k = NULL,
  transform_perplexity = 5,
  transform_iter = 250L,
  transform_early_exaggeration_iter = 0L,
  transform_n_negatives = NULL,
  initialization = c("median", "weighted", "random"),
  massive = "off",
  output = NULL,
  chunk_rows = NULL,
  memory_limit = "8GB",
  devices = NULL,
  landmark_method = "reservoir",
  checkpoint = FALSE,
  resume = FALSE,
  ...
)

Arguments

data

Numeric matrix/data frame with observations in rows, a list containing KNN indices and distances, or an experimental saved affinity graph for massive = "out_of_core_graph".

perplexity

t-SNE perplexity. If NULL, uses the largest safe value up to 30 that is available for the input. Compact affinity support uses ceiling(perplexity) non-self neighbors.

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. 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.

standardize

Center and scale columns before KNN. Defaults to FALSE so one-call results match a KNN object computed from the supplied matrix.

pca_dims

Optional PCA dimension before KNN.

metric

KNN distance metric for one-call matrix input: "euclidean", "cosine", or "correlation".

nn

Optional precomputed KNN output for resident matrix input. In EXPERIMENTAL massive = "landmark" mode, a previous massive landmark embedding reuses its saved selection and query-to-landmark KNN. Its source, reference, neighbor count, and backend must match.

seed

Random seed.

backend

Execution backend: "cpu", "cuda", or "metal". CPU KNN uses package-native exact search below 5,000 rows and HNSW otherwise. Metal uses package-native exact or recall-tuned IVF-Flat search. CUDA uses cuVS brute-force exact search below 100,000 rows and cuVS IVF-Flat above that threshold. Device pointers pass directly to the native CUDA t-SNE optimizer. Unsupported GPU requests fail clearly and are not relabelled CPU runs.

keep_knn

If TRUE, retain KNN matrices in the returned object.

verbose

Print optimizer progress.

n.cores

Number of CPU cores used by CPU PCA preprocessing, KNN, and t-SNE optimization. With NULL, PCA uses options(n.cores) (one by default), while KNN and t-SNE use their stage defaults. Native GPU stages 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.

landmarks

FALSE (the default) embeds all observations. A fraction in (0, 1), a positive landmark count, or explicit row indices enables landmark embedding followed by fixed-reference transformation of the remaining rows.

transform_k

Number of landmark neighbors used to place non-landmark observations. Used only when landmarking is enabled.

transform_perplexity

Perplexity used to transform non-landmark rows.

transform_iter

Number of normal transform iterations. Use zero for projection without transform refinement.

transform_early_exaggeration_iter

Number of transform early-exaggeration iterations.

transform_n_negatives

Number of sampled reference negatives used by large fixed-reference transforms.

initialization

Initial placement for transformed rows: "median", "weighted", or "random".

massive

"off" (default), experimental "landmark", or "out_of_core_graph" for a prepared t-SNE affinity graph. Landmarking is always explicit.

output

New .f32 path for experimental file-backed coordinates.

chunk_rows

Maximum experimental query rows per batch.

memory_limit

Conservative experimental RAM budget.

devices

Optional CUDA device indices for experimental landmark query projection. Reference fitting and KNN use the first device.

landmark_method

Sampling method for experimental landmark mode: "reservoir" (default) or "random" for fast random-access storage. Auto mode uses ordinary t-SNE when its conservative memory estimate fits; otherwise it reports and runs approximate landmark t-SNE. The landmark route requires a file-backed massive_matrix() and a new .f32 output. Full-graph mode streams affinities into the CPU FFT optimizer and currently has no CUDA route.

checkpoint

Save experimental workflow stages. Full-graph t-SNE also saves coordinates, momentum updates, and adaptive gains every 100 iterations and at the final iteration.

resume

Continue a matching interrupted experimental workflow. Changed input, backend, or fit controls fail without recomputation.

...

Additional low-level parameters passed to tsne_knn().

Value

A fastEmbedR_embedding object. Landmark fits also contain model, which can be passed to project_landmark_model() for new observations.

Details

The t-SNE API exposes the principal scientifically consequential optimizer controls: perplexity, initialization, iteration counts, early and normal exaggeration, learning rate, momentum, and clipping. FFT repulsion is fixed. Setting auto_config = FALSE disables automatic iteration and stopping choices; explicit values always override automatic values. The matrix-input function deliberately does not expose a nearest-neighbor index type or tuning parameters: it uses the backend router with target recall 0.99. Supply an externally generated KNN object to tsne_knn() when search policy must be controlled independently. The resolved settings are returned in fit$parameters. Affinity construction always uses compact support with k = ceiling(perplexity) non-self neighbors. Landmark mode embeds the selected reference rows with the same t-SNE implementation and transforms all remaining rows while keeping the reference coordinates fixed. Resident precomputed KNN input and explicit init_data or Y_init cannot be combined with landmarking.

Examples

fit <- tsne(
    as.matrix(iris[, 1:4]),
    perplexity = 5,
    early_exaggeration_iter = 5, n_iter = 10, seed = 1
)
plot(fit, labels = iris$Species)