In CytoML: A GatingML Interface for Cross Platform Cytometry Data Sharing

CytoML: Cross-Platform Cytometry Data Sharing.

This package is designed to import/export the hierarchical gated cytometry data to and from R (specifically the openCyto framework) using the gatingML2.0 and FCS3.0 cytometry data standards. This package makes use of the GatingSet R object and data model so that imported data can easily be manipulated and visualized in R using tools like openCyto and ggCyto.

What problems does CytoML solve?

CytoML allows you to:

• Import manually gated data into R from Diva, FlowJo and Cytobank.
• Combine manual gating strategies with automated gating strategies in R.
• Export data gated manually, auto-gated, or gated using a combination of manual and automated strategies from R to Diva, FlowJo and Cytobank.
• Share computational flow analyses with users on other platforms.
• Perform comparative analyses between computational and manual gating approaches.

INSTALLATION

CytoML can be installed in several ways:

For all versions:

For all versions, you must have dependencies installed

library(BiocManager)
# This should pull all dependencies.
BiocManager::install("openCyto") 

# Then install latest dependencies from github, using devtools.
install.packages("devtools") 
library(devtools) #load it

install_github("RGLab/flowWorkspace")
install_github("RGLab/openCyto")

Installing from BioConductor.

• Current BioConductor Relase

library(BiocManager)
#this should pull all dependencies.
BiocManager::install("CytoML", version = "devel") 

• Current BioConductor Development Version

library(BiocManager)
#this should pull all dependencies.
BiocManager::install("CytoML", version = "devel") 

Installing from GitHub

• Latest GitHub Version

install.packges("devtools")
devtools::install_github("RGLab/CytoML")

• Latest GitHub Release

install.packges("devtools")
devtools::install_github("RGLab/CytoML@*release")

Reproducible examples from the CytoML paper

• A reproducible workflow can be found at the RGLab site, and was prepared with version 1.7.10 of CytoML, R v3.5.0, and dependencies that can be installed by:

# We recomend using R version 3.5.0
devtools::install_github("RGLab/RProtoBufLib@v1.3.7")
devtools::install_github("RGLab/cytolib@v1.3.2")
devtools::install_github("RGLab/flowCore@v1.47.7")
devtools::install_github("RGLab/flowWorkspace@v3.29.7")
devtools::install_github("RGLab/openCyto@v1.19.2")
devtools::install_github("RGLab/CytoML@v1.7.10")
devtools::install_github("RGLab/ggcyto@v1.9.12")

Examples

Import data

To import data you need the xml workspace and the raw FCS files.

Import gatingML generated from Cytobank.

library(CytoML)
acsfile <- system.file("extdata/cytobank_experiment.acs", package = "CytoML")
ce <- open_cytobank_experiment(acsfile)
xmlfile <- ce$gatingML
fcsFiles <- list.files(ce$fcsdir, full.names = TRUE)
gs <- cytobank_to_gatingset(xmlfile, fcsFiles)

Import a Diva workspace.

ws <- open_diva_xml(system.file('extdata/diva/PE_2.xml', package = "flowWorkspaceData"))
# The path to the FCS files is stored in ws@path.
# It can also be passed in to parseWorksapce via the `path` argument.
gs <- diva_to_gatingset(ws, name = 2, subset = 1, swap_cols = FALSE)

Interact with the gated data (GatingSet)

We need flowWorkspace to interact with the imported data.

library(flowWorkspace)

We can visualize the gating tree as follows:

#get the first sample
gh <- gs[[1]]

#plot the hierarchy tree
plot(gh)

For more information see the flowWorkspace package.

We can print all the cell populations defined in the gating tree.

#show all the cell populations(/nodes)
gs_get_pop_paths(gh)

We can extract the cell population statistics.

#show the population statistics
gh_pop_compare_stats(gh)

The openCyto.count column shows the cell counts computed via the import. The xml.count column shows the cell counts computed by FlowJo (note not all platforms report cell counts in the workspace). It is normal for these to differ by a few cells due to numerical differences in the implementation of data transformations. CytoML and openCyto are reproducing the data analysis from the raw data based on the information in the workspace.

We can plot all the gates defined in the workspace.

#plot the gates
plotGate(gh) 

Access information about cells in a specific population.

Because CytoML and flowWorkspace reproduce the entire analysis in a workspace in R, we have access to information about which cells are part of which cell popualtions.

flowWorkspace has convenience methods to extract the cells from specific cell populations:

gh_pop_get_data(gh,"P3")

This returns a flowFrame with the cells in gate P3 (70% of the cells according to the plot).

The matrix of expression can be extracted from a flowFrame using the exprs() method from the flowCore package:

library(flowCore)
e <- exprs(gh_pop_get_data(gh,"P3"))
class(e)
dim(e)
colnames(e)
#compute the MFI of the fluorescence channels.
colMeans(e[,8:15])

Export gated data to other platforms.

In order to export gated data, it must be in GatingSet format.

Export a GatingSet from R to Cytobank or FlowJo

Load something to export.

dataDir <- system.file("extdata",package="flowWorkspaceData")
gs <- load_gs(list.files(dataDir, pattern = "gs_manual",full = TRUE))

Export to Cytobank

#Cytobank
outFile <- tempfile(fileext = ".xml")
gatingset_to_cytobank(gs, outFile)

Export to FlowJo

#flowJo
outFile <- tempfile(fileext = ".wsp")
gatingset_to_flowjo(gs, outFile)

Next Steps

See the flowWorskspace and [openCyto](http://www.github.com/RGLab/openCyto] packages to learn more about what can be done with GatingSet objects.

Code of conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

CytoML documentation built on March 12, 2021, 2 a.m.