In RGLab/opencytoCL: A Command Line Interface to OpenCyto

OpenCyto command line tools

A thin wrapper around the opencyto framework leveraging littler.

Run simple flow cytometery processing tasks using opencyto from the command line.

Notes

Currently openCyto command line tools work with Linux and Mac OS X

OpenCyto command line tools expects well standardized and annotated data free of typos in keywords, markers and channels.

Errors? Bugs? Feature Requrests?

Open an issue, provide a reproducible example.

Install OpenCyto Command Line Tools

To install the package run the following in R:

library(devtools)
install_github("RGLab/opencytoCL")

You will need all the dependencies:

• openCyto
• optparse
• littler

Linux and MacOS X

Then, in R:

install_openCytoCL()

Usage

For help, at the command prompt, type:

```{bash, comment = "",size="small",tidy=TRUE} opencyto -h

### parse
Import a FlowJo workspace and related FCS files and create a GatingSet.

#### options

`<workspace>` the location of the workspace

`<fcs_read_from>` the location of the fcs files

`<save_to>` the name of the gating set to save

`--group=<group_number>` option to specify the group number to import. Print all group names using `load` (see below).

`--annotate=<keywords>` optionally annotate by importing keywords. Keywords should be passed in as a quoted, comma separated list. If parsing FCS files, the keywords are taken from the FCS files.  If parsing a workspace, the keywords are taken from the workspace. Spaces in keywords should be replaced with `:`.

`--stats` Extract population statistics and write them to a file.

### load
Load a FlowJo workspace and print the sample groups in therein.

#### options

`--gs=<gatingset>` the name of the gating set to load. Created using `parse` (see above) or `process` (see below) 

### gate
Gate a GatingSet using a template, saving the results. Optionally extract population statistics. Any existing gates in the GatingSet are removed. 

#### options

`--gs=<gatingset>`  A GatingSet on which to perform automated gating.

`--template=<template>`  The name of an openCyto template csv file.

`--stats`  Extract population statistics and write them to a file.

### process

`<fcs_read_from>` location of files to process

`<save_to>` name of gating set to save to

`--compensate` perform compensation using the matrix in the FCS files.

`--transform [<parameters>]` Transform parameters using the default biexponential transformation. Parameters are passed in as a comma separated list, e.g. `--transform FL1-A,FL2-A,FL3-A`

`--rscript=<rscript>` if additional processing needs to be done, pass in an R script. The script can work with the GatingSet variable `gs`. It is run after `compensate` and `transform`.

`--gs=<gatingset>` optionally read from a GatingSet rather than FCS files. Can be combined with `--rscript`. GatingSet data are already compensated and transformed.

# Examples

Install `flowWorkspaceData` from BioConductor.

```r
if(!library(flowWorkspaceData,logical.return = TRUE)){
        source("https://bioconductor.org/biocLite.R")
        biocLite("flowWorkspaceData")
}

Create a gating set from FCS files.

fcs_path = system.file(package="flowWorkspaceData","extdata")
tmp = tempdir()
try(file.remove(list.files("/tmp/cytotrol",full=TRUE)))
try(file.remove("/tmp/cytotrol"))
file.copy(list.files(path=fcs_path,pattern="CytoTrol.*",full=TRUE),to = tmp)

system(command=paste0("opencyto process ",tmp,"  /tmp/cytotrol --compensate --transform B710-A,R660-A,R780-A,V450-A,V545-A,G560-A,G780-A --annotate='$FIL'"))

Next, run command line opencyto to process FCS files into a compensated and transformed gatings set.

```{sh eval=FALSE,echo=TRUE,results="hide"} opencyto process /Library/Frameworks/R.framework/Versions/3.4/Resources/library/flowWorkspaceData/extdata /tmp/cytotrol_gatingset --compensate --transform --annotate="$FIL"

```{sh eval=FALSE}
Loading opencyto.
All FCS files have the same following channels:
FSC-A
FSC-H
FSC-W
SSC-A
B710-A
R660-A
R780-A
V450-A
V545-A
G560-A
G780-A
Time
write CytoTrol_CytoTrol_1.fcs to empty cdf slot...
write CytoTrol_CytoTrol_2.fcs to empty cdf slot...
done!
write CytoTrol_CytoTrol_1.fcs to empty cdf slot...
write CytoTrol_CytoTrol_2.fcs to empty cdf slot...
..done!
Transforming B710-A R660-A R780-A V450-A V545-A G560-A G780-A
saving ncdf...
saving tree object...
saving R object...
Done
To reload it, use 'load_gs' function

Exiting.

Our gating set now lives at /tmp/cytotrol.

Create a gating set from a FlowJo workspace file.

manual_xml = list.files(fcs_path,pattern="manual.xml",full=TRUE)

The FlowJo xml file describing the manually gated data in flowWorskpaceData is at r manual_xml. We can parse it and extract cell population statistics.

system(paste0("opencyto parse ",manual_xml))

try(file.remove(list.files("/tmp/cytotrol_manual",full=TRUE)))
try(file.remove("/tmp/cytotrol_manual"),silent=TRUE)

```{sh eval=FALSE} Loading opencyto.

Found sample groups 1. All Samples 2. B-cell 3. DC 4. T-cell 5. Thelper 6. Treg Parse using: opencyto parse /Library/Frameworks/R.framework/Versions/3.4/Resources/library/flowWorkspaceData/extdata/manual.xml --group= Workspace not parsed.

We see a number of sample groups. We'll load the T-cell group (4).

```r
try(file.remove(list.files("/tmp/cytotrol_manual",full=TRUE)))
try(file.remove("/tmp/cytotrol_manual"),silent=TRUE)

file.remove(files = list.files(path = getwd(),pattern = "Rtmp.*\\.csv",full.names=TRUE))

system(command=paste0("opencyto parse ",manual_xml," ",fcs_path,"  /tmp/cytotrol_manual --stats --group=4"))

```{sh ,eval=FALSE} Loading opencyto.

Found sample groups 1. All Samples 2. B-cell 3. DC 4. T-cell 5. Thelper 6. Treg Parsing group 4 from /Library/Frameworks/R.framework/Versions/3.4/Resources/library/flowWorkspaceData/extdata Parsing 2 samples mac version of flowJo workspace recognized. Creating ncdfFlowSet... All FCS files have the same following channels: FSC-A FSC-H FSC-W SSC-A B710-A R660-A R780-A V450-A V545-A G560-A G780-A Time done! loading data: /Library/Frameworks/R.framework/Versions/3.4/Resources/library/flowWorkspaceData/extdata/CytoTrol_CytoTrol_1.fcs Compensating gating ... write CytoTrol_CytoTrol_1.fcs_119531 to empty cdf slot... loading data: /Library/Frameworks/R.framework/Versions/3.4/Resources/library/flowWorkspaceData/extdata/CytoTrol_CytoTrol_2.fcs Compensating gating ... write CytoTrol_CytoTrol_2.fcs_115728 to empty cdf slot... done! saving ncdf... saving tree object... saving R object... Done To reload it, use 'load_gs' function

Done! Exiting.

The cell population statistics are stored in the local directory:

```r
getwd()

files = list.files(path = getwd(),pattern = "Rtmp.*\\.csv",full.names=TRUE)
if(length(files)==1){
    stats = data.table::fread(input = files)
    head(stats)
}

#clean up afterwards
file.remove(files = list.files(path = getwd(),pattern = "Rtmp.*\\.csv",full.names=TRUE))

RGLab/opencytoCL documentation built on May 16, 2019, 10:05 a.m.