Skip to contents

Fast Wilcoxon Rank-Sum + AUC Marker Test (BPCells / Seurat-v5 Compatible)

RunWilcoxAUC.Rd

A drop-in replacement for presto::wilcoxauc(seurat_object, ...) that works reliably with BPCells-backed and Seurat v5 multi-layer objects.

The standard presto::wilcoxauc.Seurat method extracts the expression matrix internally in a way that can error with lazy matrices or v5 layer syntax. RunWilcoxAUC bypasses that path: it pulls the matrix through .get_layer_data() (which handles BPCells lazy subsetting, Seurat v3 slot= vs v5 layer=, and sparse → dgCMatrix coercion) and then calls presto::wilcoxauc(matrix, y) so S3 dispatch lands on wilcoxauc.default directly - no internal ::: access needed.

When split.by is supplied the test is run independently within each level of that column (e.g. each cell type), and the results are combined into a single data frame with an extra column named after split.by.

Usage

RunWilcoxAUC(
  seurat_object,
  group.by = NULL,
  split.by = NULL,
  groups_use = NULL,
  assay = "RNA",
  layer = "data",
  caffeinate = FALSE,
  ...
)

Arguments

seurat_object

A Seurat object.

group.by

Character. Metadata column whose levels define the comparison groups (e.g. "Condition", "Assignment"). When NULL, Idents is used.

split.by

Character or NULL. Metadata column to split on before running the test. The test is run independently within each level (e.g. split.by = "CellType" finds condition markers per cell type). The output gains a column named after split.by identifying each level. Levels with fewer than 2 groups after filtering are skipped with a message. Default NULL (no split).

groups_use

Character vector or NULL. Restrict the test to a subset of group.by levels. Applied within each split level when split.by is set. NULL = all levels.

assay

Character. Assay to extract. Default "RNA".

layer

Character. Layer / slot to extract. Default "data" (log-normalized counts, recommended for AUC statistics). "counts" uses raw counts; "scale.data" uses scaled values (note: negative values make AUC less interpretable but the test is still valid).

caffeinate

Logical. When TRUE, prevents the machine from sleeping during the run (macOS only; uses caffeinate -i). Default FALSE.

...

Additional arguments forwarded to wilcoxauc.

Value

A data.frame with one row per (feature × group) combination containing auc, pval, padj, logFC, pct_in, pct_out - the standard presto output. When split.by is set, an additional column named after split.by identifies which split level each row came from.

See also

wilcoxauc

Examples

if (FALSE) { # \dontrun{
# Basic usage - use active identity
markers <- RunWilcoxAUC(SeuratObj)

# Specify a metadata column
markers <- RunWilcoxAUC(SeuratObj, group.by = "Condition")

# Find condition markers within each cell type
markers <- RunWilcoxAUC(SeuratObj,
                         group.by = "Condition",
                         split.by = "CellType")

# Filter results for one cell type
library(dplyr)
markers |> filter(CellType == "Microglia", padj < 0.05, auc > 0.6)

# Find cluster markers within each sample
markers <- RunWilcoxAUC(SeuratObj,
                         group.by = "Cluster",
                         split.by = "Sample")
} # }