cytoflow.operations.hierarchy

Convert a hierarchical gating strategy into a categorical condition.

HierarchyOp – Given an ordered list of gate names and their values, create a categorical variable with values set by gate membership.

class cytoflow.operations.hierarchy.HierarchyOp

Bases: HasStrictTraits

Convert a hierarchical (binary) gating strategy into a categorical condition.

Hierarchical gating strategies are quite common when doing manual gating. For example, an 8-stain panel can separate monocytes into macrophages, B cells, NK cells, NKT cells, T cells, DCs, and neutrophils – but then, because these states are mutually exclusive, a reasonable question is “how much of each are there?” Cytoflow can define these gates, but because it does not have any concept of nested gates, plotting and analyzing this gating strategy can be challenging, particularly in the GUI.

HierarchyOp converts a list of gates into a categorical variable to enable straightforward analysis. For example, monocytes stained with CD64, CD3 and CD19 can differentiate between macrophages and B cells. A user defines a ThresholdOp gate to separate CD64+ cells (macrophages) from the rest of the events, then they use a PolygonOp to distinguish the CD19+/CD3- cells (B cells) from everything else. HierarchyOp can take these two gates and create a categorical condition with the values Macrophages, B_Cells, and Unknown.

The operation is set up by providing a list of conditions, values for those conditions, and the category that condition indicates. Figuring out an event’s category is done by evaluating the hierarchical gates in order. For each event, the first condition/value pair is considered. If that event has that value, its new category is set accordingly. If not, then the next gate in the list is considered. If the event is a member in none of the gates, it receives the category listed in the default attribute.

name

The operation name. Used to name the new condition in the experiment that’s created by apply.

Type:

Str

gates

The ordered list of gates that implement the gating hierarchy. Each three-tuple has the following format:

• Str - the name of the gating operation. (Must be a key in Experiment.conditions and a column in Experiment.data)

• Any - the value that the gate has to have to indicate membership in this class.

• Str - the name of this class’s category, to put in the new condition.

Type:

List(Tuple(Str, Any, Str))

default

The name that unclassified events will have in the new categorical condition.

Type:

Str (default = “Unknown”)

Examples

Make a little data set.

>>> import cytoflow as flow
>>> import_op = flow.ImportOp()
>>> import_op.tubes = [flow.Tube(file = "Plate01/RFP_Well_A3.fcs",
...                              conditions = {'Dox' : 10.0}),
...                    flow.Tube(file = "Plate01/RFP_Well_A6.fcs",
...                              conditions = {'Dox' : 1.0})]
>>> import_op.conditions = {'Dox' : 'float'}
>>> ex = import_op.apply()

Create two threshold gates, simulating a hierarchical gating scheme.

>>> ex2 = flow.ThresholdOp(name = 'B1_high',
...                        channel = 'B1-A',
...                        threshold = 500).apply(ex)

>>> ex3 = flow.ThresholdOp(name = 'Y2_high',
...                        channel = 'Y2-A',
...                        threshold = 300).apply(ex2)

Define the hierarchical gating scheme.

>>> ex4 = flow.HierarchyOp(name = "Cell_Type",
...                        gates = [("B1_high", True, "B1_high_cells"),
...                                 ("Y2_high", True, "Y2_high_cells")]).apply(ex3)

Plot the new categories.

>>> flow.ScatterplotView(xchannel = "B1-A",
...                      xscale = "log",
...                      ychannel = "Y2-A",
...                      yscale = "log",
...                      huefacet = "Cell_Type").plot(ex4)

apply(experiment)

Computes the membership at each level of the hierarchy and assigns the condition’s value accordingly.

Parameters:

experiment (Experiment) – the old Experiment to which this operation is applied

Returns:

a new Experiment, the same as experiment but with a new condition of type category with the same name as the operation name. The value of the condition is the hierarchy subset that the event was assigned to, or left to the default value otherwise.

Return type:

Experiment

Raises:

CytoflowOpError – if for some reason the operation can’t be applied to this experiment. The reason is in the args attribute.