Contents

1 Install and Load the Package

To install cytofkit package, start R and run the following codes on R console:

source("https://bioconductor.org/biocLite.R")
biocLite("cytofkit")

Notes: cytofkit GUI is dependent on XQuartz windowing system (X Windows) on Mac (OS X > 10.7). Install XQuartz from http://xquartz.macosforge.org.

Load the Package:

library("cytofkit")

Read the package description:

?"cytofkit-package"

2 Options for Using cytofkit Package

cytofkit provides three ways to employ the workforce of this package:

2.1 Run with GUI

The easiest way to use cytofkit package is through the GUI. The GUI provides all main options of cytofkit on a visual interface. To launch the GUI, load the package and type the following command:

cytofkit_GUI()

The interface will appear like below, you can click the information button ! to check the explanation for each entry and customize your own analysis.

cytofkit GUI

cytofkit GUI

Start your analysis as simply as following:

  • Choose the input fcs files from the directory where you store FCS data;
  • Select the markers from the auto-generated marker list;
  • Choose the directory where to save your output;
  • Give a project name as a prefix for the names of result files;
  • Select a data merging method if you have multiple FCS files;
  • Select your clustering method(s), visualization method(s), progression estimation method(s)

Then submit it, that’s all.

Depends on the size of your data, it will take some time to run the analysis. Once done, a window will pop up, showing you the path where the results have been stored, and asking you if open the shiny web APP. If YES, the shiny APP will be deployed locally and opened in your default web browser. Among the saved results, a special R data object with suffix of .RData is for loading the results into the shiny APP. Choose the .RData file on the shiny APP then submit it, your journey of exploring the results starts.

2.2 Run with the Core Function

Cytofkit provides a core function cytofkit() to drive the analysis pipeline of mass cytometry data. Users only need to define several key parameters to start their analysis automatically. One simple example of running cytofkit using the core function is like this:

set.seed(100)
dir <- system.file('extdata',package='cytofkit')
file <- list.files(dir ,pattern='.fcs$', full=TRUE)
parameters <- list.files(dir, pattern='.txt$', full=TRUE)
res <- cytofkit(fcsFiles = file, 
                markers = parameters, 
                projectName = 'cytofkit_test',
                transformMethod = "cytofAsinh", 
                mergeMethod = "ceil",
                fixedNum = 500,                                    ## set at 500 for faster run
                dimReductionMethod = "tsne",
                clusterMethods = c("Rphenograph", "ClusterX"),    ## accept multiple methods
                visualizationMethods = c("tsne", "pca"),          ## accept multiple methods
                progressionMethod = "isomap",
                clusterSampleSize = 500,
                resultDir = getwd(),
                saveResults = TRUE, 
                saveObject = TRUE)

You can customize the parameters for your own need, run ?cytofkit to get information of all the parameters for cytofkit. As running with GUI, once the analysis is done, the results will be saved under resultDir automatically.

2.3 Run with Commands (Step-by-Step)

You can make use of the functions exported from cytofkit to make your analysis more flexible and fit your own need. Here we use a sample data for demo:

2.3.1 Pre-processing

## Loading the FCS data:  
dir <- system.file('extdata',package='cytofkit')
file <- list.files(dir ,pattern='.fcs$', full=TRUE)
paraFile <- list.files(dir, pattern='.txt$', full=TRUE)
parameters <- as.character(read.table(paraFile, header = TRUE)[,1])

## File name
file
## [1] "/tmp/RtmpGmHEQA/Rinst31c8717cdcd9/cytofkit/extdata/130515_C2_stim_CD19-.fcs"
## parameters
parameters
##  [1] "(Sm152)Di<Vd2>"    "(Eu153)Di<CD107a>" "(Sm154)Di<CD3>"   
##  [4] "(Gd155)Di<CD152>"  "(Gd156)Di<CD19>"   "(Gd157)Di<TIM3>"  
##  [7] "(Gd158)Di<CD56>"   "(Tb159)Di<IL10>"   "(Gd160)Di<CD28>"  
## [10] "(Dy161)Di<CD38>"   "(Dy162)Di<IL4>"    "(Dy163)Di<CD127>"
## Extract the expression matrix with transformation
data_transformed <- cytof_exprsExtract(fcsFile = file, 
                                       comp = FALSE, 
                                       transformMethod = "cytofAsinh")
