Contents

1 Introduction

1.1 About scTGIF

Here, we explain the concept of scTGIF. The analysis of single-cell RNA-Seq (scRNA-Seq) has a potential difficult problem; which data corresponds to what kind of cell type is not known a priori.

Therefore, at the start point of the data analysis of the scRNA-Seq dataset, each cell is “not colored” (unannotated) (Figure 1). There some approaches to support users to infer the cell types such as (1) Known marker gene expression, (2) BLAST-like gene expression comparison with reference DB, (3) differentially expressed genes (DEGs) and over-representative analysis (ORA) (scRNA-tools).

The first approach might be the most popular method, but this task is based on the expert knowledge about the cell types, and not always general-purpose. The second approach is easy and scalable, but still limited when the cell type is not known or still not measured by the other research organization. The third approach can perhaps be used in any situation but ambiguous and time-consuming task; this task is based on the cluster label and the true cluster structure, which is not known and some DEG methods have to be performed in each cluster, but recent scRNA-Seq dataset has tens to hundreds of cell types. Besides, a scRNA-Seq dataset can have low-quality cells and artifacts (e.g. doublet) but it is hard to distinguish from real cell data. Therefore, in actual data analytical situation, laborious trial-and-error cycle along with the change of cellular label cannot be evitable (Figure 1).

scTGIF is developed to reduce this trial-and-error cycle; This tool directly connects the unannotated cells and related gene function. Since this tool does not use reference DB, marker gene list, and cluster label can be used in any situation without expert knowledge and is not influenced by the change of cellular label.

Figure 1: Concept of scTGIF

Figure 1: Concept of scTGIF

In scTGIF, three data is required; the gene expression matrix, 2D coordinates of the cells (e.g. t-SNE, UMAP), and geneset of MSigDB. Firstly, the 2D coordinates are segmented as 50-by-50 grids, and gene expression is summarized in each grid level (X1). Next, the correspondence between genes and the related gene functions are summarized as gene-by-function matrix (X2). Here, we support only common genes are used in X1 and X2. Performing joint non-negative matrix factorization (jNMF) algorithm, which is implemented in nnTensor, the shared latent variables (W) with the two matrices are estimated.

Figure 2: Joint NMF

Figure 2: Joint NMF

By this algorithm, a grid set and corresponding gene functions are paired. Lower-dimension (D)-by-Grid matrix H1 works as attention maps to help users to pay attention the grids, and D-by-Function matrix H2 shows the gene function enriched in the grids.

Figure 3: H1 and H2 matrices

Figure 3: H1 and H2 matrices

scTGIF also supports some QC metrics to distinguish low-quality cells and artifacts from real cellular data.

2 Usage

2.0.1 Test data

To demonstrate the usage of scTGIF, we prepared a testdata of distal lung epithelium.

library("scTGIF")
library("SingleCellExperiment")
library("GSEABase")
library("msigdbr")

data("DistalLungEpithelium")
data("pca.DistalLungEpithelium")
data("label.DistalLungEpithelium")

Although this data is still annotated and the cell type label is provided, scTGIF does not rely on this information.

par(ask=FALSE)
plot(pca.DistalLungEpithelium, col=label.DistalLungEpithelium, pch=16,
    main="Distal lung epithelium dataset", xlab="PCA1", ylab="PCA2", bty="n")
text(0.1, 0.05, "AT1", col="#FF7F00", cex=2)
text(0.07, -0.15, "AT2", col="#E41A1C", cex=2)
text(0.13, -0.04, "BP", col="#A65628", cex=2)
text(0.125, -0.15, "Clara", col="#377EB8", cex=2)
text(0.09, -0.2, "Cilliated", col="#4DAF4A", cex=2)

To combine with the gene expression and the related gene function, we suppose the gene function data is summarized as the object of GSEABase. This data is directly downloadable from MSigDB and can be imported like gmt <- GSEABase::getGmt(“/YOURPATH/h.all.v6.0.entrez.gmt”)

Note that scTGIF only supports NCBI Gene IDs (Entrez IDs) for now. When the scRNA-Seq is not about human, the situation is more complicated. Here, we use msigdbr package to retrieve the mouse MSigDB genesets like below.

m_df = msigdbr(species = "Mus musculus",
    category = "H")[, c("gs_name", "entrez_gene")]

