# Using UCell with SingleCellExperiment

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

SingleCellExperiment is Bioconductor’s data structure of choice for storing single-cell experiment data. The function `ScoreSignatures_UCell()` allows performing signature scoring with UCell directly on `sce` objects. UCell scores are returned in a altExp object: `altExp(sce, 'UCell')`

# 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 sce object

    library(UCell)
    library(SingleCellExperiment)

    sce <- SingleCellExperiment(list(counts=exp.mat))
    sce <- ScoreSignatures_UCell(sce, features=signatures,
                                     assay = 'counts', name=NULL)
    altExp(sce, 'UCell')

    ## class: SummarizedExperiment
    ## dim: 4 5000
    ## metadata(0):
    ## assays(1): UCell
    ## rownames(4): Tcell Myeloid NK Plasma_cell
    ## rowData names(0):
    ## colnames(5000): bcHTNA1 bcHNVA2 ... bcGVZB4999 bcHGKL5000
    ## colData names(0):

Dimensionality reduction and visualization

    library(scater)
    library(patchwork)
    #PCA
    sce <- logNormCounts(sce)
    sce <- runPCA(sce, scale=TRUE, ncomponents=10)

    #UMAP
    set.seed(1234)
    sce <- runUMAP(sce, dimred="PCA")

Visualize UCell scores on low-dimensional representation (UMAP)

    pll <- lapply(names(signatures), function(x) {
        plotUMAP(sce, colour_by = x, by_exprs_values = "UCell",
                 point_size=0.2) + theme(aspect.ratio = 1)
    })

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    wrap_plots(pll)

# 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 SingleCellExperiment objects to smooth UCell scores:

    sce <- SmoothKNN(sce, signature.names = names(signatures), reduction="PCA")

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    a <- plotUMAP(sce, colour_by="Myeloid", by_exprs_values="UCell",
             point_size=0.2) + ggtitle("UCell") + theme(aspect.ratio = 1)

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    b <- plotUMAP(sce, colour_by="Myeloid_kNN", by_exprs_values="UCell_kNN",
             point_size=0.2) + ggtitle("Smoothed UCell") + theme(aspect.ratio = 1)

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'
    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    ## Found more than one class "package_version" in cache; using the first, from namespace 'alabaster.base'

    ## Also defined by 'SeuratObject'

    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
- Amezquita, Robert A., et al. (2020) “Orchestrating single-cell analysis with Bioconductor.” Nature methods

# 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] scater_1.36.0               scuttle_1.18.0
    ##  [3] patchwork_1.3.0             ggplot2_3.5.2
    ##  [5] Seurat_5.2.1                SeuratObject_5.0.2
    ##  [7] sp_2.2-0                    UCell_2.12.0
    ##  [9] scRNAseq_2.21.1             SingleCellExperiment_1.30.0
    ## [11] SummarizedExperiment_1.38.0 Biobase_2.68.0
    ## [13] GenomicRanges_1.60.0        GenomeInfoDb_1.44.0
    ## [15] IRanges_2.42.0              S4Vectors_0.46.0
    ## [17] BiocGenerics_0.54.0         generics_0.1.3
    ## [19] MatrixGenerics_1.20.0       matrixStats_1.5.0
    ## [21] 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           reshape2_1.4.4           ScaledMatrix_1.16.0
    ## [148] BiocVersion_3.21.1       XML_3.99-0.18            evaluate_1.0.3
    ## [151] BiocManager_1.30.25      httpuv_1.6.15            RANN_2.6.2
    ## [154] tidyr_1.3.1              purrr_1.0.4              polyclip_1.10-7
    ## [157] future_1.40.0            scattermore_1.2          alabaster.sce_1.8.0
    ## [160] rsvd_1.0.5               xtable_1.8-4             restfulr_0.0.15
    ## [163] AnnotationFilter_1.32.0  RSpectra_0.16-2          later_1.4.2
    ## [166] viridisLite_0.4.2        tibble_3.2.1             beeswarm_0.4.0
    ## [169] memoise_2.0.1            AnnotationDbi_1.70.0     GenomicAlignments_1.44.0
    ## [172] cluster_2.1.8.1          globals_0.16.3