1 Introduction

In the single cell World, which includes flow cytometry, mass cytometry, single-cell RNA-seq (scRNA-seq), and others, there is a need to improve data visualisation and to bring analysis capabilities to researchers even from non-technical backgrounds. scDataviz (Blighe 2020) attempts to fit into this space, while also catering for advanced users. Additonally, due to the way that scDataviz is designed, which is based on SingleCellExperiment (Lun and Risso 2020), it has a ‘plug and play’ feel, and immediately lends itself as flexibile and compatibile with studies that go beyond scDataviz. Finally, the graphics in scDataviz are generated via the ggplot (Wickham 2016) engine, which means that users can ‘add on’ features to these with ease.

2 Installation

2.2 2. Load the package into R session

3 Tutorial 1: CyTOF FCS data

Here, we will utilise some of the flow cytometry data from Deep phenotyping detects a pathological CD4+ T-cell complosome signature in systemic sclerosis.

This can normally be downloadedd via git clone from your command prompt:

In a practical situation, we would normally read in this data from the raw FCS files and then QC filter, normalise, and transform them. This can be achieved via the processFCS function, which, by default, also removes variables based on low variance and downsamples [randomly] your data to 100000 variables. The user can change these via the downsample and downsampleVar parameters. An example (not run) is given below:

In flow and mass cytometry, getting the correct marker names in the FCS files can be surprisingly difficult. In many cases, from experience, a facility may label the markers by their metals, such as Iridium (Ir), Ruthenium (Ru), Terbium (Tb), et cetera - this is the case for the data used in this tutorial. The true marker names may be held as pData encoded within each FCS, accessible via:

Whatever the case, it is important to sort out marker naming issues prior to the experiment being conducted in order to avoid any confusion.

For this vignette, due to the fact that the raw FCS data is > 500 megabytes, we will work with a smaller pre-prepared dataset that has been downsampled to 10000 cells using the above code. This data comes included with the package.

Load the pre-prepared complosome data.

One can also create a new SingleCellExperiment object manually using any type of data, including any data from scRNA-seq produced elsewhere. Import functions for data deriving from other sources is covered in Tutorials 2 and 3 in this vignette. All functions in scDataviz additionally accept data-frames or matrices on their own, de-necessitating the reliance on the SingleCellExperiment class.

3.2 Perform UMAP

UMAP can be performed on the entire dataset, if your computer’s memory will permit. Currently it’s default is to use the data contained in the ‘scaled’ assay component of your SingleCellExperiment object.

UMAP can also be stratified based on a column in your metadata, e.g., (treated versus untreated samples); however, to do this, I recommend creating separate SingleCellExperiment objects from the very start, i.e., from the the data input stage, and processing the data separately for each group.

Nota bene - advanced users may want to change the default configuration for UMAP. scDataviz currently performs UMAP via the umap package. In order to modify the default configuration, one can pull in the default config separately from the umap package and then modify these config values held in the umap.defaults variable, as per the umap vignette (see ‘Tuning UMAP’ section). For example:

We can also perform UMAP on a select number of PC eigenvectors. PCAtools (Blighe and Lun 2020) can be used to infer ideal number of dimensions to use via the elbow method and Horn’s parallel analysis.

## PC3 
##   3
## [1] 1

For now, let’s just use 5 PCs.

3.3 Create a contour plot of the UMAP layout

This and the remaining sections in this tutorial are about producing great visualisations of the data and attempting to make sense of it, while not fully overlapping with functionalioty provided by other programs that operate in tis space.

With the contour plot, we are essentially looking at celluar density. It can provide for a beautiful viusualisation in a manuscript while also serving as a useful QC tool: if the density is ‘scrunched up’ into a single area in the plot space, then there are likely issues with your input data distribution. We want to see well-separated, high density ‘islands’, or, at least, gradual gradients that blend into one another across high density ‘peaks’.

Create a contour plot of the UMAP layout

Create a contour plot of the UMAP layout

3.5 Shade cells by metadata

