1 How to write a csv gating template

The openCyto package is uses a spreadsheet to compose the gating schemes. Basically each row corresponds to one population node in the gating hierarchy tree. However sometime it is verbose to describe every single population. So here we will explain how to make the template more succinct to easier to compose by using pop and alias pattern.

1.1 pop = “A+/-”

For the 1d/2d gating function, we are normally interested in either positive(representing cell events within gate) or negative(or negated, representing cell events outside of the gate) by setting pop column in the form of A+ or A-. But sometime we want to do the downstream gating for both. By specifying pop as A+/-, the template parser will expand it into two rows internally.

For example, this row will be expanded automatically

alias pop parent dims gating_method gating_args
* cd4+/- cd3 cd4 mindensity

to two rows:

alias pop parent dims gating_method gating_args
cd4+ cd4+ cd3 cd4 mindensity
cd4- cd4- cd3 cd4 refGate cd3/cd4+
Note tha t the s econd row uses ` refGate` which s imply copies the gate coordinates computed by mindensity in the first row,
and assi gn the negative sign to the pop colum n indicating the population of interest is cd4 negative.

1.2 pop = “++”

Often time we need to apply 1d gating function on two dimensions separately and then use the two cutting points to construct rectangleGate to capture the cell events falling into one particular quadrant on the 2-d projections For example, T helper cells are usually represented as CD4+CD8-. Instead of writing three rows in the template, simply using A+B+ pattern in the pop column.
e.g

alias pop parent dims gating_method gating_args
T helper cd4+cd8- cd3 cd4,cd8 mindensity
And the tem plate parse r will ta ke care of the expansion a utomatically.
alias pop parent dims gating_method gating_args
cd4+ cd4+ cd3 cd4 mindensity
cd8+ cd8+ cd3 cd8 mindensity
T helper cd4+cd8- cd3 cd4,cd8 refGate cd3/cd4+:cd3/cd8+
As we see, first two r ows do th e actual g ating by `minden sityand the third row simply makes use the coordinates of that two 1d gates (cd4+andcd8+`) and
construct a `rectangle Gate` (T helper) by using refGate as gating_method. And the + and - sign along with dimensions determines which quadrant to keep.

It is now prefered to omit the dimension information from pop since dims already provides it. It is especially helpful when the dimension itself contains special characters +/- (e.g. HLA-DR and BDCA-2), parser then can’t tell the correct quadrant pattern (i.e. HLA-DR+BDCA-2).

1.3 pop = “+/-+/-”

Apparently, we may want to get more than one quadrants by using the same mechanism. For example, we can set pop to +/-+/-(or CD4+/-CD8+/-) to keep all of four quadrants.

alias pop parent dims gating_method gating_args
* +/-+/- cd3 cd4,cd8 mindensity
It will be expand ed to six rows:
alias pop parent dims gating_method gating_args
cd4+ cd4+ cd3 cd4 mindensity
cd8+ cd8+ cd3 cd8 mindensity
cd4+cd8+ cd4+cd8+ cd3 cd4,cd8 refGate cd3/cd4+:cd3/cd8+
cd4-cd8+ cd4-cd8+ cd3 cd4,cd8 refGate cd3/cd4+:cd3/cd8+
cd4+cd8- cd4+cd8- cd3 cd4,cd8 refGate cd3/cd4+:cd3/cd8+
cd4-cd8- cd4-cd8- cd3 cd4,cd8 refGate cd3/cd4+:cd3/cd8+
First two d oes the act ual gatin g, and res t of four uses t wo 1d gates to construct four different rectangleGates to represent
four differ ent quadran ts.

1.4 pop = “*"

So far, we’ve been talking about the gating functions that only returns one gate object( S4 class that extends flowCore::filter). If we want to apply the gating function(e.g. curv2filter or flowClust::tmixFilter) that returns more than one gates, we can set pop to * and specify multiple population names within alias with comma-separated characters.

alias pop parent dims gating_method gating_args
CD4,CD8 * cd3 cd4,cd8 curv2gate
Here we as sume ` curv1gate ` always r eturns two gat es in the order of c("cd4", "cd8"), then the population names in alias column
will be ma tched to these two gates and two `dummy_g ate` rows are generated that simply serves as a reference to be used
as `parent ` node of the d ownstream gates.
alias pop parent dims gating_method gating_args
CD4,CD8 * cd3 cd4,cd8 curv2gate
CD4 cd3 cd4,cd8 dummy_gate cd3/CD4,CD8
CD8 cd3 cd4,cd8 dummy_gate cd3/CD4,CD8

1.5 pop = “*" and alias = “*"

If we don’t know how many gates will be returned by curv2gate or the order of gates are undetermined, thus we will not able to name these populations. As long as they are not used as parent nodes for the further gating (i.e. terminal gates), we can simply set alias to * .

alias pop parent dims gating_method gating_args
* * cd3 cd4,cd8 curv2gate

This will not be expanded in the openCyto framework. However, multiple populations will be generated and added to the GatingSet object. They are named by the filterId slot of filter objects.