README.Rmd

---
output: github_document
editor_options: 
  
  chunk_output_type: inline
---

# 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](https://github.com/RGLab/openCyto) framework) using the [`gatingML2.0`](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4874733/) and [`FCS3.0`](http://isac-net.org/Resources/Standards/FCS3-1.aspx) 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](https://github.com/RGLab/openCyto) and [ggCyto](https://github.com/RGLab/ggcyto).


## What problems does CytoML solve?

CytoML allows you to:

- Import manually gated data into R from [Diva](http://www.bdbiosciences.com/us/instruments/clinical/software/flow-cytometry-acquisition/bd-facsdiva-software/m/333333/overview), [FlowJo](https://www.flowjo.com/) and [Cytobank](https://cytobank.org/).
- 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](http://www.bdbiosciences.com/us/instruments/clinical/software/flow-cytometry-acquisition/bd-facsdiva-software/m/333333/overview), [FlowJo](https://www.flowjo.com/) and [Cytobank](https://cytobank.org/).
- 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

```r
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](https://www.bioconductor.org).

- [Current BioConductor Relase](https://doi.org/doi:10.18129/B9.bioc.CytoML)

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

- [Current BioConductor Development Version](http://bioconductor.org/packages/devel/bioc/html/CytoML.html)

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

### Installing from GitHub

- [Latest GitHub Version](https://github.com/RGLab/CytoML)

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

- [Latest GitHub Release](https://github.com/RGLab/CytoML/releases)

```r
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](http://www.rglab.org/CytoML), and was prepared with version 1.7.10 of CytoML, R v3.5.0, and dependencies that can be installed by:

```r
# 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](https://cytobank.org/).


```{r, message = FALSE, warning = FALSE, error = FALSE}
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](http://www.bdbiosciences.com/us/instruments/clinical/software/flow-cytometry-acquisition/bd-facsdiva-software/m/333333/overview) workspace.

```{r, message = FALSE, warning = FALSE, error = FALSE}
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.

```{r, message = FALSE, warning = FALSE, error = FALSE}
library(flowWorkspace)
```

We can visualize the gating tree as follows:

```{r}
#get the first sample
gh <- gs[[1]]

#plot the hierarchy tree
plot(gh)
```

For more information see the [flowWorkspace](http://www.github.com/RGLab/flowWorkspace) package.

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

```{r}
#show all the cell populations(/nodes)
gs_get_pop_paths(gh)
```

We can extract the cell population statistics. 

```{r}
#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.

```{r}
#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:

```{r}
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:

```{r}
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](https://cytobank.org/) or [FlowJo](https://www.flowjo.com/)

Load something to export.

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

##### Export to Cytobank

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

##### Export to FlowJo

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

## Next Steps

See the [flowWorskspace](http://www.github.com/RGLab/flowWorkspace) 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](CODE_OF_CONDUCT.md).
  By participating in this project you agree to abide by its terms.