# Gene signature scoring with UCell

Massimo Andreatta1 and Santiago J. Carmona1

1Ludwig Institute for Cancer Research, Lausanne Branch, and Department of Oncology, CHUV and University of Lausanne, Epalinges 1066, Switzerland; and Swiss Institute of Bioinformatics, Lausanne, Switzerland

#### 16 April 2025

#### Package

UCell 2.12.0

# 1 Introduction

In single-cell RNA-seq analysis, gene signature (or “module”) scoring constitutes a simple yet powerful approach to evaluate the strength of biological signals, typically associated to a specific cell type or biological process, in a transcriptome.

UCell is an R package for evaluating gene signatures in single-cell datasets. UCell signature scores, based on the Mann-Whitney U statistic, are robust to dataset size and heterogeneity, and their calculation demands less computing time and memory than other available methods, enabling the processing of large datasets in a few minutes even on machines with limited computing power. UCell can be applied to any single-cell data matrix, and includes functions to directly interact with Seurat objects.

# 2 Quick start

To test your installation, load a small sample dataset and run UCell:

    library(UCell)

    data(sample.matrix)
    gene.sets <- list(Tcell_signature = c("CD2","CD3E","CD3D"),
                      Myeloid_signature = c("SPI1","FCER1G","CSF1R"))

    scores <- ScoreSignatures_UCell(sample.matrix, features=gene.sets)

    ## Warning in BiocParallel::MulticoreParam(workers = ncores): MulticoreParam() not
    ## supported on Windows, use SnowParam()

    head(scores)

    ##                       Tcell_signature_UCell Myeloid_signature_UCell
    ## L5_ATTTCTGAGGTCGTGA               0.8991989                       0
    ## L4_TCACTATTCATCTCTA               0.6900312                       0
    ## L1_TCCTTCTTCTTTACAC               0.5932354                       0
    ## L5_AAAGTGAAGGCGCTCT               0.6090343                       0
    ## E2L3_CCTCAGTAGTGCAGGT             0.8506898                       0
    ## L5_CCCTCTCGTTCTAAGC               0.6557632                       0

# 3 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)))

# 4 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-")
    )

# 5 Run UCell

Run `ScoreSignatures_UCell` and get directly signature scores for all cells

    u.scores <- ScoreSignatures_UCell(exp.mat,features=signatures)

    ## Warning in BiocParallel::MulticoreParam(workers = ncores): MulticoreParam() not
    ## supported on Windows, use SnowParam()

    head(u.scores)

    ##         Tcell_UCell Myeloid_UCell NK_UCell Plasma_cell_UCell
    ## bcHTNA1           0     0.5227121        0        0.00000000
    ## bcHNVA2           0     0.5112892        0        0.00000000
    ## bcALZN3           0     0.3584502        0        0.07540874
    ## bcFWBP4           0     0.1546426        0        0.00000000
    ## bcBJYE5           0     0.4629927        0        0.00000000
    ## bcGSBJ6           0     0.5452238        0        0.00000000

Show the distribution of predicted scores

    library(reshape2)
    library(ggplot2)
    melted <- reshape2::melt(u.scores)
    colnames(melted) <- c("Cell","Signature","UCell_score")
    p <- ggplot(melted, aes(x=Signature, y=UCell_score)) +
        geom_violin(aes(fill=Signature), scale = "width") +
        geom_boxplot(width=0.1, outlier.size=0) +
        theme_bw() + theme(axis.text.x=element_blank())
    p

# 6 Pre-calculating gene rankings

The time- and memory-demanding step in UCell is the calculation of gene rankings for each individual cell. If we plan to experiment with signatures, editing them or adding new cell subtypes, it is possible to pre-calculate the gene rankings once and for all and then apply new signatures over these pre-calculated ranks. Run the `StoreRankings_UCell` function to pre-calculate gene rankings over a dataset:

    set.seed(123)
    ranks <- StoreRankings_UCell(exp.mat)

    ## Warning in BiocParallel::MulticoreParam(workers = ncores): MulticoreParam() not
    ## supported on Windows, use SnowParam()

    ranks[1:5,1:5]

    ## 5 x 5 sparse Matrix of class "dgCMatrix"
    ##           bcHTNA1 bcHNVA2 bcALZN3 bcFWBP4 bcBJYE5
    ## 5S_rRNA         .       .       .       .       .
    ## 5_8S_rRNA       .       .       .       .       .
    ## 7SK             .       .       .       .       .
    ## A1BG            .       .       .       .       .
    ## A1BG-AS1        .       .       .       .       .

