Score query cells against reference classes

scoreCells() provides a lightweight correlation- and signature-based fallback for regimes where a full PhiSpace model is not meaningful, such as single-class references or references with very few classes. It stores score matrices in reducedDim() slots with one column per reference class.

scoreCells(
  reference,
  query,
  class_col = NULL,
  assay_ref = "logcounts",
  assay_query = "logcounts",
  signature_genes = NULL,
  signature_method = c("mean", "findMarkers"),
  marker_test = c("t", "wilcox", "binom"),
  marker_pval_type = "any",
  marker_direction = c("up", "down", "any"),
  n_top_genes = 300,
  n_signature_genes = 100,
  remove_housekeeping = TRUE,
  housekeeping_patterns = c("^Rpl", "^Rps", "^mt-", "^MT-", "^Mrpl", "^Mrps"),
  housekeeping_genes = NULL,
  shared_genes_only = TRUE,
  scoring = c("both", "correlation", "signature"),
  cor_method = c("spearman", "pearson"),
  zscore_signature = TRUE,
  score_prefix = "scoreCells",
  BPPARAM = BiocParallel::SerialParam(),
  verbose = TRUE
)

Arguments

reference

A SingleCellExperiment or SpatialExperiment object.

query

A SingleCellExperiment or SpatialExperiment object to score.

class_col

Character or NULL. Column in colData(reference) defining reference classes. If NULL, all reference cells are treated as one class.

assay_ref

Character. Assay in reference used for scoring.

assay_query

Character. Assay in query used for scoring.

signature_genes

NULL, a character vector, or a named list of character vectors. If NULL, signatures are generated from reference. A character vector is accepted for a single-class reference. A multi-class reference requires a named list whose names exactly match the reference classes. Supplied signatures are used as-is after removing duplicates and genes unavailable in either assay; marker-selection and housekeeping-removal arguments are ignored.

signature_method

Character. Signature selection method. "mean" (default) uses mean-expression ranking for every class. "findMarkers" uses scran::findMarkers() for multi-class references and falls back to mean-expression ranking for single-class references. scran deprecates findMarkers() in Bioconductor 3.24, so this option will be removed when scran removes the function.

marker_test

Character. Test type passed to scran::findMarkers().

marker_pval_type

Character. pval.type passed to scran::findMarkers().

marker_direction

Character. Direction used when selecting markers: "up", "down", or "any".

n_top_genes

Integer. Candidate gene pool per class before removing housekeeping genes.

n_signature_genes

Integer. Number of final signature genes per class.

remove_housekeeping

Logical. Whether to remove housekeeping genes from class signatures.

housekeeping_patterns

Character vector of regex patterns identifying housekeeping genes.

housekeeping_genes

Character vector of additional housekeeping genes. If NULL, a small built-in list is used.

shared_genes_only

Logical. If TRUE, use the intersection of reference and query genes. If FALSE, reference and query row names must be identical.

scoring

Character. Which score matrices to compute: "both", "correlation", or "signature".

cor_method

Character. Correlation method: "spearman" or "pearson".

zscore_signature

Logical. Whether to z-score signature scores. For multi-class references, z-scoring is across classes within each cell. For a single-class reference, z-scoring is across cells.

score_prefix

Character. Prefix for output reducedDim() names.

BPPARAM

BiocParallel parameter object passed to scran::findMarkers().

verbose

Logical. Whether to emit progress messages.

Value

The modified query object with score matrices stored in reducedDim() slots and run details stored in metadata(query)$scoreCells.

Details

A correlation score measures similarity between a query cell and a reference class centroid in the relative expression pattern across that class's effective signature genes. Different classes can therefore be scored using different genes. Correlations are NA for query cells with fewer than two complete observations or zero expression variance across the relevant signature.

A signature score is the average query expression across the same effective signature genes, optionally z-scored. When scoring = "both", the correlation and signature branches use exactly the same genes for each class.

Examples

set.seed(1)
ref <- logNormTransf(scuttle::mockSCE(ncells = 200, ngenes = 300))
query <- logNormTransf(scuttle::mockSCE(ncells = 100, ngenes = 300))
query <- scoreCells(ref, query, class_col = "Cell_Cycle",
                    signature_method = "mean", n_signature_genes = 20,
                    verbose = FALSE)
reducedDimNames(query)