hallmark = unique(m_df$gs_name)
gsc <- lapply(hallmark, function(h){
    target = which(m_df$gs_name == h)
    geneIds = unique(as.character(m_df$entrez_gene[target]))
    GeneSet(setName=h, geneIds)
})
gmt = GeneSetCollection(gsc)
gmt = gmt[1:10] # Reduced for this demo

2.0.2 Parameter setting : settingTGIF

Next, the data matrix is converted to the object of SingleCellExperiment package, and the 2D coordinates are registered as the reducedDims slot.

sce <- SingleCellExperiment(assays = list(counts = DistalLungEpithelium))
reducedDims(sce) <- SimpleList(PCA=pca.DistalLungEpithelium)

Although the default mode of scTGIF use count slot as the input matrix, the normalized gene expression data can also be specified. In such a case, we recommend using normcounts slot to register the data.

CPMED <- function(input){
    libsize <- colSums(input)
    median(libsize) * t(t(input) / libsize)
}
normcounts(sce) <- log10(CPMED(counts(sce)) + 1)

After the registration of the data in sce, settingTGIF will work like below.

settingTGIF(sce, gmt, reducedDimNames="PCA", assayNames="normcounts")

2.0.4 HTML Report : reportTGIF

Finally, reportTGIF generates the HTML report to summarize the result of jNMF.

reportTGIF(sce,
    html.open=FALSE,
    title="scTGIF Report for DistalLungEpithelium dataset",
    author="Koki Tsuyuzaki")
## index.Rmd is created...
## index.Rmd is compiled to index.html...
## Loading required package: ggplot2
## 
## Attaching package: 'plotly'
## The following object is masked from 'package:ggplot2':
## 
##     last_plot
## The following object is masked from 'package:AnnotationDbi':
## 
##     select
## The following object is masked from 'package:IRanges':
## 
##     slice
## The following object is masked from 'package:S4Vectors':
## 
##     rename
## The following object is masked from 'package:stats':
## 
##     filter
## The following object is masked from 'package:graphics':
## 
##     layout
## Warning: textfont.color doesn't (yet) support data arrays

## Warning: textfont.color doesn't (yet) support data arrays

## Warning: textfont.color doesn't (yet) support data arrays

## Warning: textfont.color doesn't (yet) support data arrays

## Warning: textfont.color doesn't (yet) support data arrays

## Warning: textfont.color doesn't (yet) support data arrays
## ################################################
## Data files are saved in
## /tmp/RtmploHiKn
## ################################################

Since this function takes some time, please type example("reportTGIF") by your own environment.

Session information

