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 = “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. |
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).
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. |
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 |
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.