## If analysing flow cytometry data, you can set comp to TRUE or 
## provide a transformation matrix to apply compensation

## If you have multiple FCS files, expression can be extracted and combined
combined_data_transformed <- cytof_exprsMerge(fcsFiles = file, comp=FALSE,
                                              transformMethod = "cytofAsinh",
                                              mergeMethod = "all")
## change mergeMethod to apply different combination strategy

## Take a look at the extracted expression matrix
head(data_transformed[ ,1:3])
##                        Cell_length<NA> (Rh103)Di<BC103> (Pd104)Di<BC104>
## 130515_C2_stim_CD19-_1        2.824903    -0.0018738715         4.072829
## 130515_C2_stim_CD19-_2        2.725596     0.0011091183         4.125760
## 130515_C2_stim_CD19-_3        2.672016    -0.0004428311         3.705151
## 130515_C2_stim_CD19-_4        2.555494    -0.0008412519         3.393448
## 130515_C2_stim_CD19-_5        2.644121     0.0040425242         3.554248
## 130515_C2_stim_CD19-_6        2.800979     0.0032699275         3.974557

2.3.2 Cell Subset Detection

## use clustering algorithm to detect cell subsets
## to speed up our test here, we only use 100 cells
data_transformed_1k <- data_transformed[1:100, ]

## run PhenoGraph
cluster_PhenoGraph <- cytof_cluster(xdata = data_transformed_1k, method = "Rphenograph")
##   Running PhenoGraph...  Finding nearest neighbors...DONE ~ 0.002 s
##   Compute jaccard coefficient between nearest-neighbor sets...DONE ~ 0.033 s
##   Build undirected graph from the weighted links...DONE ~ 0.015 s
##   Run louvain clustering on the graph ...DONE ~ 0.006 s
##   Return a community class
##   -Modularity value: 0.4696663 
##   -Number of clusters: 4 DONE!
## run ClusterX
data_transformed_1k_tsne <- cytof_dimReduction(data=data_transformed_1k, method = "tsne")
##   Running t-SNE...with seed 42  DONE
cluster_ClusterX <- cytof_cluster(ydata = data_transformed_1k_tsne,  method="ClusterX")
##   Running ClusterX...    Calculate cutoff distance...0.52  
##     Calculate local Density...DONE!
##     Detect nearest neighbour with higher density...DONE!
##     Peak detection...DONE!
##     Cluster assigning...DONE!
##  DONE!
## run DensVM (takes long time, we skip here)
cluster_DensVM <- cytof_cluster(xdata = data_transformed_1k, 
                                ydata = data_transformed_1k_tsne, method = "DensVM")
## run FlowSOM with cluster number 15
cluster_FlowSOM <- cytof_cluster(xdata = data_transformed_1k, method = "FlowSOM", FlowSOM_k = 12)
##   Running FlowSOM...    Building SOM...
##     Meta clustering to 12 clusters...
##  DONE!
## combine data
data_1k_all <- cbind(data_transformed_1k, data_transformed_1k_tsne, 
                     PhenoGraph = cluster_PhenoGraph, ClusterX=cluster_ClusterX, 
                     FlowSOM=cluster_FlowSOM)
data_1k_all <- as.data.frame(data_1k_all)

2.3.3 Cell Subset Visualization and Interpretation

## PhenoGraph plot on tsne
cytof_clusterPlot(data=data_1k_all, xlab="tsne_1", ylab="tsne_2", 
                  cluster="PhenoGraph", sampleLabel = FALSE)

## PhenoGraph cluster heatmap
PhenoGraph_cluster_median <- aggregate(. ~ PhenoGraph, data = data_1k_all, median)
cytof_heatmap(PhenoGraph_cluster_median[, 2:37], baseName = "PhenoGraph Cluster Median")

## ClusterX plot on tsne
cytof_clusterPlot(data=data_1k_all, xlab="tsne_1", ylab="tsne_2", cluster="ClusterX", sampleLabel = FALSE)

## ClusterX cluster heatmap
ClusterX_cluster_median <- aggregate(. ~ ClusterX, data = data_1k_all, median)
cytof_heatmap(ClusterX_cluster_median[, 2:37], baseName = "ClusterX Cluster Median")

