GatingStrategy Class

class flowkit.GatingStrategy

Represents a flow cytometry gating strategy, including instructions for compensation and transformation.

Public Methods:

__init__()
__repr__()	Return repr(self).
add_gate(gate, gate_path[, sample_id])	Add a gate to the gating strategy, see gates module.
is_custom_gate(sample_id, gate_name[, gate_path])	Determine if a custom gate exists for a sample ID.
get_gate(gate_name[, gate_path, sample_id])	Retrieve a gate instance by its gate ID (gate name and optional gate_path).
remove_gate(gate_name[, gate_path, ...])	Remove a gate from the gating strategy.
add_transform(transform)	Add a transform to the gating strategy, see transforms module.
get_transform(transform_id)	Retrieve transform instance from gating strategy.
add_comp_matrix(matrix)	Add a compensation matrix to the gating strategy, see transforms module.
get_comp_matrix(matrix_id)	Retrieve Matrix instance from gating strategy.
find_matching_gate_paths(gate_name)	Find all gate paths for given gate name.
get_root_gates([sample_id])	Retrieve list of root-level gate instances.
get_parent_gate_id(gate_name[, gate_path])	Retrieve the parent Gate ID for the given gate ID.
get_child_gate_ids(gate_name[, gate_path])	Retrieve list of child gate instances by their parent's gate ID.
get_gate_ids()	Retrieve the list of gate IDs (with ancestors) for the gating strategy.
get_max_depth()	Returns the max depth of the gating hierarchy.
get_gate_hierarchy([output])	Retrieve the hierarchy of gates in the gating strategy in several formats, including text, dictionary, or JSON.
export_gate_hierarchy_image(output_file_path)	Saves an image of the gate hierarchy in many common formats according to the extension given in output_file_path, including
clear_cache()	Clears all cached pre-processed events stored in the GatingStrategy.
gate_sample(sample[, cache_events, verbose])	Apply GatingStrategy to a Sample instance, returning a GatingResults instance.

---

resolver = <anytree.resolver.Resolver object>

add_gate(gate, gate_path, sample_id=None)

Add a gate to the gating strategy, see gates module. The gate ID and gate path must be unique in the gating strategy. Custom sample gates may be added by specifying an optional sample ID. Note, the gate & gate path must already exist prior to adding custom sample gates.

Parameters:

• gate – instance from a subclass of the Gate class

• gate_path – complete ordered tuple of gate names for unique set of gate ancestors

• sample_id – text string for specifying given gate as a custom Sample gate

Returns:

None

is_custom_gate(sample_id, gate_name, gate_path=None)

Determine if a custom gate exists for a sample ID.

Parameters:

• sample_id – Sample ID string

• gate_name – text string of a gate name

• gate_path – complete ordered tuple of gate names for unique set of gate ancestors. Required if gate_name is ambiguous

Returns:

Boolean value for whether the sample ID has a custom gate

get_gate(gate_name, gate_path=None, sample_id=None)

Retrieve a gate instance by its gate ID (gate name and optional gate_path). If a sample_id is specified, the custom sample gate will be returned if it exists.

Parameters:

• gate_name – text string of a gate name

• gate_path – complete ordered tuple of gate names for unique set of gate ancestors. Required if gate_name is ambiguous

• sample_id – Sample ID string to lookup custom gate. If None or not found, template gate is returned

Returns:

Subclass of a Gate object

Raises:

• GateReferenceError – if gate ID is not found in gating strategy

• QuadrantReferenceError – if gate ID references a single Quadrant (specify the QuadrantGate ID instead)

remove_gate(gate_name, gate_path=None, keep_children=False)

Remove a gate from the gating strategy. Any descendant gates will also be removed unless keep_children=True. In all cases, if a BooleanGate exists that references the gate to remove, a GateTreeError will be thrown indicating the BooleanGate must be removed prior to removing the gate.

Parameters:

• gate_name – text string of a gate name

• gate_path – complete ordered tuple of gate names for unique set of gate ancestors. Required if gate_name is ambiguous

