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. DefaultFALSE.
Value
A list with elements
resultsData frame with one row per feature:
feature,F_stat(observed pseudo-F),R2(\(SS_B / SS_T\)),pvalueandpadj(Benjamini-Hochberg).exactLogical, whether the P-values are exact.
n_permNumber of assignments evaluated (\(|\Pi|\) if exact).
min_pvalueSmallest attainable P-value.
F_null,assignmentsOnly 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), ])
} # }