Quick Start Guide

Introduction

scGate is a powerful R package for marker-based purification of cell types from heterogeneous single-cell RNA-seq datasets. Unlike reference-based methods, scGate does not require training data or reference gene expression profiles.

Key Features

Marker-based gating: Define cell populations using positive and negative markers
Hierarchical models: Build complex gating strategies similar to flow cytometry
Multi-class classification: Annotate multiple cell types simultaneously
Cross-platform: Works on Windows, macOS, and Linux
Integration-friendly: Compatible with Seurat v4/v5 and batch-corrected data

Installation

# From CRAN (stable version)
install.packages("scGate")

# From GitHub (development version)
# remotes::install_github("Zaoqu-Liu/scGate")

Quick Example

Load Required Packages

library(scGate)
library(Seurat)
library(ggplot2)

Load Example Data

scGate provides a small example dataset for testing:

# Load the built-in example dataset
data(query.seurat)

# Check the data
query.seurat
#> An object of class Seurat 
#> 20388 features across 300 samples within 1 assay 
#> Active assay: RNA (20388 features, 492 variable features)
#>  1 layer present: data
#>  2 dimensional reductions calculated: pca, umap

Create a Simple Gating Model

The simplest way to use scGate is with a single marker:

# Create a model for B cells using MS4A1 (CD20) as marker
bcell_model <- gating_model(name = "Bcell", signature = c("MS4A1"))

# View the model structure
bcell_model
#>   levels   use_as  name signature
#> 1 level1 positive Bcell     MS4A1

Apply scGate

# Apply the gating model
# Using pre-computed PCA for speed
query.seurat <- scGate(
  data = query.seurat, 
  model = bcell_model,
  reduction = "pca"  # Use existing PCA
)

# Check results
table(query.seurat$is.pure)

Visualize Results

# Create visualization
p1 <- DimPlot(query.seurat, group.by = "cell_type", label = TRUE, repel = TRUE) +
  ggtitle("Original Annotation") +
  NoLegend()

p2 <- DimPlot(query.seurat, group.by = "is.pure", 
              cols = c("Pure" = "#00ae60", "Impure" = "gray80")) +
  ggtitle("scGate Result")

p1 + p2

Building More Complex Models

Positive and Negative Markers

For more accurate gating, combine positive and negative markers:

# T cell model with positive (CD3) and negative (CD19) markers
tcell_model <- gating_model(name = "Tcell", signature = c("CD3D", "CD3E"))
tcell_model <- gating_model(
  model = tcell_model, 
  name = "notBcell", 
  signature = c("CD19", "MS4A1"),
  positive = FALSE  # These are negative markers
)

tcell_model
#>   levels   use_as     name  signature
#> 1 level1 positive    Tcell  CD3D;CD3E
#> 2 level1 negative notBcell CD19;MS4A1

Using Pre-defined Models

scGate provides a database of curated gating models:

# Download the model database
models_db <- get_scGateDB()

# Available models for human
names(models_db$human$generic)

# Use a pre-defined T cell model
tcell_model <- models_db$human$generic$Tcell

Multi-class Classification

scGate can annotate multiple cell types simultaneously:

# Define multiple models
model_list <- list(
  "Bcell" = gating_model(name = "Bcell", signature = c("MS4A1", "CD19")),
  "Tcell" = gating_model(name = "Tcell", signature = c("CD3D", "CD3E"))
)

# Apply all models at once
seurat_obj <- scGate(seurat_obj, model = model_list)

# Results are stored in scGate_multi column
table(seurat_obj$scGate_multi)

Key Parameters

Parameter	Description	Default
`pos.thr`	Threshold for positive signatures	0.2
`neg.thr`	Threshold for negative signatures	0.2
`reduction`	Dimensionality reduction to use	“calculate”
`k.param`	Number of neighbors for smoothing	30
`ncores`	Number of cores for parallel processing	1

Session Info

