Not an algorithm, but a framework for automated gating.

Goals

• Easily build reproducible gating pipelines.
  
• Use any gating algorithm
  • interchange any algorithm at any step (support gating plugins)
• Simplify data handling and data management.
  • Easily pass subsets of the data (cell subsets) to different gating algorithms.
• Simple(r) pipeline template definitions
  • Pipeline defined via text file (csv)
  • Templates and code are re-usable for standardized assays and data.
• Facilitate comparative analysis
  • Import manually gated data from FlowJo workspaces
• Scale to large data sets
  • HDF5 support - data sets limited by disk space not RAM.

Raw data ➙ Preprocessing ➙ Annotation ➙ Gating ➙ Statistical analysis ➙ Output

Create a gating set of manual gates.

gating_set<-parseWorkspace(ws,name="0882 Samples",path="data/FCS/",isNcdf=TRUE)

## loading R object...
## loading tree object...
## Done

Parsing 76 samples
calling c++ parser...
...

We now have gated, compensated and transformed data in an HDF5 file represented in a GatingSet object. We can save it for later use.

save_gs(gating_set,path="data/manual_gating")

saving ncdf...
saving tree object...
saving R object...
Done
To reload it, use 'load_gs' function

The archived gating set contains all the information on transformation, compensation, single-cell events, and gates and can be shared with collaborators.

We annotate our gating set from the keywords and flowrepository. We'll keep only the GAG and negative control stimulations

keyword_vars<-c("$FIL","Stim","Sample Order","EXPERIMENT NAME") #relevant keywords
pd<-data.table(getKeywords(gating_set,keyword_vars)) #extract relevant keywords to a data table
annotations<-data.table:::fread("data/workspace/pd_submit.csv") # read the annotations from flowrepository
pd<-data.frame(annotations[pd]) #data.table style merge
setnames(pd,c("Timepoint","Individual"),c("VISITNO","PTID"))
pData(gating_set)<-pd #annotate

We want to perform automated gating of this data.

• We'll clone the gating set, delete existing nodes and re-save the data as a new gating set.

auto_gating<-clone(gating_subset)
Rm("S",auto_gating)
save_gs(auto_gating,path="data/autogating",overwrite=TRUE)

list.files("data/autogating")

## [1] "NHxz3bpHGl.dat"     "NHxz3bpHGl.rds"     "file9e8620253f4.nc"

• .nc file is the HDF5 file of event-level data..
• .dat file contains the gating set representation from the C data structure.
• .rds file is an R data file that contains the R-object information.

Send it to a friend, load_gs() will read it all in and the data will be available.

Each row defines a cell population

• alias: how we refer to the population / shorthand
  
• pop: The population definition i.e. do we keep the positive (+) or negative (-) cells for a marker / pair of markers after gating.
  
• parent: The alias of the parent population on which the current population is defined
  
• dims: The dimensions / markers used to define this cell population.
• gating_method: Which gating algorithm to use.
  
• gating_args: additional arguments passed to the gating method to tweak various parameters
  
• collaseDataForGating: TRUE or FALSE. Together with groupBy will gate multiple samples with a common gate.
  
• groupBy: Specify metadata variables for combining samples (e.g. PTID)
  
• preprocessing_method: advanced use for some gating methods
  
• preprocessing_args: additional arguments

p1<-plotGate(auto_gating[[1]],c("cd8","cd4"),arrange=FALSE,
             projections=list("cd4"=c(x="CD8",y="CD4"),"cd8"=c(x="CD8",y="CD4")),
             main="Automated Gate",path=2)[[1]]
p2<-plotGate(gating_subset[[1]],c("8+","4+"),
             projections=list("4+"=c(x="CD8",y="CD4"),"8+"=c(x="CD8",y="CD4")),
             arrange=FALSE,main="Manual Gate",path=2)[[1]]

grid.arrange(arrangeGrob(p1,p2,ncol=2))

Stats and gates are comparable, could be tweaked if necessary, but importantly it's reproducible. Always generate the same result.

#Extract stats
auto_stats<-getPopStats(auto_gating,statistic="count")
manual_stats<-getPopStats(gating_subset,statistic="count")

Note Perforin is incorrectly gated in the manual analysis. Minor differences at low end, but reproducible and objective.

Automated gate set on CD57- (reference). Perforin-negative cells included in the manual gate.

Return a flowSet containing event-level data for the named cell population.

cd3_population<-getData(auto_gating,"cd3")

Plot a named cell population.

plotGate(auto_gating,"cd3")

Subset by FCS file(s).

first_ten_fcs_files<-auto_gating[1:10]

List supported gating methods (that can be used in a template).

listgtMethods()

Register a new gating or preprocessing plugin.

registerPlugins(myfunction,methodName,dependencies, "preprocessing"|"gating")

Generate a Basic GatingTemplate from a Manual Gating Hierarchy.

templateGen(gating_subset[[1]])

Just fill in the gating_method and dims to get started.

Infers a gate threshold based on the minimum density separating two major populations in a 1-D density estimate.

• Open the csv template in a new window, the definition for the live/dead gate is:

viable, viable-, singlet, AViD, mindensity, gate_range=c(500,1000)
gate_range restricts the data region where the method searches for a cutpoint.
adjust alters the smoothing (larger value = more smoothing, less bumpy)

• Play with these parameters in the gating template.
  • What happens if you remove the gate_range parameter?
  • What happens if you set adjust=0.75?

# Work with a subset of the data
auto_subset<-auto_gating[1:20] # first 20 samples
# Make changes in the template. SAVE it, then re-load it in R.
gt<-gatingTemplate("data/template/gt_080.csv")
# Remove the old gate from auto_gating
Rm("viable",auto_subset)
# Gate with the new template, stop after the viable gate (which is nonNeutro)
gating(gt,auto_subset,stop.at="nonNeutro")
# View the new result
plotGate(auto_subset,"viable")