Skip to contents

Tests each feature for a condition-associated shift in its MOSAIC embedding. For each feature, a PERMANOVA pseudo-F statistic is computed on the distances between its sample embeddings, and significance is assessed by permuting condition labels across samples with the embedding held fixed. The same label assignments are used for all features; each feature is compared with its own null distribution.

Usage

run_DC_test(
  mosaic_embed_list,
  groups,
  blocks = NULL,
  n_perm = 999,
  max_exact = 2e+05,
  dist_method = c("euclidean", "cosine"),
  seed = NULL,
  feature_chunk = 2000,
  perm_chunk = 2000,
  return_null = FALSE
)

Arguments

mosaic_embed_list

Named list of per-sample embedding matrices (features x latent dimensions), as returned by run_MOSAIC()$mosaic_embed_list. All matrices must have the same features in the same order.

groups

Character or factor vector of condition labels, one per sample, in the order of mosaic_embed_list.

blocks

Optional vector of block labels (e.g. donor IDs), one per sample. If given, labels are permuted only within blocks. Default NULL (all samples exchangeable).

n_perm

Integer. Number of random assignments used when the admissible set is too large to enumerate. Default 999.

max_exact

Numeric. Enumerate all admissible assignments if their number is at most this value. Set to 0 to always use random assignments. Default 2e5.

dist_method

Distance between the sample embeddings of a feature: "euclidean" (default) or "cosine" (\(1 -\) cosine similarity).

seed

Optional integer seed for the random assignments.

feature_chunk, perm_chunk

Integers controlling memory use: number of features and of assignments processed at once.

return_null

Logical. If TRUE, also return the full features x assignments matrix of permutation pseudo-F statistics and the assignment matrix. Default FALSE.

Value

A list with elements

results

Data frame with one row per feature: feature, F_stat (observed pseudo-F), R2 (\(SS_B / SS_T\)), pvalue and padj (Benjamini-Hochberg).

exact

Logical, whether the P-values are exact.

n_perm

Number of assignments evaluated (\(|\Pi|\) if exact).

min_pvalue

Smallest attainable P-value.

F_null, assignments

Only if return_null = TRUE: the permutation statistics (features x assignments) and the assignments (samples x assignments, as group labels).

Details

Without blocks, all assignments preserving the group sizes are admissible; with blocks, labels are permuted within blocks. If the number of admissible assignments is at most max_exact, all of them are enumerated and exact P-values are returned. Otherwise n_perm random assignments are used and \(p = (1 + \sum_b I\{F^{(b)} \ge F\}) / (B + 1)\). P-values are adjusted with the Benjamini-Hochberg procedure.

See also

run_MOSAIC to generate the embedding, compute_feature_similarity for per-feature sample similarity matrices used in visualization and subgroup detection.

Examples

if (FALSE) { # \dontrun{
result <- run_MOSAIC(
  list(RNA = seurat_rna, ADT = seurat_adt),
  assays = c("RNA", "ADT"),
  sample_meta = "sample_id",
  condition_meta = "time"
)

# Independent samples
dc <- run_DC_test(result$mosaic_embed_list,
                  groups = result$annotation$Condition)

# Paired design: permute time labels within donor
dc <- run_DC_test(result$mosaic_embed_list,
                  groups = result$annotation$Condition,
                  blocks = donor_ids)
head(dc$results[order(dc$results$pvalue, -dc$results$F_stat), ])
} # }