sessionInfo()
#> R version 4.6.0 (2026-04-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.4 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] patchwork_1.3.2    ggplot2_4.0.3      Seurat_5.5.0       SeuratObject_5.4.0
#> [5] sp_2.2-1           scGate_1.7.2       rmarkdown_2.31    
#> 
#> loaded via a namespace (and not attached):
#>   [1] deldir_2.0-4           pbapply_1.7-4          gridExtra_2.3         
#>   [4] rlang_1.2.0            magrittr_2.0.5         RcppAnnoy_0.0.23      
#>   [7] otel_0.2.0             spatstat.geom_3.8-1    matrixStats_1.5.0     
#>  [10] ggridges_0.5.7         compiler_4.6.0         png_0.1-9             
#>  [13] vctrs_0.7.3            reshape2_1.4.5         stringr_1.6.0         
#>  [16] pkgconfig_2.0.3        fastmap_1.2.0          promises_1.5.0        
#>  [19] purrr_1.2.2            xfun_0.57              cachem_1.1.0          
#>  [22] jsonlite_2.0.0         goftest_1.2-3          later_1.4.8           
#>  [25] BiocParallel_1.47.0    spatstat.utils_3.2-3   irlba_2.3.7           
#>  [28] parallel_4.6.0         cluster_2.1.8.2        R6_2.6.1              
#>  [31] ica_1.0-3              spatstat.data_3.1-9    bslib_0.11.0          
#>  [34] stringi_1.8.7          RColorBrewer_1.1-3     reticulate_1.46.0     
#>  [37] spatstat.univar_3.2-0  parallelly_1.47.0      lmtest_0.9-40         
#>  [40] jquerylib_0.1.4        scattermore_1.2        Rcpp_1.1.1-1.1        
#>  [43] knitr_1.51             tensor_1.5.1           future.apply_1.20.2   
#>  [46] zoo_1.8-15             sctransform_0.4.3      httpuv_1.6.17         
#>  [49] Matrix_1.7-5           splines_4.6.0          igraph_2.3.1          
#>  [52] tidyselect_1.2.1       abind_1.4-8            yaml_2.3.12           
#>  [55] spatstat.random_3.5-0  codetools_0.2-20       miniUI_0.1.2          
#>  [58] spatstat.explore_3.8-1 listenv_0.10.1         lattice_0.22-9        
#>  [61] tibble_3.3.1           plyr_1.8.9             withr_3.0.2           
#>  [64] shiny_1.13.0           S7_0.2.2               ROCR_1.0-12           
#>  [67] evaluate_1.0.5         Rtsne_0.17             future_1.70.0         
#>  [70] fastDummies_1.7.6      survival_3.8-6         polyclip_1.10-7       
#>  [73] fitdistrplus_1.2-6     pillar_1.11.1          KernSmooth_2.23-26    
#>  [76] plotly_4.12.0          generics_0.1.4         RcppHNSW_0.6.0        
#>  [79] scales_1.4.0           globals_0.19.1         xtable_1.8-8          
#>  [82] glue_1.8.1             lazyeval_0.2.3         maketools_1.3.2       
#>  [85] tools_4.6.0            BiocNeighbors_2.7.2    sys_3.4.3             
#>  [88] data.table_1.18.4      RSpectra_0.16-2        RANN_2.6.2            
#>  [91] buildtools_1.0.0       dotCall64_1.2          cowplot_1.2.0         
#>  [94] grid_4.6.0             tidyr_1.3.2            colorspace_2.1-2      
#>  [97] nlme_3.1-169           cli_3.6.6              spatstat.sparse_3.2-0 
#> [100] spam_2.11-3            viridisLite_0.4.3      dplyr_1.2.1           
#> [103] uwot_0.2.4             gtable_0.3.6           sass_0.4.10           
#> [106] digest_0.6.39          progressr_0.19.0       ggrepel_0.9.8         
#> [109] htmlwidgets_1.6.4      farver_2.1.2           htmltools_0.5.9       
#> [112] lifecycle_1.0.5        httr_1.4.8             mime_0.13             
#> [115] MASS_7.3-65