Shading cells by metadata can be useful for identifying any batch effects, but also useful for visualising, e.g., differences across treatments.

First, let’s take a look inside the metadata that we have.

##       sample   group treatment
## cell1    P00 Disease    Unstim
## cell2    P00 Disease    Unstim
## cell3    P04 Disease      CD46
## cell4    P03 Disease      CD46
## cell5    P08 Disease    Unstim
## cell6    P00 Disease      CD46
## [1] "Healthy" "Disease"
## [1] "CD46"   "Unstim" "CD3"
Shade cells by metadata

Shade cells by metadata

3.8 Determine enriched markers in each cluster and plot the expression signature

This method also calculates metacluster abundances across a chosen phenotype. The function returns a data-frame, which can then be exported to do other analyses.

3.8.1 Disease vs Healthy metacluster abundances

Cluster nCells TotalCells PercentCells NegMarkers PosMarkers PerCent_HD00 PerCent_HD01 PerCent_HD262 PerCent_P00 PerCent_P02 PerCent_P03 PerCent_P04 PerCent_P08 nCell_Healthy nCell_Disease
0 3410 10000 34.10 NA CD25+ 0.0879765 9.6187683 25.483871 22.8152493 8.3870968 8.8563050 17.7126100 7.0381232 1200 2210
1 1928 10000 19.28 CD25-CD279- CD3+CD45RA+ 0.0000000 0.1556017 62.085062 0.5705394 0.2074689 0.0000000 0.0518672 36.9294606 1200 728
2 1298 10000 12.98 Granzyme B-CD279- CD3+ 15.6394453 7.8582435 2.234206 64.1756549 3.8520801 3.5439137 1.9260401 0.7704160 334 964
3 1236 10000 12.36 NA CD25+ 6.3915858 1.1326861 1.375404 2.9126214 24.0291262 7.0388350 56.8770227 0.2427184 110 1126
4 962 10000 9.62 NA CD3+ 16.5280665 26.1954262 7.484407 27.9625780 3.2224532 10.0831601 6.0291060 2.4948025 483 479
5 502 10000 5.02 CD25- NA 0.3984064 14.9402390 40.836653 11.1553785 0.0000000 0.3984064 0.1992032 32.0717131 282 220
6 300 10000 3.00 CD46-CD279- NA 0.0000000 41.0000000 2.000000 54.6666667 0.3333333 0.3333333 0.6666667 1.0000000 129 171
7 281 10000 2.81 NA Foxp3+CD25+CD3+ 0.3558719 0.0000000 70.462633 2.1352313 0.7117438 0.7117438 0.3558719 25.2669039 199 82
8 61 10000 0.61 CD46- NA 0.0000000 18.0327869 1.639344 0.0000000 1.6393443 78.6885246 0.0000000 0.0000000 12 49
9 22 10000 0.22 CD46-CD279- CD3+ 0.0000000 18.1818182 4.545454 0.0000000 0.0000000 77.2727273 0.0000000 0.0000000 5 17

.

3.8.2 Treatment type metacluster abundances

Cluster nCells TotalCells PercentCells NegMarkers PosMarkers nCell_CD46 nCell_Unstim nCell_CD3
0 3410 10000 34.10 NA CD25+ 3384 2 24
1 1928 10000 19.28 CD25-CD279- CD3+CD45RA+ 3 1921 4
2 1298 10000 12.98 Granzyme B-CD279- CD3+ 5 1172 121
3 1236 10000 12.36 NA CD25+ 21 132 1083
4 962 10000 9.62 NA CD3+ 4 771 187
5 502 10000 5.02 CD25- NA 112 24 366
6 300 10000 3.00 CD46-CD279- NA 288 10 2
7 281 10000 2.81 NA Foxp3+CD25+CD3+ 2 276 3
8 61 10000 0.61 CD46- NA 57 4 0
9 22 10000 0.22 CD46-CD279- CD3+ 21 1 0

.

3.8.3 Expression signature

The expression signature is a quick way to visualise which markers are more or less expressed in each identified cluster of cells.

