Using UCell with Seurat
15 April 2025
Package
UCell 2.12.0
1 Introduction
The function AddModuleScore_UCell() allows operating directly on Seurat objects. UCell scores are calculated from raw counts or normalized data, and returned as metadata columns. The example below defines some simple signatures, and applies them on single-cell data stored in a Seurat object.
To see how this function differs from Seurat’s own AddModuleScore() (not based on per-cell ranks) see this vignette.
2 Get some testing data
For this demo, we will download a single-cell dataset of lung cancer (Zilionis et al. (2019) Immunity) through the scRNA-seq package. This dataset contains >170,000 single cells; for the sake of simplicity, in this demo will we focus on immune cells, according to the annotations by the authors, and downsample to 5000 cells.
library(scRNAseq)
lung <- ZilionisLungData()
immune <- lung$Used & lung$used_in_NSCLC_immune
lung <- lung[,immune]
lung <- lung[,1:5000]
exp.mat <- Matrix::Matrix(counts(lung),sparse = TRUE)
colnames(exp.mat) <- paste0(colnames(exp.mat), seq(1,ncol(exp.mat)))3 Define gene signatures
Here we define some simple gene sets based on the “Human Cell Landscape” signatures Han et al. (2020) Nature. You may edit existing signatures, or add new one as elements in a list.
signatures <- list(
Tcell = c("CD3D","CD3E","CD3G","CD2","TRAC"),
Myeloid = c("CD14","LYZ","CSF1R","FCER1G","SPI1","LCK-"),
NK = c("KLRD1","NCR1","NKG7","CD3D-","CD3E-"),
Plasma_cell = c("MZB1","DERL3","CD19-")
)4 Run UCell on Seurat object
library(UCell)
library(Seurat)
seurat.object <- CreateSeuratObject(counts = exp.mat,
project = "Zilionis_immune")
seurat.object <- AddModuleScore_UCell(seurat.object,
features=signatures, name=NULL)
head(seurat.object[[]])## orig.ident nCount_RNA nFeature_RNA Tcell Myeloid NK Plasma_cell
## bcHTNA1 Zilionis_immune 7516 2613 0 0.5227121 0 0.00000000
## bcHNVA2 Zilionis_immune 5684 1981 0 0.5112892 0 0.00000000
## bcALZN3 Zilionis_immune 4558 1867 0 0.3584502 0 0.07540874
## bcFWBP4 Zilionis_immune 2915 1308 0 0.1546426 0 0.00000000
## bcBJYE5 Zilionis_immune 3576 1548 0 0.4629927 0 0.00000000
## bcGSBJ6 Zilionis_immune 2796 1270 0 0.5452238 0 0.00000000Generate PCA and UMAP embeddings
seurat.object <- NormalizeData(seurat.object)
seurat.object <- FindVariableFeatures(seurat.object,
selection.method = "vst", nfeatures = 500)
seurat.object <- ScaleData(seurat.object)
seurat.object <- RunPCA(seurat.object, npcs = 20,
features=VariableFeatures(seurat.object))
seurat.object <- RunUMAP(seurat.object, reduction = "pca",
dims = 1:20, seed.use=123)Visualize UCell scores on low-dimensional representation (UMAP)
library(ggplot2)
library(patchwork)
FeaturePlot(seurat.object, reduction = "umap", features = names(signatures))
5 Signature smoothing
Single-cell data are sparse. It can be useful to ‘impute’ scores by neighboring cells and partially correct this sparsity. The function SmoothKNN performs smoothing of single-cell scores by weighted average of the k-nearest neighbors in a given dimensionality reduction. It can be applied directly on Seurat objects to smooth UCell scores:
seurat.object <- SmoothKNN(seurat.object,
signature.names = names(signatures),
reduction="pca")FeaturePlot(seurat.object, reduction = "umap", features = c("NK","NK_kNN"))
Smoothing (or imputation) has been designed for UCell scores, but it can be applied to any other data or metadata. For instance, we can perform knn-smoothing directly on gene expression measurements:
genes <- c("CD2","CSF1R")
seurat.object <- SmoothKNN(seurat.object, signature.names=genes,
assay="RNA", reduction="pca", k=20, suffix = "_smooth")
DefaultAssay(seurat.object) <- "RNA"
a <- FeaturePlot(seurat.object, reduction = "umap", features = genes)
DefaultAssay(seurat.object) <- "RNA_smooth"
b <- FeaturePlot(seurat.object, reduction = "umap", features = genes)
a / b
6 Resources
Please report any issues at the UCell GitHub repository.
More demos available on the Bioc landing page and at the UCell demo repository.
If you find UCell useful, you may also check out the scGate package, which relies on UCell scores to automatically purify populations of interest based on gene signatures.
See also SignatuR for easy storing and retrieval of gene signatures.
7 References
Appendix
- Andreatta, M., Carmona, S. J. (2021) UCell: Robust and scalable single-cell gene signature scoring Computational and Structural Biotechnology Journal
- Zilionis, R., Engblom, C., …, Klein, A. M. (2019) Single-Cell Transcriptomics of Human and Mouse Lung Cancers Reveals Conserved Myeloid Populations across Individuals and Species Immunity
- Hao, Yuhan, et al. (2021) Integrated analysis of multimodal single-cell data Cell
A Session Info
sessionInfo()## R version 4.5.0 RC (2025-04-04 r88126)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.04.2 LTS
##
## Matrix products: default
## BLAS: /home/biocbuild/bbs-3.21-bioc/R/lib/libRblas.so
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0 LAPACK version 3.12.0
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_GB LC_COLLATE=C
## [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: America/New_York
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats4 stats graphics grDevices utils datasets methods
## [8] base
##
## other attached packages:
## [1] patchwork_1.3.0 ggplot2_3.5.2
## [3] Seurat_5.2.1 SeuratObject_5.0.2
## [5] sp_2.2-0 UCell_2.12.0
## [7] scRNAseq_2.21.1 SingleCellExperiment_1.30.0
## [9] SummarizedExperiment_1.38.0 Biobase_2.68.0
## [11] GenomicRanges_1.60.0 GenomeInfoDb_1.44.0
## [13] IRanges_2.42.0 S4Vectors_0.46.0
## [15] BiocGenerics_0.54.0 generics_0.1.3
## [17] MatrixGenerics_1.20.0 matrixStats_1.5.0
## [19] BiocStyle_2.36.0
##
## loaded via a namespace (and not attached):
## [1] RcppAnnoy_0.0.22 splines_4.5.0 later_1.4.2
## [4] BiocIO_1.18.0 bitops_1.0-9 filelock_1.0.3
## [7] tibble_3.2.1 polyclip_1.10-7 XML_3.99-0.18
## [10] fastDummies_1.7.5 lifecycle_1.0.4 httr2_1.1.2
## [13] globals_0.16.3 lattice_0.22-7 ensembldb_2.32.0
## [16] MASS_7.3-65 alabaster.base_1.8.0 magrittr_2.0.3
## [19] plotly_4.10.4 sass_0.4.10 rmarkdown_2.29
## [22] jquerylib_0.1.4 yaml_2.3.10 httpuv_1.6.15
## [25] sctransform_0.4.1 spam_2.11-1 spatstat.sparse_3.1-0
## [28] reticulate_1.42.0 pbapply_1.7-2 cowplot_1.1.3
## [31] DBI_1.2.3 RColorBrewer_1.1-3 abind_1.4-8
## [34] Rtsne_0.17 purrr_1.0.4 AnnotationFilter_1.32.0
## [37] RCurl_1.98-1.17 rappdirs_0.3.3 GenomeInfoDbData_1.2.14
## [40] ggrepel_0.9.6 irlba_2.3.5.1 spatstat.utils_3.1-3
## [43] listenv_0.9.1 alabaster.sce_1.8.0 goftest_1.2-3
## [46] RSpectra_0.16-2 spatstat.random_3.3-3 fitdistrplus_1.2-2
## [49] parallelly_1.43.0 codetools_0.2-20 DelayedArray_0.34.0
## [52] tidyselect_1.2.1 farver_2.1.2 UCSC.utils_1.4.0
## [55] spatstat.explore_3.4-2 BiocFileCache_2.16.0 GenomicAlignments_1.44.0
## [58] jsonlite_2.0.0 BiocNeighbors_2.2.0 progressr_0.15.1
## [61] ggridges_0.5.6 survival_3.8-3 tools_4.5.0
## [64] ica_1.0-3 Rcpp_1.0.14 glue_1.8.0
## [67] gridExtra_2.3 SparseArray_1.8.0 xfun_0.52
## [70] dplyr_1.1.4 HDF5Array_1.36.0 gypsum_1.4.0
## [73] withr_3.0.2 BiocManager_1.30.25 fastmap_1.2.0
## [76] rhdf5filters_1.20.0 digest_0.6.37 R6_2.6.1
## [79] mime_0.13 colorspace_2.1-1 scattermore_1.2
## [82] tensor_1.5 spatstat.data_3.1-6 RSQLite_2.3.9
## [85] h5mread_1.0.0 tidyr_1.3.1 data.table_1.17.0
## [88] rtracklayer_1.68.0 htmlwidgets_1.6.4 httr_1.4.7
## [91] S4Arrays_1.8.0 uwot_0.2.3 pkgconfig_2.0.3
## [94] gtable_0.3.6 blob_1.2.4 lmtest_0.9-40
## [97] XVector_0.48.0 htmltools_0.5.8.1 dotCall64_1.2
## [100] bookdown_0.43 ProtGenerics_1.40.0 scales_1.3.0
## [103] alabaster.matrix_1.8.0 png_0.1-8 spatstat.univar_3.1-2
## [106] knitr_1.50 reshape2_1.4.4 rjson_0.2.23
## [109] nlme_3.1-168 curl_6.2.2 cachem_1.1.0
## [112] zoo_1.8-14 rhdf5_2.52.0 stringr_1.5.1
## [115] BiocVersion_3.21.1 KernSmooth_2.23-26 parallel_4.5.0
## [118] miniUI_0.1.1.1 AnnotationDbi_1.70.0 restfulr_0.0.15
## [121] pillar_1.10.2 grid_4.5.0 alabaster.schemas_1.8.0
## [124] vctrs_0.6.5 RANN_2.6.2 promises_1.3.2
## [127] dbplyr_2.5.0 xtable_1.8-4 cluster_2.1.8.1
## [130] evaluate_1.0.3 magick_2.8.6 tinytex_0.57
## [133] GenomicFeatures_1.60.0 cli_3.6.4 compiler_4.5.0
## [136] Rsamtools_2.24.0 rlang_1.1.6 crayon_1.5.3
## [139] future.apply_1.11.3 labeling_0.4.3 plyr_1.8.9
## [142] stringi_1.8.7 deldir_2.0-4 viridisLite_0.4.2
## [145] alabaster.se_1.8.0 BiocParallel_1.42.0 munsell_0.5.1
## [148] Biostrings_2.76.0 lazyeval_0.2.2 spatstat.geom_3.3-6
## [151] Matrix_1.7-3 ExperimentHub_2.16.0 RcppHNSW_0.6.0
## [154] bit64_4.6.0-1 future_1.40.0 Rhdf5lib_1.30.0
## [157] KEGGREST_1.48.0 shiny_1.10.0 alabaster.ranges_1.8.0
## [160] AnnotationHub_3.16.0 ROCR_1.0-11 igraph_2.1.4
## [163] memoise_2.0.1 bslib_0.9.0 bit_4.6.0