This vignette demonstrates how the gatingML files exported from Cytobank can be imported into R as a GatingSet object.

library(flowWorkspace)
library(CytoML)
fcsFiles <- list.files(pattern = "CytoTrol", system.file("extdata", package = "flowWorkspaceData"), full.names = TRUE)
xmlfile <- system.file("extdata/cytotrol_tcell_cytobank.xml", package = "CytoML")

0.1 Use cytobank2GatingSet

The entire parsing work can be done with single convevient function cytobank2GatingSet:

gs <- cytobank2GatingSet(xmlfile, fcsFiles)

0.2 Load GatingML and FCS separately

Or you can divide the parsing into several steps to have more controls.

0.2.1 Load the gatingML file as a graphGML object

g <- read.gatingML.cytobank(xmlfile)
class(g)
## [1] "graphGML"
## attr(,"package")
## [1] "CytoML"
g
## --- Gating hieararchy parsed from GatingML: 
##  with  12  populations defined

graphGML stores the gating hierarchy, which can be inspected by various accessors.

getNodes(g)
## GateSet_722318 GateSet_722319 GateSet_722320 GateSet_722321 GateSet_722322 
##          "CD4"          "CD8"           "Q4"           "Q3"     "singlets" 
## GateSet_722323 GateSet_722324 GateSet_722325 GateSet_722326 GateSet_722327 
##   "not debris"           "Q1"           "Q2"       "CD8_Q2"          "CD3" 
## GateSet_722328 GateSet_722329 
##   "CD38 range"    "HLA range"
getParent(g, "GateSet_722318")
## [1] "GateSet_722327"
getChildren(g, "GateSet_722318")
## [1] "GateSet_722320" "GateSet_722321" "GateSet_722324" "GateSet_722325"

And the population tree can be plotted

plot(g)

The node with dotted border means the tailored gates(or sample-specific gates) are defined for that population.

0.2.2 Read raw FCS files and construct the GatingSet

fs <- read.ncdfFlowSet(fcsFiles)
gs <- GatingSet(fs)

0.2.3 Compensate and transform the GatingSet

gs <- compensate(gs, g)
## Extract the transformation from graphGML
trans <- getTransformations(g)
trans
## $`B710-A`
## Transformer:  asinhtGml2 
## 
## $`G560-A`
## Transformer:  asinhtGml2 
## 
## $`G780-A`
## Transformer:  asinhtGml2 
## 
## $`R660-A`
## Transformer:  asinhtGml2 
## 
## $`R780-A`
## Transformer:  asinhtGml2 
## 
## $`V450-A`
## Transformer:  asinhtGml2 
## 
## $`V545-A`
## Transformer:  asinhtGml2 
## 
## attr(,"class")
## [1] "transformerList" "list"
## Transform the `GatingSet`
gs <- transform(gs, trans)

0.2.4 Visualize the outcome of compensation and transformation

require(ggcyto)
ggcyto(gs, aes(x = CD4), subset = "root") + geom_density()
ggcyto(gs, aes(x = CD4, y = CD8), subset = "root") + geom_hex()

0.2.5 Apply the gates to GatingSet and inspect the results

gating(g, gs)
## Plot the gates
autoplot(gs[[1]])

# Extract the population statistics
getPopStats(gs, statType = "count")
##                        name Population     Parent Count ParentCount
##  1: CytoTrol_CytoTrol_1.fcs not debris       root 87876      119531
##  2: CytoTrol_CytoTrol_1.fcs   singlets not debris 79845       87876
##  3: CytoTrol_CytoTrol_1.fcs        CD3   singlets 53135       79845
##  4: CytoTrol_CytoTrol_1.fcs        CD8        CD3 12862       53135
##  5: CytoTrol_CytoTrol_1.fcs     CD8_Q2        CD8  2331       12862
##  6: CytoTrol_CytoTrol_1.fcs  HLA range     CD8_Q2  2315        2331
##  7: CytoTrol_CytoTrol_1.fcs CD38 range     CD8_Q2  2331        2331
##  8: CytoTrol_CytoTrol_1.fcs        CD4        CD3 33653       53135
##  9: CytoTrol_CytoTrol_1.fcs         Q2        CD4 11429       33653
## 10: CytoTrol_CytoTrol_1.fcs         Q1        CD4   419       33653
## 11: CytoTrol_CytoTrol_1.fcs         Q3        CD4 17686       33653
## 12: CytoTrol_CytoTrol_1.fcs         Q4        CD4  4119       33653
## 13: CytoTrol_CytoTrol_2.fcs not debris       root 87648      115728
## 14: CytoTrol_CytoTrol_2.fcs   singlets not debris 79641       87648
## 15: CytoTrol_CytoTrol_2.fcs        CD3   singlets 50761       79641
## 16: CytoTrol_CytoTrol_2.fcs        CD8        CD3 12413       50761
## 17: CytoTrol_CytoTrol_2.fcs     CD8_Q2        CD8  2208       12413
## 18: CytoTrol_CytoTrol_2.fcs  HLA range     CD8_Q2  2193        2208
## 19: CytoTrol_CytoTrol_2.fcs CD38 range     CD8_Q2  2208        2208
## 20: CytoTrol_CytoTrol_2.fcs        CD4        CD3 32226       50761
## 21: CytoTrol_CytoTrol_2.fcs         Q2        CD4 10904       32226
## 22: CytoTrol_CytoTrol_2.fcs         Q1        CD4   383       32226
## 23: CytoTrol_CytoTrol_2.fcs         Q3        CD4 16965       32226
## 24: CytoTrol_CytoTrol_2.fcs         Q4        CD4  3974       32226
##                        name Population     Parent Count ParentCount