Evaluate an embedding against high-dimensional structure — evaluate

Trustworthiness and continuity use their standard rank-penalty definitions. Local rank metrics are computed exactly on a deterministic subsample so the function does not allocate all-pairs matrices for the complete dataset. Float32 inputs are sampled before conversion to a dense double matrix.

Usage

evaluate_embedding(
  x_high,
  embedding,
  labels = NULL,
  batch = NULL,
  k = c(15L, 30L, 50L),
  primary_k = NULL,
  reference_nn = NULL,
  sample_size_for_global_metrics = min(5000L, nrow(x_high)),
  sample_size_for_local_metrics = min(2000L, nrow(x_high)),
  use_cache = FALSE,
  cache_dir = file.path("results", "cache"),
  force_recompute = FALSE,
  seed = NA_integer_,
  method = NA_character_,
  backend = NA_character_,
  n.cores = NULL,
  dataset = NA_character_
)

Arguments

x_high: High-dimensional input, usually scaled data or PCA scores.
embedding: Low-dimensional embedding matrix.
labels: Optional biological/class labels.
batch: Optional batch labels.
k: Neighbor sizes used for structure metrics.
primary_k: Neighbor size used for scalar trustworthiness, continuity, label accuracy, rare-class recall, density summaries, and rank-error metrics. The default NULL preserves the historical k = 15 behavior when possible.
reference_nn: Optional precomputed high-dimensional nearest-neighbor list. It may include a self-neighbor column.
sample_size_for_global_metrics: Maximum deterministic subsample size for all-pairs global distance metrics.
sample_size_for_local_metrics: Maximum deterministic subsample size for local trustworthiness, continuity, and neighbor preservation metrics.
use_cache: Cache the high-dimensional reference neighbors used by quality metrics.
cache_dir: Directory for quality-metric reference-neighbor cache files.
force_recompute: Ignore cached quality reference neighbors.
seed: Random seed recorded in the output and used for subsampling.
method: Method name recorded in the output.
backend: Backend name recorded in the output.
n.cores: Number of CPU cores used when quality metrics need nearest-neighbor searches. Ignored by native GPU metric backends.
dataset: Dataset name recorded in the output.

Value

A one-row data frame with local, global, label-aware, batch-aware, and metadata columns. Per-class recall is also attached as an attribute.

Examples

x <- scale(as.matrix(iris[, 1:4]))
metrics <- evaluate_embedding(
    x, x[, 1:2],
    labels = iris$Species, k = 5,
    sample_size_for_local_metrics = 100,
    sample_size_for_global_metrics = 100,
    seed = 1
)