## R version 4.2.1 (2022-06-23)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 20.04.5 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.16-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.16-bioc/R/lib/libRlapack.so
## 
## 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       
## 
## attached base packages:
## [1] stats4    stats     graphics  grDevices utils     datasets  methods  
## [8] base     
## 
## other attached packages:
##  [1] plotly_4.10.0               ggplot2_3.3.6              
##  [3] msigdbr_7.5.1               GSEABase_1.60.0            
##  [5] graph_1.76.0                annotate_1.76.0            
##  [7] XML_3.99-0.12               AnnotationDbi_1.60.0       
##  [9] SingleCellExperiment_1.20.0 SummarizedExperiment_1.28.0
## [11] Biobase_2.58.0              GenomicRanges_1.50.0       
## [13] GenomeInfoDb_1.34.0         IRanges_2.32.0             
## [15] S4Vectors_0.36.0            BiocGenerics_0.44.0        
## [17] MatrixGenerics_1.10.0       matrixStats_0.62.0         
## [19] scTGIF_1.12.0               BiocStyle_2.26.0           
## 
## loaded via a namespace (and not attached):
##   [1] utf8_1.2.2             tagcloud_0.6           reticulate_1.26       
##   [4] tidyselect_1.2.0       RSQLite_2.2.18         htmlwidgets_1.5.4     
##   [7] grid_4.2.1             Rtsne_0.16             munsell_0.5.0         
##  [10] ragg_1.2.4             codetools_0.2-18       ica_1.0-3             
##  [13] future_1.28.0          miniUI_0.1.1.1         misc3d_0.9-1          
##  [16] withr_2.5.0            spatstat.random_3.0-0  colorspace_2.0-3      
##  [19] schex_1.12.0           progressr_0.11.0       highr_0.9             
##  [22] knitr_1.40             Seurat_4.2.0           ROCR_1.0-11           
##  [25] tensor_1.5             listenv_0.8.0          labeling_0.4.2        
##  [28] GenomeInfoDbData_1.2.9 polyclip_1.10-4        bit64_4.0.5           
##  [31] farver_2.1.1           parallelly_1.32.1      vctrs_0.5.0           
##  [34] generics_0.1.3         xfun_0.34              R6_2.5.1              
##  [37] fields_14.1            concaveman_1.1.0       bitops_1.0-7          
##  [40] spatstat.utils_3.0-1   cachem_1.0.6           DelayedArray_0.24.0   
##  [43] assertthat_0.2.1       nnTensor_1.1.8         promises_1.2.0.1      
##  [46] scales_1.2.1           rgeos_0.5-9            gtable_0.3.1          
##  [49] globals_0.16.1         goftest_1.2-3          spam_2.9-1            
##  [52] rlang_1.0.6            systemfonts_1.0.4      splines_4.2.1         
##  [55] lazyeval_0.2.2         hexbin_1.28.2          spatstat.geom_3.0-3   
##  [58] BiocManager_1.30.19    yaml_2.3.6             reshape2_1.4.4        
##  [61] abind_1.4-5            crosstalk_1.2.0        httpuv_1.6.6          
##  [64] tools_4.2.1            tcltk_4.2.1            bookdown_0.29         
##  [67] ellipsis_0.3.2         spatstat.core_2.4-4    jquerylib_0.1.4       
##  [70] RColorBrewer_1.1-3     ggridges_0.5.4         Rcpp_1.0.9            
##  [73] plyr_1.8.7             zlibbioc_1.44.0        purrr_0.3.5           
##  [76] RCurl_1.98-1.9         rpart_4.1.19           deldir_1.0-6          
##  [79] pbapply_1.5-0          viridis_0.6.2          cowplot_1.1.1         
##  [82] zoo_1.8-11             SeuratObject_4.1.2     ggrepel_0.9.1         
##  [85] cluster_2.1.4          magrittr_2.0.3         magick_2.7.3          
##  [88] data.table_1.14.4      scattermore_0.8        lmtest_0.9-40         
##  [91] RANN_2.6.1             fitdistrplus_1.1-8     patchwork_1.1.2       
##  [94] mime_0.12              evaluate_0.17          xtable_1.8-4          
##  [97] gridExtra_2.3          compiler_4.2.1         tibble_3.1.8          
## [100] maps_3.4.1             KernSmooth_2.23-20     crayon_1.5.2          
## [103] htmltools_0.5.3        entropy_1.3.1          mgcv_1.8-41           
## [106] rTensor_1.4.8          later_1.3.0            tidyr_1.2.1           
## [109] DBI_1.1.3              tweenr_2.0.2           MASS_7.3-58.1         
## [112] babelgene_22.9         Matrix_1.5-1           cli_3.4.1             
## [115] parallel_4.2.1         dotCall64_1.0-2        igraph_1.3.5          
## [118] pkgconfig_2.0.3        sp_1.5-0               spatstat.sparse_3.0-0 
## [121] bslib_0.4.0            XVector_0.38.0         stringr_1.4.1         
## [124] digest_0.6.30          sctransform_0.3.5      RcppAnnoy_0.0.20      
## [127] spatstat.data_3.0-0    Biostrings_2.66.0      rmarkdown_2.17        
## [130] leiden_0.4.3           uwot_0.1.14            shiny_1.7.3           
## [133] lifecycle_1.0.3        nlme_3.1-160           jsonlite_1.8.3        
## [136] viridisLite_0.4.1      fansi_1.0.3            pillar_1.8.1          
## [139] lattice_0.20-45        KEGGREST_1.38.0        fastmap_1.1.0         
## [142] httr_1.4.4             survival_3.4-0         glue_1.6.2            
## [145] png_0.1-7              plot3D_1.4             bit_4.0.4             
## [148] ggforce_0.4.1          stringi_1.7.8          sass_0.4.2            
## [151] blob_1.2.3             textshaping_0.3.6      memoise_2.0.1         
## [154] dplyr_1.0.10           irlba_2.3.5.1          future.apply_1.9.1