## FlowSOM plot on tsne
cytof_clusterPlot(data=data_1k_all, xlab="tsne_1", ylab="tsne_2", 
                  cluster="FlowSOM", sampleLabel = FALSE)

## FlowSOM cluster heatmap
FlowSOM_cluster_median <- aggregate(. ~ FlowSOM, data = data_1k_all, median)
cytof_heatmap(FlowSOM_cluster_median[, 2:37], baseName = "FlowSOM Cluster Median")

2.3.4 Inference of Subset Progression

## Inference of PhenoGraph cluster relatedness
PhenoGraph_progression <- cytof_progression(data = data_transformed_1k, 
                                            cluster = cluster_PhenoGraph, 
                                            method="isomap", clusterSampleSize = 50, 
                                            sampleSeed = 5)
##   Running ISOMAP...  DONE
p_d <- data.frame(PhenoGraph_progression$sampleData, 
                  PhenoGraph_progression$progressionData, 
                  cluster = PhenoGraph_progression$sampleCluster, 
                  check.names = FALSE)

## cluster relatedness plot
cytof_clusterPlot(data=p_d, xlab="isomap_1", ylab="isomap_2", 
                  cluster="cluster", sampleLabel = FALSE)

## marker expression profile
markers <- c("(Sm150)Di<GranzymeB>", "(Yb173)Di<Perforin>")

cytof_colorPlot(data=p_d, xlab="isomap_1", ylab="isomap_2", zlab = markers[1], limits = range(p_d[,1:52]))

cytof_colorPlot(data=p_d, xlab="isomap_1", ylab="isomap_2", zlab = markers[2], limits = range(p_d[,1:52]))

cytof_progressionPlot(data=p_d, markers=markers, orderCol="isomap_1", clusterCol = "cluster")

## Inference of ClusterX cluster relatedness
ClusterX_progression <- cytof_progression(data = data_transformed_1k, 
                                          cluster = cluster_ClusterX, 
                                          method="isomap", 
                                          clusterSampleSize = 30, 
                                          sampleSeed = 3)
##   Running ISOMAP...  DONE
c_d <- data.frame(ClusterX_progression$sampleData, 
                  ClusterX_progression$progressionData,
                  cluster=ClusterX_progression$sampleCluster, 
                  check.names = FALSE)

## cluster relatedness plot
cytof_clusterPlot(data=c_d, xlab="isomap_1", ylab="isomap_2", 
                  cluster="cluster", sampleLabel = FALSE)

## marker expression profile
markers <- c("(Sm150)Di<GranzymeB>", "(Yb173)Di<Perforin>")

cytof_colorPlot(data=c_d, xlab="isomap_1", ylab="isomap_2", zlab = markers[1], limits = range(c_d[,1:52]))

cytof_colorPlot(data=c_d, xlab="isomap_1", ylab="isomap_2", zlab = markers[2], limits = range(c_d[,1:52]))

cytof_progressionPlot(data=c_d, markers, orderCol="isomap_1", clusterCol = "cluster")

2.3.5 Post-processing

## save analysis results to FCS file
cytof_addToFCS(data_1k_all, rawFCSdir=dir, analyzedFCSdir="analysed_FCS", 
               transformed_cols = c("tsne_1", "tsne_2"), 
               cluster_cols = c("PhenoGraph", "ClusterX", "FlowSOM"))

In addition, expression values for cells in a specified cluster can be extracted using cytof_clusterMtrx()

## See documentation, this function uses the output of main cytofkit cuntion as its input
?cytof_clusterMtrx

2.3.6 Get package update news

cytofkitNews()

3 Session Information

