cytoflow.operations.category

Convert a binary gating strategy into a categorical condition.

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

class cytoflow.operations.category.CategoryOp

Bases: HasStrictTraits

Convert a binary gating strategy into a categorical condition.

Binary gating strategies are quite common while doing manual gating. For example, a gating strategy might be “if a monocyte is CD64-, CD19+, and CD3-, then it is a B cell; if it is CD64+, it is a macrophage”. Analyzing these data sets is often easier if one can specify a set of gate memberships, for example making a categorical variable with the values B_Cell and Macrophage.

If the gating strategy is strictly hierarchical, then you can use HierarchyOp to accomplish this easily. For more complicated situations, there is CategoryOp. CategoryOp is configured with a dict that maps query strings to categories. pandas.DataFrame.query is called on each query string in turn; the rows from Experiment.data that are returned are assigned the corresponding category in the new categorical condition that is created. These subsets must be mutually exclusive, a requirement which is enforced by the operation.

Any event that is in none of the subsets is set to a default value, which defaults to Unknown.

name

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

Type:

Str

subsets

The dictionary of query strings and their corresponding categories.

Type:

Dict(Str : 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 = 'Y2_really_high',
...                        channel = 'Y2-A',
...                        threshold = 30000).apply(ex)

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

Define the hierarchical gating scheme.

>>> ex4 = flow.CategoryOp(name = "BO",
...                     subsets = {"Y2_high == False" : "Low",
...                                "Y2_really_high == True" : "High"},
...                     default = "Medium").apply(ex3)

Plot the new categories.

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

apply(experiment)

Computes the membership for each subset and assign the new 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.