• keep_children – Whether to keep child gates. If True, the child gates will be remapped to the removed gate’s parent. Default is False, which will delete all descendant gates.

Returns:

None

add_transform(transform)

Add a transform to the gating strategy, see transforms module. The transform ID must be unique in the gating strategy.

Parameters:

transform – instance from a subclass of the Transform class

Returns:

None

get_transform(transform_id)

Retrieve transform instance from gating strategy.

Parameters:

transform_id – String of a valid transform ID stored in the gating strategy

Returns:

Instance of a Transform subclass

add_comp_matrix(matrix)

Add a compensation matrix to the gating strategy, see transforms module. The matrix ID must be unique in the gating strategy.

Parameters:

matrix – an instance of the Matrix class

Returns:

None

get_comp_matrix(matrix_id)

Retrieve Matrix instance from gating strategy.

Parameters:

matrix_id – String of a valid Matrix ID stored in the gating strategy

Returns:

Matrix instance

find_matching_gate_paths(gate_name)

Find all gate paths for given gate name.

Parameters:

gate_name – text string of a gate name

Returns:

list of gate paths (list of tuples)

get_root_gates(sample_id=None)

Retrieve list of root-level gate instances.

Parameters:

sample_id – Sample ID string to retrieve custom gates if present. If None, template gates are returned

Returns:

list of Gate instances

get_parent_gate_id(gate_name, gate_path=None)

Retrieve the parent Gate ID for the given gate ID.

Parameters:

• gate_name – text string of a gate name

• gate_path – complete ordered tuple of gate names for unique set of gate ancestors. Required if gate_name is ambiguous

Returns:

a gate ID (tuple of gate name and gate path)

get_child_gate_ids(gate_name, gate_path=None)

Retrieve list of child gate instances by their parent’s gate ID.

Parameters:

• gate_name – text string of a gate name

• gate_path – complete ordered tuple of gate names for unique set of gate ancestors. Required if gate_name is ambiguous

Returns:

list of Gate IDs (tuple of gate name plus gate path). Returns an empty list if no child gates exist.

Raises:

GateReferenceError – if gate ID is not found in gating strategy or if gate name is ambiguous

get_gate_ids()

Retrieve the list of gate IDs (with ancestors) for the gating strategy.

Returns:

list of tuples (1st item is gate name string, 2nd item is a list of ancestor gate names)

get_max_depth()

Returns the max depth of the gating hierarchy.

get_gate_hierarchy(output='ascii', **kwargs)

Retrieve the hierarchy of gates in the gating strategy in several formats, including text, dictionary, or JSON. If output == ‘json’, extra keyword arguments are passed to json.dumps

Parameters:

output – Determines format of hierarchy returned, either ‘ascii’, ‘dict’, or ‘JSON’ (default is ‘ascii’)

Returns:

gate hierarchy as a text string or a dictionary

export_gate_hierarchy_image(output_file_path)

Saves an image of the gate hierarchy in many common formats according to the extension given in output_file_path, including

• SVG (‘svg’)

• PNG (‘png’)

• JPEG (‘jpeg’, ‘jpg’)

• TIFF (‘tiff’, ‘tif’)

• GIF (‘gif’)

• PS (‘ps’)

• PDF (‘pdf’)

Requires that `graphviz` is installed.

Parameters:

output_file_path – File path (including file name) of image

Returns:

None

clear_cache()

Clears all cached pre-processed events stored in the GatingStrategy. This is useful to reduce memory usage after analyzing large data sets. Clearing the cache will not affect any results previously retrieved.

Returns:

None

gate_sample(sample, cache_events=False, verbose=False)

Apply GatingStrategy to a Sample instance, returning a GatingResults instance.

Parameters:

• sample – an FCS Sample instance

• cache_events – Whether to cache pre-processed events (compensated and transformed). This can be useful to speed up processing of gates that share the same pre-processing instructions for the same channel data, but can consume significantly more memory space. See the related clear_cache method for additional information. Default is False.

• verbose – If True, print a line for each gate processed

Returns:

GatingResults instance