Then, we can apply our signature set, or any other new signature to the pre-calculated ranks. The calculations will be considerably faster.

    set.seed(123)
    u.scores.2 <- ScoreSignatures_UCell(features=signatures,
                                        precalc.ranks = ranks)

    ## Warning in BiocParallel::MulticoreParam(workers = ncores): MulticoreParam() not
    ## supported on Windows, use SnowParam()

    melted <- reshape2::melt(u.scores.2)
    colnames(melted) <- c("Cell","Signature","UCell_score")
    p <- ggplot(melted, aes(x=Signature, y=UCell_score)) +
        geom_violin(aes(fill=Signature), scale = "width") +
        geom_boxplot(width=0.1, outlier.size = 0) +
        theme_bw() + theme(axis.text.x=element_blank())
    p

    new.signatures <- list(Mast.cell = c("TPSAB1","TPSB2","CPA3","MS4A2"),
                           Lymphoid = c("LCK"))

    u.scores.3 <- ScoreSignatures_UCell(features=new.signatures,
                                        precalc.ranks = ranks)

    ## Warning in BiocParallel::MulticoreParam(workers = ncores): MulticoreParam() not
    ## supported on Windows, use SnowParam()

    melted <- reshape2::melt(u.scores.3)
    colnames(melted) <- c("Cell","Signature","UCell_score")
    p <- ggplot(melted, aes(x=Signature, y=UCell_score)) +
        geom_violin(aes(fill=Signature), scale = "width") +
        geom_boxplot(width=0.1, outlier.size=0) +
        theme_bw() + theme(axis.text.x=element_blank())
    p

# 7 Multi-core processing

If your machine has multi-core capabilities and enough RAM, running UCell in parallel can speed up considerably your analysis. The example below runs on a single core - you may modify this behavior by setting e.g. `workers=4` to parallelize to 4 cores:

    BPPARAM <- BiocParallel::MulticoreParam(workers=1)

    ## Warning in BiocParallel::MulticoreParam(workers = 1): MulticoreParam() not
    ## supported on Windows, use SnowParam()

    u.scores <- ScoreSignatures_UCell(exp.mat,features=signatures,
                                      BPPARAM=BPPARAM)

# 8 Interacting with SingleCellExperiment or Seurat

SingleCellExperiment and Seurat are popular environments for single-cell analysis. The UCell package implements functions to interact directly with these pipelines, as described in dedicated demos available on the Bioc landing page.

# 9 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.

# 10 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

