Automated cell-type annotation with rcellmarker, scType, and SingleR

Runs up to three automated cell-type annotation methods on a Seurat object, adds their results as new metadata columns, and produces two summary PDFs:

An AutoAssignment umaps.pdf with scType, rcellmarker, and cluster UMAPs side-by-side.
An AutoAssignment umaps with singleR.pdf + Assignment Helper.pdf combining all annotations and canonical-marker dotplots.

Usage

CellTypeAssignmentHelper(
  seurat_object,
  markers,
  cluster_column = "Cluster",
  output_dir = NULL,
  object_name = "",
  subset_name = "",
  reduction = "umap",
  cluster_colors = NULL,
  species = "human",
  run_rcellmarker = TRUE,
  run_sctype = TRUE,
  sctype_tissues = c("Immune system", "Brain"),
  sctype_assay = "RNA",
  sctype_layer = "scale.data",
  sctype_db = NULL,
  run_singler = TRUE,
  singler_ref = NULL,
  singler_col = "SingleRAssignment",
  markers_csv = NULL,
  marker_groups = NULL,
  top_n_per_cluster = 3L,
  extra_dimplot_cols = NULL,
  extra_col_colors = NULL,
  col.min = 0,
  col.max = 2,
  scale.min = 0,
  scale.max = 100,
  caffeinate = FALSE
)

Arguments

seurat_object

A Seurat object.

markers

Data frame of DE results from presto::wilcoxauc(). Required for rcellmarker annotation and for the top-marker dotplot. Expected columns: feature, group, avgExpr, avg_log2FC (or logFC), auc, pval, padj, pct_in, pct_out.

cluster_column

Character. Metadata column holding cluster labels. Default "Cluster".

output_dir

Character. Directory for PDFs.

object_name

Character. Prefix for PDF filenames.

subset_name

Character. Second prefix component.

reduction

Character. UMAP reduction name. Default "umap".

cluster_colors

Named character vector of colors for cluster_column levels. NULL auto-generates from Nour_pal().

species

Character. "human" (default) or "mouse". Controls: (1) which gene column is read from the markers CSV (Human vs Mouse), (2) the rcellmarker species argument, and (3) which CellChatDB is loaded in downstream CellChat workflows.

run_rcellmarker

Logical. Run rcellmarker automated annotation? Requires the rcellmarker package. Default TRUE.

run_sctype

Logical. Run scType automated annotation? Requires openxlsx. Default TRUE.

sctype_tissues

Character vector of tissue type(s) to query from the bundled ScTypeDB_full.xlsx. Combine multiple types for broader coverage. All valid values (from the bundled database):

"Adrenal" - adrenal gland
"Brain" - cerebral cortex, broad neuronal/glial types
"Eye" - retinal and eye-specific cell types
"Heart" - cardiac cell types
"Hippocampus" - hippocampal-specific subtypes (use with "Brain" for combined brain data)
"Immune system" - broad immune cells: T, B, NK, myeloid, etc.
"Intestine" - intestinal epithelial and stromal types
"Kidney" - renal cell types
"Liver" - hepatocytes, Kupffer cells, stellate cells
"Lung" - airway epithelium, alveolar cells, immune
"Muscle" - skeletal and smooth muscle
"Pancreas" - islet and exocrine types
"Placenta" - trophoblast and decidual types
"Spleen" - splenic immune populations
"Stomach" - gastric epithelial types
"Thymus" - thymocyte and thymic stromal types

Recommended combinations: c("Brain", "Hippocampus") for brain snRNAseq; c("Immune system", "Spleen") for immune-rich tissues; c("Immune system", "Brain") for neuroinflammation datasets.

sctype_assay

Character. Seurat assay to use for scoring. Must contain a scale.data (scaled) layer. Common choices:

"RNA" - standard full assay (default); use sctype_layer = "scale.data"
"sketch" - BPCells sketch assay for large datasets; use sctype_layer = "scale.data" after ScaleData() on the sketch

sctype_layer

Character. Layer within sctype_assay that holds scaled expression values. Default "scale.data". Must be a scaled (mean-centered) matrix - scType scores are not meaningful on raw counts.

sctype_db

Character or NULL. Path to a ScTypeDB_full.xlsx database file. NULL (default) uses the copy bundled in inst/extdata/ScTypeDB_full.xlsx; if that is missing it is downloaded once from the scType GitHub and cached at tools::R_user_dir("scSidekick", "cache").

run_singler

Logical. Run SingleR cluster-level annotation? Requires SingleR, scuttle, celldex, SingleCellExperiment. Default TRUE.

singler_ref

