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.
pop = “+/-”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 + or -.
But sometime we want to do the downstream gating for both. By specifying
pop as +/-, 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 |
|---|---|---|---|---|---|
| * | +/- | cd3 | cd4 | mindensity |
to two rows:
| alias | pop | parent | dims | gating_method | gating_args |
|---|---|---|---|---|---|
| cd4+ | + | cd3 | cd4 | mindensity | |
| cd4- | - | cd3 | cd4 | refGate | cd3/cd4+ |
Note that the second row uses refGate which simply
copies the gate coordinates computed by mindensity in the
first row, and assign the negative sign to the pop column
indicating the population of interest is cd4 negative.
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 ++ pattern in the pop
column.
e.g
| alias | pop | parent | dims | gating_method | gating_args |
|---|---|---|---|---|---|
| T helper | +- | cd3 | cd4,cd8 | mindensity |
And the template parser will take care of the expansion automatically.
| alias | pop | parent | dims | gating_method | gating_args |
|---|---|---|---|---|---|
| cd4+ | + | cd3 | cd4 | mindensity | |
| cd8+ | + | cd3 | cd8 | mindensity | |
| T helper | +- | cd3 | cd4,cd8 | refGate | cd3/cd4+:cd3/cd8+ |
As we see, first two rows do the actual gating by
mindensity and the third row simply makes use the
coordinates of that two 1d gates (cd4+ and
cd8+) and construct a rectangleGate (T helper)
by using refGate as gating_method. And the
+ and - sign along with dimensions determines
which quadrant to keep.
pop = “+/-+/-”Apparently, we may want to get more than one quadrants by using the
same mechanism. For example, we can set pop to
+/-+/- to keep all of four quadrants.
| alias | pop | parent | dims | gating_method | gating_args |
|---|---|---|---|---|---|
| * | +/-+/- | cd3 | cd4,cd8 | mindensity |
It will be expanded to six rows:
| alias | pop | parent | dims | gating_method | gating_args |
|---|---|---|---|---|---|
| cd4+ | + | cd3 | cd4 | mindensity | |
| cd8+ | + | cd3 | cd8 | mindensity | |
| cd4+cd8+ | ++ | cd3 | cd4,cd8 | refGate | cd3/cd4+:cd3/cd8+ |
| cd4-cd8+ | -+ | cd3 | cd4,cd8 | refGate | cd3/cd4+:cd3/cd8+ |
| cd4+cd8- | +- | cd3 | cd4,cd8 | refGate | cd3/cd4+:cd3/cd8+ |
| cd4-cd8- | – | cd3 | cd4,cd8 | refGate | cd3/cd4+:cd3/cd8+ |
First two does the actual gating, and rest of four uses two 1d gates
to construct four different rectangleGates to represent
four different quadrants.
pop = “*” and alias = “A,B,C”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 assume curv1gate always returns two
gates in the order of c("cd4", "cd8"), then the population
names in alias column will be matched to these two gates
and two dummy_gate rows are generated that simply serves as
a reference to be used
as parent node of the downstream 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 |
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.
parent
=“A,B,C”)If the same gating method (or simply refGate) needs to
be applied to multiple parents, it is possible to write these into the
single row. For example,
| alias | pop | parent | dims | gating_method | gating_args |
|---|---|---|---|---|---|
| IL2+ | + | cd4,cd8 | IL2 | refGate | cd3/IL2+ |
This row is interpreted as copying the IL2 gate that has
been generated from cd3 population and applying it to
cd4 and cd8, which is equivalent to the rows
of below
| alias | pop | parent | dims | gating_method | gating_args |
|---|---|---|---|---|---|
| IL2+ | + | cd4 | IL2 | refGate | cd3/IL2+ |
| IL2+ | + | cd8 | IL2 | refGate | cd3/IL2+ |