# A Session Info

    sessionInfo()

    ## R version 4.5.0 RC (2025-04-04 r88126 ucrt)
    ## Platform: x86_64-w64-mingw32/x64
    ## Running under: Windows Server 2022 x64 (build 20348)
    ##
    ## Matrix products: default
    ##   LAPACK version 3.12.1
    ##
    ## locale:
    ## [1] LC_COLLATE=C
    ## [2] LC_CTYPE=English_United States.utf8
    ## [3] LC_MONETARY=English_United States.utf8
    ## [4] LC_NUMERIC=C
    ## [5] LC_TIME=English_United States.utf8
    ##
    ## time zone: America/New_York
    ## tzcode source: internal
    ##
    ## attached base packages:
    ## [1] stats4    stats     graphics  grDevices utils     datasets  methods
    ## [8] base
    ##
    ## other attached packages:
    ##  [1] reshape2_1.4.4              scater_1.36.0
    ##  [3] scuttle_1.18.0              patchwork_1.3.0
    ##  [5] ggplot2_3.5.2               Seurat_5.2.1
    ##  [7] SeuratObject_5.0.2          sp_2.2-0
    ##  [9] UCell_2.12.0                scRNAseq_2.21.1
    ## [11] SingleCellExperiment_1.30.0 SummarizedExperiment_1.38.0
    ## [13] Biobase_2.68.0              GenomicRanges_1.60.0
    ## [15] GenomeInfoDb_1.44.0         IRanges_2.42.0
    ## [17] S4Vectors_0.46.0            BiocGenerics_0.54.0
    ## [19] generics_0.1.3              MatrixGenerics_1.20.0
    ## [21] matrixStats_1.5.0           BiocStyle_2.36.0
    ##
    ## loaded via a namespace (and not attached):
    ##   [1] ProtGenerics_1.40.0      spatstat.sparse_3.1-0    bitops_1.0-9
    ##   [4] httr_1.4.7               RColorBrewer_1.1-3       tools_4.5.0
    ##   [7] sctransform_0.4.1        alabaster.base_1.8.0     R6_2.6.1
    ##  [10] HDF5Array_1.36.0         lazyeval_0.2.2           uwot_0.2.3
    ##  [13] rhdf5filters_1.20.0      withr_3.0.2              gridExtra_2.3
    ##  [16] progressr_0.15.1         cli_3.6.4                spatstat.explore_3.4-2
    ##  [19] fastDummies_1.7.5        alabaster.se_1.8.0       labeling_0.4.3
    ##  [22] sass_0.4.10              spatstat.data_3.1-6      ggridges_0.5.6
    ##  [25] pbapply_1.7-2            Rsamtools_2.24.0         parallelly_1.43.0
    ##  [28] RSQLite_2.3.9            BiocIO_1.18.0            ica_1.0-3
    ##  [31] spatstat.random_3.3-3    dplyr_1.1.4              Matrix_1.7-3
    ##  [34] ggbeeswarm_0.7.2         abind_1.4-8              lifecycle_1.0.4
    ##  [37] yaml_2.3.10              rhdf5_2.52.0             SparseArray_1.8.0
    ##  [40] BiocFileCache_2.16.0     Rtsne_0.17               grid_4.5.0
    ##  [43] blob_1.2.4               promises_1.3.2           ExperimentHub_2.16.0
    ##  [46] crayon_1.5.3             miniUI_0.1.1.1           lattice_0.22-7
    ##  [49] beachmat_2.24.0          cowplot_1.1.3            GenomicFeatures_1.60.0
    ##  [52] KEGGREST_1.48.0          magick_2.8.6             pillar_1.10.2
    ##  [55] knitr_1.50               rjson_0.2.23             future.apply_1.11.3
    ##  [58] codetools_0.2-20         glue_1.8.0               spatstat.univar_3.1-2
    ##  [61] data.table_1.17.0        vctrs_0.6.5              png_0.1-8
    ##  [64] gypsum_1.4.0             spam_2.11-1              gtable_0.3.6
    ##  [67] cachem_1.1.0             xfun_0.52                S4Arrays_1.8.0
    ##  [70] mime_0.13                survival_3.8-3           tinytex_0.57
    ##  [73] fitdistrplus_1.2-2       ROCR_1.0-11              nlme_3.1-168
    ##  [76] bit64_4.6.0-1            alabaster.ranges_1.8.0   filelock_1.0.3
    ##  [79] RcppAnnoy_0.0.22         bslib_0.9.0              irlba_2.3.5.1
    ##  [82] vipor_0.4.7              KernSmooth_2.23-26       colorspace_2.1-1
    ##  [85] DBI_1.2.3                tidyselect_1.2.1         bit_4.6.0
    ##  [88] compiler_4.5.0           curl_6.2.2               httr2_1.1.2
    ##  [91] BiocNeighbors_2.2.0      h5mread_1.0.0            DelayedArray_0.34.0
    ##  [94] plotly_4.10.4            bookdown_0.43            rtracklayer_1.68.0
    ##  [97] scales_1.3.0             lmtest_0.9-40            rappdirs_0.3.3
    ## [100] stringr_1.5.1            digest_0.6.37            goftest_1.2-3
    ## [103] spatstat.utils_3.1-3     alabaster.matrix_1.8.0   rmarkdown_2.29
    ## [106] XVector_0.48.0           htmltools_0.5.8.1        pkgconfig_2.0.3
    ## [109] dbplyr_2.5.0             fastmap_1.2.0            ensembldb_2.32.0
    ## [112] rlang_1.1.6              htmlwidgets_1.6.4        UCSC.utils_1.4.0
    ## [115] shiny_1.10.0             farver_2.1.2             jquerylib_0.1.4
    ## [118] zoo_1.8-14               jsonlite_2.0.0           BiocParallel_1.42.0
    ## [121] BiocSingular_1.24.0      RCurl_1.98-1.17          magrittr_2.0.3
    ## [124] GenomeInfoDbData_1.2.14  dotCall64_1.2            Rhdf5lib_1.30.0
    ## [127] munsell_0.5.1            Rcpp_1.0.14              viridis_0.6.5
    ## [130] reticulate_1.42.0        stringi_1.8.7            alabaster.schemas_1.8.0
    ## [133] MASS_7.3-65              AnnotationHub_3.16.0     plyr_1.8.9
    ## [136] parallel_4.5.0           listenv_0.9.1            ggrepel_0.9.6
    ## [139] deldir_2.0-4             Biostrings_2.76.0        splines_4.5.0
    ## [142] tensor_1.5               igraph_2.1.4             spatstat.geom_3.3-6
    ## [145] RcppHNSW_0.6.0           ScaledMatrix_1.16.0      BiocVersion_3.21.1
    ## [148] XML_3.99-0.18            evaluate_1.0.3           BiocManager_1.30.25
    ## [151] httpuv_1.6.15            RANN_2.6.2               tidyr_1.3.1
    ## [154] purrr_1.0.4              polyclip_1.10-7          future_1.40.0
    ## [157] scattermore_1.2          alabaster.sce_1.8.0      rsvd_1.0.5
    ## [160] xtable_1.8-4             restfulr_0.0.15          AnnotationFilter_1.32.0
    ## [163] RSpectra_0.16-2          later_1.4.2              viridisLite_0.4.2
    ## [166] tibble_3.2.1             beeswarm_0.4.0           memoise_2.0.1
    ## [169] AnnotationDbi_1.70.0     GenomicAlignments_1.44.0 cluster_2.1.8.1
    ## [172] globals_0.16.3