Gates

CellEngine API: Gates

Gates are geometric shapes that define boundaries within which events (cells) must be contained to be considered part of a population. Each gate type has its own implementation of the abstract Gate class. Do not instantiate the base Gate class directly.

All gate types share some required and optional arguments, which are documented on the base Gate class. Gate-specific arguments are documented in each gate type.

Properties

Properties are the snake_case equivalent of those documented on the CellEngine API unless otherwise noted.

Gate ABC and Methods

Although you should not instantiate the Gate class, each gate type will inherit the methods below.

`cellengine.resources.gate.Gate`

Do not construct directly; use the Experiment.create_*_gate and __Gate.create() methods.

`experiment_id: str` `property`

`fcs_file_id: Union[str, None]` `property`

`gid: str` `property`

`id: str` `property`

Alias for _id.

`locked: bool` `property` `writable`

`model: Dict` `property`

`tailored_per_file: bool` `property`

`type: str` `property`

`x_channel: str` `property`

`y_channel: Union[str, None]` `property`

`apply_tailoring(fcs_file_ids)`

Apply this gate's tailoring (copy its geometry) to other FCS files.

`create_many(gates)` `classmethod`

`delete()`

`untailor()`

`update()`

Save changes to this Gate to CellEngine.

`update_gate_family(experiment_id, gid, body)` `staticmethod`

Update a given field for a gate family.

Warning: This method does not modify local versions of gates; use the .update() method to ensure changes are reflected locally.

Parameters:

Name	Type	Description	Default
`experiment_id`	`str`	ID of experiment	required
`gid`	`str`	ID of gate family to modify	required
`body`	`Dict`	camelCase properties to update	required

Returns:

Type	Description
`None`	Raises a warning if no gates are modified, else None

Gate Types

`cellengine.resources.gate.RectangleGate`

Bases: SimpleGate

`create(experiment_id, x_channel, y_channel, name, x1, x2, y1, y2, label=[], gid=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None)` `classmethod`

Creates a rectangle gate.

Parameters:

Name	Type	Description	Default
`experiment_id`	`str`	The ID of the experiment.	required
`x_channel`	`str`	The name of the x channel to which the gate applies.	required
`y_channel`	`str`	The name of the y channel to which the gate applies.	required
`name`	`str`	The name of the gate	required
`x1`	`float`	The first x coordinate (after the channel's scale has been applied).	required
`x2`	`float`	The second x coordinate (after the channel's scale has been applied).	required
`y1`	`float`	The first y coordinate (after the channel's scale has been applied).	required
`y2`	`float`	The second y coordinate (after the channel's scale has been applied).	required
`label`	`List[float]`	Position of the label. Defaults to the midpoint of the gate.	`[]`
`gid`	`Optional[str]`	Group ID of the gate, used for tailoring. If this is not specified, then a new Group ID will be created. Must be specified when creating a tailored gate.	`None`
`locked`	`bool`	Prevents modification of the gate via the web interface.	`False`
`tailored_per_file`	`bool`	Whether or not this gate is tailored per FCS file.	`False`
`fcs_file_id`	`Optional[str]`	ID of FCS file, if tailored per file. Use `None` for the global gate in a tailored gate group. If specified, do not specify `fcs_file`.	`None`
`fcs_file`	`Optional[str]`	Name of FCS file, if tailored per file. An attempt will be made to find the file by name. If zero or more than one file exists with the name, an error will be thrown. Looking up files by name is slower than using the ID, as this requires additional requests to the server. If specified, do not specify `fcs_file_id`.	`None`
`create_population`	`bool`	If true, a corresponding population will be created and returned in a tuple with the gate.	`True`
`parent_population_id`	`Optional[str]`	Use with `create_population` to specify the population below which to create this population.	`None`

Returns:

Type	Description
`Union[RectangleGate, Tuple[RectangleGate, Population]]`	A RectangleGate if `create_population` is False, or a Tuple with the gate and population if `create_population` is True.

Examples:

gate, pop = experiment.create_rectangle_gate(
    x_channel="FSC-A",
    y_channel="FSC-W",
    name="my gate",
    x1=12.502,
    x2=95.102,
    y1=1020,
    y2=32021.2)

`cellengine.resources.gate.PolygonGate`

Bases: SimpleGate

`create(experiment_id, x_channel, y_channel, name, vertices, label=[], gid=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None)` `classmethod`

Creates a polygon gate.

Parameters:

Name	Type	Description	Default
`experiment_id`	`str`	The ID of the experiment.	required
`x_channel`	`str`	The name of the x channel to which the gate applies.	required
`y_channel`	`str`	The name of the y channel to which the gate applies.	required
`name`	`str`	The name of the gate	required
`vertices`	`List[List[float]]`	List of coordinates, like `[[x,y], [x,y], ...]`.	required
`label`	`List[float]`	Position of the label. Defaults to the midpoint of the gate.	`[]`
`gid`	`Optional[str]`	Group ID of the gate, used for tailoring. If this is not specified, then a new Group ID will be created. To create a tailored gate, the gid of the global tailored gate must be specified.	`None`
`locked`	`bool`	Prevents modification of the gate via the web interface.	`False`
`tailored_per_file`	`bool`	Whether or not this gate is tailored per FCS file.	`False`
`fcs_file_id`	`Optional[str]`	ID of FCS file, if tailored per file. Use `None` for the global gate in a tailored gate group. If specified, do not specify `fcs_file`.	`None`
`fcs_file`	`Optional[str]`	Name of FCS file, if tailored per file. An attempt will be made to find the file by name. If zero or more than one file exists with the name, an error will be thrown. Looking up files by name is slower than using the ID, as this requires additional requests to the server. If specified, do not specify `fcs_file_id`.	`None`
`create_population`	`bool`	If true, a corresponding population will be created and returned in a tuple with the gate.	`True`
`parent_population_id`	`Optional[str]`	Use with `create_population` to specify the population below which to create this populations.	`None`

Returns:

Type	Description
`Union[PolygonGate, Tuple[PolygonGate, Population]]`	A PolygonGate if `create_population` is False, or a Tuple with the gate and populations if `create_population` is True.

Examples:

gate, pop = experiment.create_polygon_gate(
    x_channel="FSC-A",
    y_channel="FSC-W",
    name="my gate",
    vertices=[[1,4], [2,5], [3,6]])

`cellengine.resources.gate.EllipseGate`

Bases: SimpleGate

`create(experiment_id, x_channel, y_channel, name, center, angle, major, minor, label=[], gid=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None)` `classmethod`

Creates an ellipse gate.

Parameters:

Name	Type	Description	Default
`experiment_id`	`str`	The ID of the experiment.	required
`x_channel`	`str`	The name of the x channel to which the gate applies.	required
`y_channel`	`str`	The name of the y channel to which the gate applies.	required
`name`	`str`	The name of the gate	required
`center`	`List[float]`	The x, y centerpoint of the gate.	required
`angle`	`float`	The angle of the ellipse in radians.	required
`major`	`float`	The major radius of the ellipse.	required
`minor`	`float`	The minor radius of the ellipse.	required
`label`	`List[float]`	Position of the label. Defaults to the midpoint of the gate.	`[]`
`gid`	`Optional[str]`	Group ID of the gate, used for tailoring. If this is not specified, then a new Group ID will be created. To create a tailored gate, the gid of the global tailored gate must be specified.	`None`
`locked`	`bool`	Prevents modification of the gate via the web interface.	`False`
`tailored_per_file`	`bool`	Whether or not this gate is tailored per FCS file.	`False`
`fcs_file_id`	`Optional[str]`	ID of FCS file, if tailored per file. Use `None` for the global gate in a tailored gate group. If specified, do not specify `fcs_file`.	`None`
`fcs_file`	`Optional[str]`	Name of FCS file, if tailored per file. An attempt will be made to find the file by name. If zero or more than one file exists with the name, an error will be thrown. Looking up files by name is slower than using the ID, as this requires additional requests to the server. If specified, do not specify `fcs_file_id`.	`None`
`create_population`	`bool`	If true, a corresponding population will be created and returned in a tuple with the gate.	`True`
`parent_population_id`	`Optional[str]`	Use with `create_population` to specify the population below which to create this populations.	`None`

Returns:

Type	Description
`Union[EllipseGate, Tuple[EllipseGate, Population]]`	If `create_population` is `True`, a tuple containing an EllipseGate and a list of two Populations; otherwise, an EllipseGate.

Examples:

gate, pop = experiment.create_ellipse_gate(
    x_channel="FSC-A",
    y_channel="FSC-W",
    name="my gate",
    x=260000,
    y=64000,
    angle=0,
    major=120000,
    minor=70000)

`cellengine.resources.gate.RangeGate`

Bases: SimpleGate

`create(experiment_id, x_channel, name, x1, x2, y=0.5, label=[], gid=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None)` `classmethod`

Creates a range gate.

Parameters:

Name	Type	Description	Default
`experiment_id`	`str`	The ID of the experiment.	required
`x_channel`	`str`	The name of the x channel to which the gate applies.	required
`name`	`str`	The name of the gate	required
`x1`	`float`	The first x coordinate (after the channel's scale has been applied).	required
`x2`	`float`	The second x coordinate (after the channel's scale has been applied).	required
`y`	`float`	Position of the horizontal line between the vertical lines	`0.5`
`label`	`List[float]`	Position of the label. Defaults to the midpoint of the gate.	`[]`
`gid`	`Optional[str]`	Group ID of the gate, used for tailoring. If this is not specified, then a new Group ID will be created. To create a tailored gate, the gid of the global tailored gate must be specified.	`None`
`locked`	`bool`	Prevents modification of the gate via the web interface.	`False`
`tailored_per_file`	`bool`	Whether or not this gate is tailored per FCS file.	`False`
`fcs_file_id`	`Optional[str]`	ID of FCS file, if tailored per file. Use `None` for the global gate in a tailored gate group. If specified, do not specify `fcs_file`.	`None`
`fcs_file`	`Optional[str]`	Name of FCS file, if tailored per file. An attempt will be made to find the file by name. If zero or more than one file exists with the name, an error will be thrown. Looking up files by name is slower than using the ID, as this requires additional requests to the server. If specified, do not specify `fcs_file_id`.	`None`
`create_population`	`bool`	If true, a corresponding population will be created and returned in a tuple with the gate.	`True`
`parent_population_id`	`Optional[str]`	Use with `create_population` to specify the population below which to create this populations.	`None`

Returns:

Type	Description
`Union[RangeGate, Tuple[RangeGate, Population]]`	If `create_population` is `True`, a tuple containing a RangeGate and a list of two Populations; otherwise, a RangeGate.

Examples:

gate, pop = experiment.create_range_gate(
    x_channel="FSC-A",
    name="my gate",
    x1=12.502,
    x2=95.102)

`cellengine.resources.gate.SplitGate`

Bases: CompoundGate

`create(experiment_id, x_channel, name, x, y=0.5, labels=[], gid=None, gids=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None)` `classmethod`

Creates a split gate.

Split gates have two sectors (right and left), each with a unique gid and name.

Parameters:

Name	Type	Description	Default
`experiment_id`	`str`	The ID of the experiment.	required
`x_channel`	`str`	The name of the x channel to which the gate applies.	required
`name`	`str`	The name of the gate.	required
`x`	`float`	The x coordinate of the center point (after the channel's scale has been applied).	required
`y`	`float`	The relative position from 0 to 1 of the horizontal dashed line extending from the center point.	`0.5`
`labels`	`List[List[float]]`	Positions of the quadrant labels. A list of two length-2 lists in the order: L, R. These are set automatically to the top corners.	`[]`
`gid`	`Optional[str]`	Group ID of the gate, used for tailoring. If this is not specified, then a new Group ID will be created. To create a tailored gate, the gid of the global tailored gate must be specified.	`None`
`gids`	`Optional[List[str]]`	Group IDs of each sector, assigned to `model.gids`.	`None`
`locked`	`bool`	Prevents modification of the gate via the web interface.	`False`
`tailored_per_file`	`bool`	Whether or not this gate is tailored per FCS file.	`False`
`fcs_file_id`	`Optional[str]`	ID of FCS file, if tailored per file. Use `None` for the global gate in a tailored gate group. If specified, do not specify `fcs_file`.	`None`
`fcs_file`	`Optional[str]`	Name of FCS file, if tailored per file. An attempt will be made to find the file by name. If zero or more than one file exists with the name, an error will be thrown. Looking up files by name is slower than using the ID, as this requires additional requests to the server. If specified, do not specify `fcs_file_id`.	`None`
`create_population`	`bool`	If true, corresponding populations will be created and returned in a tuple with the gate.	`True`
`parent_population_id`	`Optional[str]`	Use with `create_population` to specify the population below which to create these populations.	`None`

Returns:

Type	Description
`Union[SplitGate, Tuple[SplitGate, List[Population]]]`	A SplitGate if `create_population` is False, or a Tuple with the gate and populations if `create_population` is True.

Examples:

# With automatic creation of the corresponding populations:
gate, pops = experiment.create_split_gate(
    experiment_id,
    x_channel="FSC-A",
    name="my gate",
    x=144000, y=0.5,
    parent_population_id="...")
# Without
gate = experiment.create_split_gate(
    experiment_id,
    x_channel="FSC-A",
    name="my gate",
    x=144000, y=0.5,
    create_population=False)

`cellengine.resources.gate.QuadrantGate`

Bases: CompoundGate

`create(experiment_id, x_channel, y_channel, name, x, y, labels=[], skewable=False, angles=[0, pi / 2, pi, 3 * pi / 2], gid=None, gids=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None)` `classmethod`

Creates a quadrant gate.

Quadrant gates have four sectors (upper-right, upper-left, lower-left, lower-right), each with a unique gid and name.

Parameters:

Name	Type	Description	Default
`experiment_id`	`str`	The ID of the experiment.	required
`x_channel`	`str`	The name of the x channel to which the gate applies.	required
`y_channel`	`str`	The name of the y channel to which the gate applies.	required
`name`	`str`	The name of the gate	required
`x`	`float`	The x coordinate of the center point (after the channel's scale has been applied).	required
`y`	`float`	The y coordinate (after the channel's scale has been applied).	required
`labels`	`List[List[float]]`	Positions of the quadrant labels. A list of four length-2 vectors in the order UR, UL, LL, LR. These are set automatically to the plot corners.	`[]`
`skewable`	`bool`	Whether the quadrant gate is skewable.	`False`
`angles`	`List[float]`	List of the four angles of the quadrant demarcations	`[0, pi / 2, pi, 3 * pi / 2]`
`gid`	`Optional[str]`	Group ID of the gate, used for tailoring. If this is not specified, then a new Group ID will be created. To create a tailored gate, the gid of the global tailored gate must be specified.	`None`
`gids`	`Optional[List[str]]`	Group IDs of each sector, assigned to `model.gids`.	`None`
`locked`	`bool`	Prevents modification of the gate via the web interface.	`False`
`tailored_per_file`	`bool`	Whether or not this gate is tailored per FCS file.	`False`
`fcs_file_id`	`Optional[str]`	ID of FCS file, if tailored per file. Use `None` for the global gate in a tailored gate group. If specified, do not specify `fcs_file`.	`None`
`fcs_file`	`Optional[str]`	Name of FCS file, if tailored per file. An attempt will be made to find the file by name. If zero or more than one file exists with the name, an error will be thrown. Looking up files by name is slower than using the ID, as this requires additional requests to the server. If specified, do not specify `fcs_file_id`.	`None`
`create_population`	`bool`	If true, corresponding populations will be created and returned in a tuple with the gate.	`True`
`parent_population_id`	`Optional[str]`	Use with `create_population` to specify the population below which to create these populations.	`None`

Returns:

Type	Description
`Union[QuadrantGate, Tuple[QuadrantGate, List[Population]]]`	If `create_population` is `True`, a tuple containing the QuadrantGate and a list of four Populations; otherwise, a QuadrantGate.

Examples:

gate, pops = experiment.create_quadrant_gate(
    x_channel="FSC-A",
    y_channel="FSC-W",
    name="my gate",
    x=160000,
    y=200000)

Gate Models

Gates have a model property, which is a nested dict object. For convenience, the model property has dot-indexing for getting and setting properties. For instance:

> gate = experiment.gates[0]
> gate.model
Munch({'polygon':
    Munch({'vertices': [
        [4.68957, 2.90929],
        [5.23152, 5.77464],
        [7.76064, 5.956],
        [8.59164, 4.65026],
        [6.71287, 2.32896]
    ]}),
    'locked': False,
    'label': [7.62844, 6.19701]
})

> gate.model.polygon.vertices
[[4.68957, 2.90929],
 [5.23152, 5.77464],
 [7.76064, 5.956],
 [8.59164, 4.65026],
 [6.71287, 2.32896]]

You can set the values of these properties. You must explicitly call the update method for these changes to be saved to CellEngine.

> gate.model.locked
True

> gate.model.locked = False
> gate.update()
> gate.model.locked
False

You may set invalid values, but update will fail with an API error:

> gate.model.locked = "orange"
> gate.model.locked
"orange"

> gate.update()
APIError: CellEngine API: status code 400 != 200 for URL
https://cellengine.com/api/v1/experiments/.../gates/...
-- "locked" must be a Boolean.

Creating Gates

Gates may be created singly or in bulk.

Create a single new gate using kwargs:

# using a method on Experiment
exp.create_ellipse_gate(
    x_channel="FSC-A",
    y_channel="FSC-W",
    name="my gate",
    x=260000,
    y=64000,
    angle=0,
    major=120000,
    minor=70000
    )

# using a classmethod
from cellengine import EllipseGate
gate = EllipseGate.create(
    experiment_id=exp._id,
    # the same kwargs
    )
gate.post()

Post gates in bulk

When creating many gates, build the gates in a list, then save them in bulk to CellEngine. For instance:

gates = []
gates.append(
    EllipseGate.create(
        experiment_id=exp._id,
        # args, kwargs
        )
    )
gates.append(
    RectangleGate.create(
        experiment_id=exp._id,
        # args, kwargs
        )
    )

Gate.bulk_create(gates)
# returns [EllipseGate(...), RectangleGate(...)]

Gates

Properties

Gate ABC and Methods

cellengine.resources.gate.Gate

experiment_id: str property

fcs_file_id: Union[str, None] property

gid: str property

id: str property

locked: bool property writable

model: Dict property

tailored_per_file: bool property

type: str property

x_channel: str property

y_channel: Union[str, None] property

apply_tailoring(fcs_file_ids)

create_many(gates) classmethod

delete()

untailor()

update()

update_gate_family(experiment_id, gid, body) staticmethod

Gate Types

cellengine.resources.gate.RectangleGate

create(experiment_id, x_channel, y_channel, name, x1, x2, y1, y2, label=[], gid=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None) classmethod

cellengine.resources.gate.PolygonGate

create(experiment_id, x_channel, y_channel, name, vertices, label=[], gid=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None) classmethod

cellengine.resources.gate.EllipseGate

create(experiment_id, x_channel, y_channel, name, center, angle, major, minor, label=[], gid=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None) classmethod

cellengine.resources.gate.RangeGate

create(experiment_id, x_channel, name, x1, x2, y=0.5, label=[], gid=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None) classmethod

cellengine.resources.gate.SplitGate

create(experiment_id, x_channel, name, x, y=0.5, labels=[], gid=None, gids=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None) classmethod

cellengine.resources.gate.QuadrantGate

create(experiment_id, x_channel, y_channel, name, x, y, labels=[], skewable=False, angles=[0, pi / 2, pi, 3 * pi / 2], gid=None, gids=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None) classmethod

Gate Models

Creating Gates

Create a single new gate using kwargs:

Post gates in bulk

`cellengine.resources.gate.Gate`

`experiment_id: str` `property`

`fcs_file_id: Union[str, None]` `property`

`gid: str` `property`

`id: str` `property`

`locked: bool` `property` `writable`

`model: Dict` `property`

`tailored_per_file: bool` `property`

`type: str` `property`

`x_channel: str` `property`

`y_channel: Union[str, None]` `property`

`apply_tailoring(fcs_file_ids)`

`create_many(gates)` `classmethod`

`delete()`

`untailor()`

`update()`

`update_gate_family(experiment_id, gid, body)` `staticmethod`

`cellengine.resources.gate.RectangleGate`

`create(experiment_id, x_channel, y_channel, name, x1, x2, y1, y2, label=[], gid=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None)` `classmethod`

`cellengine.resources.gate.PolygonGate`

`create(experiment_id, x_channel, y_channel, name, vertices, label=[], gid=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None)` `classmethod`

`cellengine.resources.gate.EllipseGate`

`create(experiment_id, x_channel, y_channel, name, center, angle, major, minor, label=[], gid=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None)` `classmethod`

`cellengine.resources.gate.RangeGate`

`create(experiment_id, x_channel, name, x1, x2, y=0.5, label=[], gid=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None)` `classmethod`

`cellengine.resources.gate.SplitGate`

`create(experiment_id, x_channel, name, x, y=0.5, labels=[], gid=None, gids=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None)` `classmethod`

`cellengine.resources.gate.QuadrantGate`

`create(experiment_id, x_channel, y_channel, name, x, y, labels=[], skewable=False, angles=[0, pi / 2, pi, 3 * pi / 2], gid=None, gids=None, locked=False, tailored_per_file=False, fcs_file_id=None, fcs_file=None, create_population=True, parent_population_id=None)` `classmethod`