Determine enriched markers in each cluster and plot the expression signature

Determine enriched markers in each cluster and plot the expression signature

4 Tutorial 2: Import from Seurat

Due to the fact that scDataviz is based on SingleCellExperiment, it has increased interoperability with other packages, including the popular Seurat (Stuart et al. 2018). Taking the data produced from the Seurat Tutorial on Peripheral Blood Mononuclear Cells (PBMCs), we can convert this to a SingleCellExperiment object recognisable by scDataviz via as.SingleCellExperiment().

For a full workflow for Seurat-to-scDataviz, see the GitHub vignette.

5 Tutorial 3: Import any numerical data

scDataviz will work with any numerical data, too. Here, we show a quick example of how one can import a data-matrix of randomly-generated numbers that follow a negative binomial distribution, comprising 2500 cells and 20 markers:

##       group
## cell1     A
## cell2     A
## cell3     A
## cell4     A
## cell5     A
## cell6     A
## class: SingleCellExperiment 
## dim: 20 2500 
## metadata(1): group
## assays(1): normcounts
## rownames(20): CD1 CD2 ... CD19 CD20
## rowData names(0):
## colnames(2500): cell1 cell2 ... cell2499 cell2500
## colData names(0):
## reducedDimNames(0):
## altExpNames(0):

This will also work without any assigned metadata.

## class: SingleCellExperiment 
## dim: 20 2500 
## metadata(0):
## assays(1): normcounts
## rownames(20): CD1 CD2 ... CD19 CD20
## rowData names(0):
## colnames(2500): cell1 cell2 ... cell2499 cell2500
## colData names(0):
## reducedDimNames(0):
## altExpNames(0):

6 Acknowledgments

7 Session info