A reference SummarizedExperiment for SingleR::SingleR(), or NULL to use celldex::BlueprintEncodeData() (default). Choose based on tissue type and species:

Human references:
celldex::BlueprintEncodeData(): Blueprint/ENCODE bulk RNA-seq. Broad cell types; good general-purpose starting point. Default.
celldex::HumanPrimaryCellAtlasData(): Human Primary Cell Atlas. Very broad coverage across many tissues; best for highly heterogeneous datasets with diverse cell populations.
celldex::MonacoImmuneData(): Monaco et al. Finest immune subtype resolution (29 populations). Best for PBMCs, spleen, or any immune-focused study.
celldex::DatabaseImmuneCellExpressionData(): DICE database. Good alternative immune reference with activated/resting states.
celldex::NovershternHematopoieticData(): Hematopoietic lineages. Best for bone marrow or stem-cell datasets.
Mouse references:
celldex::ImmGenData(): ImmGen consortium. The most comprehensive mouse immune cell reference (over 250 subtypes).
celldex::MouseRNAseqData(): Broad mouse tissue types from bulk RNA-seq. Good for non-immune mouse tissues.

All celldex references are downloaded once and cached by BiocFileCache; subsequent calls are instant.

singler_col

Character. Name for the new metadata column storing numbered SingleR labels (e.g. "01.CD8+ T cells"). Default "SingleRAssignment".

markers_csv

Character or NULL. Path to a canonical-marker CSV. NULL uses the CSV bundled with scSidekick (inst/extdata/Markers.csv). Required columns: Type, Cell types, plus Human and/or Mouse gene symbol columns. The bundled CSV covers brain and immune markers (see marker_groups for the full list of Type values).

marker_groups

Named list controlling how many dotplots are produced and which Type values from the markers CSV appear in each. One SplitDotPlot() is generated per list entry. NULL produces a single dotplot with all markers combined.

Type values in the bundled Markers.csv:

"Brain Stroma" - Astrocytes, Oligodendrocytes, OPC, Microglia, Endothelial, Pericytes, Neurons (excitatory, inhibitory, dopaminergic, glutamatergic, serotonergic), VLMC, and stem/progenitor types
"Lymphocytes" - T cells (naive, cytotoxic, Th1/2/17, Treg, exhausted, MAIT, GDT), B cells, NK cells
"Monocytes" - CD14/CD16 monocytes, MDSCs
"Macrophages" - tissue macrophages
"Dendritic cells" - cDC1, cDC2, pDCs, LAMP3+ DCs
"Granulocytes" - neutrophils, basophils, mast cells
"Bone Marrow Derived" - BMD immune cells
"All" - proliferating cells (Prol)
"Tumor" - generic tumor marker

Example for brain snRNAseq with separate immune panel:

marker_groups = list(
  "Brain"  = "Brain Stroma",
  "Immune" = c("Lymphocytes", "Monocytes", "Macrophages",
               "Dendritic cells", "Granulocytes",
               "Bone Marrow Derived", "All")
)

top_n_per_cluster

Integer. Number of top DE genes per cluster shown in the cluster-faceted dotplot (uses the markers data frame). Default 3.

extra_dimplot_cols

Character vector of additional metadata columns to include as panels in the multi-UMAP summary figure (e.g. "Subclass" for SEAAD reference labels or "Donor.ID" for QC). Colors are auto-generated from Nour_pal() unless supplied via extra_col_colors.

extra_col_colors

Named list of color vectors for extra_dimplot_cols. Names must match extra_dimplot_cols. Example: list(Subclass = subclass_colors).

col.min

Numeric. Minimum scaled expression value for dotplot color scale. Default 0.

col.max

Numeric. Maximum scaled expression value for dotplot color scale. Default 2.

scale.min

Numeric. Minimum percentage of expressing cells for the dotplot size scale. Default 0.

scale.max

Numeric. Maximum percentage of expressing cells for the dotplot size scale. Default 100.

caffeinate

Logical. If TRUE, prevent macOS system sleep for the duration of the function call using caffeinate. Default FALSE.

Value

The modified Seurat object (returned invisibly), with:

New metadata columns: scType_CellType, rcellmarker_CellType, and/or the column named by singler_col, depending on which methods ran.
seurat_object@misc$annotation_colors: Named list of color vectors for each annotation column: rcellmarker, sctype, singler, plus any extra_dimplot_cols colors. Retrieve with seurat_object@misc$annotation_colors$sctype etc.

Automated cell-type annotation with rcellmarker, scType, and SingleR

Usage

Arguments

Value

rcellmarker

scType

SingleR

Dotplots

UMAP panels

Dotplot scale

System