sessionInfo()
## R version 3.5.0 (2018-04-23)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 16.04.4 LTS
## 
## Matrix products: default
## BLAS: /home/biocbuild/bbs-3.7-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.7-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] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] cytofkit_1.12.0 plyr_1.8.4      ggplot2_2.2.1   BiocStyle_2.8.0
## 
## loaded via a namespace (and not attached):
##   [1] Rtsne_0.13                  VGAM_1.0-5                 
##   [3] colorspace_1.3-2            RcppEigen_0.3.3.4.0        
##   [5] class_7.3-14                rio_0.5.10                 
##   [7] rprojroot_1.3-2             corpcor_1.6.9              
##   [9] XVector_0.20.0              GenomicRanges_1.32.0       
##  [11] proxy_0.4-22                ggrepel_0.7.0              
##  [13] mvtnorm_1.0-7               codetools_0.2-15           
##  [15] splines_3.5.0               doParallel_1.0.11          
##  [17] robustbase_0.93-0           knitr_1.20                 
##  [19] cluster_2.0.7-1             graph_1.58.0               
##  [21] shiny_1.0.5                 rrcov_1.4-3                
##  [23] compiler_3.5.0              backports_1.1.2            
##  [25] assertthat_0.2.0            Matrix_1.2-14              
##  [27] lazyeval_0.2.1              later_0.7.1                
##  [29] htmltools_0.3.6             tools_3.5.0                
##  [31] igraph_1.2.1                gtable_0.2.0               
##  [33] GenomeInfoDbData_1.1.0      reshape2_1.4.3             
##  [35] RANN_2.5.1                  ggthemes_3.4.2             
##  [37] Rcpp_0.12.16                carData_3.0-1              
##  [39] Biobase_2.40.0              cellranger_1.1.0           
##  [41] RJSONIO_1.3-0               nlme_3.1-137               
##  [43] gdata_2.18.0                iterators_1.0.9            
##  [45] lmtest_0.9-36               xfun_0.1                   
##  [47] laeken_0.4.6                stringr_1.3.0              
##  [49] openxlsx_4.0.17             mime_0.5                   
##  [51] miniUI_0.1.1                gtools_3.5.0               
##  [53] XML_3.98-1.11               DEoptimR_1.0-8             
##  [55] zlibbioc_1.26.0             MASS_7.3-50                
##  [57] zoo_1.8-1                   scales_0.5.0               
##  [59] VIM_4.7.0                   colourpicker_1.0           
##  [61] promises_1.0.1              parallel_3.5.0             
##  [63] SummarizedExperiment_1.10.0 yaml_2.1.18                
##  [65] curl_3.2                    stringi_1.1.7              
##  [67] S4Vectors_0.18.0            pcaPP_1.9-73               
##  [69] foreach_1.4.4               permute_0.9-4              
##  [71] e1071_1.6-8                 flowCore_1.46.0            
##  [73] destiny_2.10.0              TTR_0.23-3                 
##  [75] caTools_1.17.1              BiocGenerics_0.26.0        
##  [77] boot_1.3-20                 BiocParallel_1.14.0        
##  [79] GenomeInfoDb_1.16.0         rlang_0.2.0                
##  [81] pkgconfig_2.0.1             matrixStats_0.53.1         
##  [83] bitops_1.0-6                evaluate_0.10.1            
##  [85] lattice_0.20-35             labeling_0.3               
##  [87] htmlwidgets_1.2             pdist_1.2                  
##  [89] magrittr_1.5                bookdown_0.7               
##  [91] R6_2.2.2                    IRanges_2.14.0             
##  [93] gplots_3.0.1                DelayedArray_0.6.0         
##  [95] mgcv_1.8-23                 pillar_1.2.2               
##  [97] haven_1.1.1                 foreign_0.8-70             
##  [99] xts_0.10-2                  scatterplot3d_0.3-41       
## [101] abind_1.4-5                 RCurl_1.95-4.10            
## [103] sp_1.2-7                    nnet_7.3-12                
## [105] FlowSOM_1.12.0              tibble_1.4.2               
## [107] tsne_0.1-3                  car_3.0-0                  
## [109] shinyFiles_0.6.2            KernSmooth_2.23-15         
## [111] rmarkdown_1.9               grid_3.5.0                 
## [113] readxl_1.1.0                data.table_1.10.4-3        
## [115] vegan_2.5-1                 ConsensusClusterPlus_1.44.0
## [117] forcats_0.3.0               vcd_1.4-4                  
## [119] digest_0.6.15               xtable_1.8-2               
## [121] httpuv_1.4.1                stats4_3.5.0               
## [123] munsell_0.4.3               smoother_1.1               
## [125] tcltk_3.5.0