## R version 4.0.3 (2020-10-10)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 18.04.5 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.12-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.12-bioc/R/lib/libRlapack.so
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        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] parallel  stats4    stats     graphics  grDevices utils     datasets 
## [8] methods   base     
## 
## other attached packages:
##  [1] PCAtools_2.2.0              ggrepel_0.8.2              
##  [3] ggplot2_3.3.2               scDataviz_1.0.0            
##  [5] SingleCellExperiment_1.12.0 SummarizedExperiment_1.20.0
##  [7] Biobase_2.50.0              GenomicRanges_1.42.0       
##  [9] GenomeInfoDb_1.26.0         IRanges_2.24.0             
## [11] MatrixGenerics_1.2.0        matrixStats_0.57.0         
## [13] S4Vectors_0.28.0            BiocGenerics_0.36.0        
## [15] kableExtra_1.3.1            knitr_1.30                 
## 
## loaded via a namespace (and not attached):
##   [1] corrplot_0.84             plyr_1.8.6               
##   [3] igraph_1.2.6              lazyeval_0.2.2           
##   [5] splines_4.0.3             flowCore_2.2.0           
##   [7] BiocParallel_1.24.0       listenv_0.8.0            
##   [9] digest_0.6.27             htmltools_0.5.0          
##  [11] magrittr_1.5              tensor_1.5               
##  [13] cluster_2.1.0             ROCR_1.0-11              
##  [15] globals_0.13.1            RcppParallel_5.0.2       
##  [17] askpass_1.1               cytolib_2.2.0            
##  [19] colorspace_1.4-1          rvest_0.3.6              
##  [21] rappdirs_0.3.1            xfun_0.18                
##  [23] dplyr_1.0.2               crayon_1.3.4             
##  [25] RCurl_1.98-1.2            jsonlite_1.7.1           
##  [27] spatstat_1.64-1           spatstat.data_1.4-3      
##  [29] survival_3.2-7            zoo_1.8-8                
##  [31] glue_1.4.2                polyclip_1.10-0          
##  [33] gtable_0.3.0              zlibbioc_1.36.0          
##  [35] XVector_0.30.0            webshot_0.5.2            
##  [37] leiden_0.3.3              DelayedArray_0.16.0      
##  [39] BiocSingular_1.6.0        future.apply_1.6.0       
##  [41] abind_1.4-5               scales_1.1.1             
##  [43] miniUI_0.1.1.1            Rcpp_1.0.5               
##  [45] isoband_0.2.2             viridisLite_0.3.0        
##  [47] xtable_1.8-4              dqrng_0.2.1              
##  [49] reticulate_1.18           rsvd_1.0.3               
##  [51] umap_0.2.6.0              htmlwidgets_1.5.2        
##  [53] httr_1.4.2                RColorBrewer_1.1-2       
##  [55] ellipsis_0.3.1            Seurat_3.2.2             
##  [57] ica_1.0-2                 farver_2.0.3             
##  [59] pkgconfig_2.0.3           uwot_0.1.8               
##  [61] deldir_0.1-29             labeling_0.4.2           
##  [63] tidyselect_1.1.0          rlang_0.4.8              
##  [65] reshape2_1.4.4            later_1.1.0.1            
##  [67] munsell_0.5.0             tools_4.0.3              
##  [69] generics_0.0.2            ggridges_0.5.2           
##  [71] evaluate_0.14             stringr_1.4.0            
##  [73] fastmap_1.0.1             yaml_2.2.1               
##  [75] goftest_1.2-2             fitdistrplus_1.1-1       
##  [77] purrr_0.3.4               RANN_2.6.1               
##  [79] sparseMatrixStats_1.2.0   pbapply_1.4-3            
##  [81] future_1.19.1             nlme_3.1-150             
##  [83] mime_0.9                  xml2_1.3.2               
##  [85] compiler_4.0.3            rstudioapi_0.11          
##  [87] plotly_4.9.2.1            png_0.1-7                
##  [89] spatstat.utils_1.17-0     tibble_3.0.4             
##  [91] stringi_1.5.3             highr_0.8                
##  [93] RSpectra_0.16-0           lattice_0.20-41          
##  [95] Matrix_1.2-18             vctrs_0.3.4              
##  [97] pillar_1.4.6              lifecycle_0.2.0          
##  [99] lmtest_0.9-38             RcppAnnoy_0.0.16         
## [101] data.table_1.13.2         cowplot_1.1.0            
## [103] bitops_1.0-6              irlba_2.3.3              
## [105] httpuv_1.5.4              patchwork_1.0.1          
## [107] R6_2.4.1                  promises_1.1.1           
## [109] KernSmooth_2.23-17        gridExtra_2.3            
## [111] RProtoBufLib_2.2.0        codetools_0.2-16         
## [113] MASS_7.3-53               openssl_1.4.3            
## [115] withr_2.3.0               sctransform_0.3.1        
## [117] GenomeInfoDbData_1.2.4    mgcv_1.8-33              
## [119] grid_4.0.3                rpart_4.1-15             
## [121] beachmat_2.6.0            tidyr_1.1.2              
## [123] rmarkdown_2.5             DelayedMatrixStats_1.12.0
## [125] Rtsne_0.15                shiny_1.5.0

8 References

Blighe (2020)

Blighe and Lun (2020)

Lun and Risso (2020)

Stuart et al. (2018)

Wickham (2016)

Blighe, K. 2020. “scDataviz: single cell dataviz and downstream analyses.” https://github.com/kevinblighe/scDataviz.

Blighe, K, and A Lun. 2020. “PCAtools: everything Principal Component Analysis.” https://github.com/kevinblighe/PCAtools.

Lun, A, and D Risso. 2020. “SingleCellExperiment: S4 Classes for Single Cell Data.” https://bioconductor.org/packages/SingleCellExperiment.

Stuart, Tim, Andrew Butler, Paul Hoffman, Christoph Hafemeister, Efthymia Papalexi, William M Mauck III, Marlon Stoeckius, Peter Smibert, and Rahul Satija. 2018. “Comprehensive Integration of Single Cell Data.” bioRxiv. https://doi.org/10.1101/460147.

Wickham, H. 2016. “ggplot2: Elegant Graphics for Data Analysis.” Springer-Verlag New York, ISBN: 978-3-319-24277-4.