Skip to content

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 

create(
    experiment_id: str,
    x_channel: str,
    y_channel: str,
    name: str,
    x1: float,
    x2: float,
    y1: float,
    y2: float,
    label: List[float] = [],
    gid: Optional[str] = None,
    locked: bool = False,
    tailored_per_file: bool = False,
    fcs_file_id: Optional[str] = None,
    fcs_file: Optional[str] = None,
    create_population: Literal[True] = True,
    parent_population_id: Optional[str] = None,
) -> Tuple[RectangleGate, Population]

create(
    experiment_id: str,
    x_channel: str,
    y_channel: str,
    name: str,
    x1: float,
    x2: float,
    y1: float,
    y2: float,
    label: List[float] = [],
    gid: Optional[str] = None,
    locked: bool = False,
    tailored_per_file: bool = False,
    fcs_file_id: Optional[str] = None,
    fcs_file: Optional[str] = None,
    create_population: Literal[False] = False,
) -> RectangleGate

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 

create(
    experiment_id: str,
    x_channel: str,
    y_channel: str,
    name: str,
    vertices: List[List[float]],
    label: List[float] = [],
    gid: Optional[str] = None,
    locked: bool = False,
    tailored_per_file: bool = False,
    fcs_file_id: Optional[str] = None,
    fcs_file: Optional[str] = None,
    create_population: Literal[True] = True,
    parent_population_id: Optional[str] = None,
) -> Tuple[PolygonGate, Population]

create(
    experiment_id: str,
    x_channel: str,
    y_channel: str,
    name: str,
    vertices: List[List[float]],
    label: List[float] = [],
    gid: Optional[str] = None,
    locked: bool = False,
    tailored_per_file: bool = False,
    fcs_file_id: Optional[str] = None,
    fcs_file: Optional[str] = None,
    create_population: Literal[False] = False,
) -> PolygonGate

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 

create(
    experiment_id: str,
    x_channel: str,
    y_channel: str,
    name: str,
    center: List[float],
    angle: float,
    major: float,
    minor: float,
    label: List[float] = [],
    gid: Optional[str] = None,
    locked: bool = False,
    tailored_per_file: bool = False,
    fcs_file_id: Optional[str] = None,
    fcs_file: Optional[str] = None,
    create_population: Literal[True] = True,
    parent_population_id: Optional[str] = None,
) -> Tuple[EllipseGate, Population]

create(
    experiment_id: str,
    x_channel: str,
    y_channel: str,
    name: str,
    center: List[float],
    angle: float,
    major: float,
    minor: float,
    label: List[float] = [],
    gid: Optional[str] = None,
    locked: bool = False,
    tailored_per_file: bool = False,
    fcs_file_id: Optional[str] = None,
    fcs_file: Optional[str] = None,
    create_population: Literal[False] = False,
) -> EllipseGate

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 

create(
    experiment_id: str,
    x_channel: str,
    name: str,
    x1: float,
    x2: float,
    y: float = 0.5,
    label: List[float] = [],
    gid: Optional[str] = None,
    locked: bool = False,
    tailored_per_file: bool = False,
    fcs_file_id: Optional[str] = None,
    fcs_file: Optional[str] = None,
    create_population: Literal[True] = True,
    parent_population_id: Optional[str] = None,
) -> Tuple[RangeGate, Population]

create(
    experiment_id: str,
    x_channel: str,
    name: str,
    x1: float,
    x2: float,
    y: float = 0.5,
    label: List[float] = [],
    gid: Optional[str] = None,
    locked: bool = False,
    tailored_per_file: bool = False,
    fcs_file_id: Optional[str] = None,
    fcs_file: Optional[str] = None,
    create_population: Literal[False] = False,
) -> RangeGate

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 

create(
    experiment_id: str,
    x_channel: str,
    name: str,
    x: float,
    y: float,
    labels: List[List[float]] = [],
    gid: Optional[str] = None,
    gids: Optional[List[str]] = None,
    locked: bool = False,
    tailored_per_file: bool = False,
    fcs_file_id: Optional[str] = None,
    fcs_file: Optional[str] = None,
    create_population: Literal[True] = True,
    parent_population_id: Optional[str] = None,
) -> Tuple[SplitGate, List[Population]]

create(
    experiment_id: str,
    x_channel: str,
    name: str,
    x: float,
    y: float,
    labels: List[List[float]] = [],
    gid: Optional[str] = None,
    gids: Optional[List[str]] = None,
    locked: bool = False,
    tailored_per_file: bool = False,
    fcs_file_id: Optional[str] = None,
    fcs_file: Optional[str] = None,
    create_population: Literal[False] = False,
) -> SplitGate

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 

create(
    experiment_id: str,
    x_channel: str,
    y_channel: str,
    name: str,
    x: float,
    y: float,
    labels: List[List[float]] = [],
    skewable: bool = False,
    angles: List[float] = [0, pi / 2, pi, 3 * pi / 2],
    gid: Optional[str] = None,
    gids: Optional[List[str]] = None,
    locked: bool = False,
    tailored_per_file: bool = False,
    fcs_file_id: Optional[str] = None,
    fcs_file: Optional[str] = None,
    create_population: Literal[True] = True,
    parent_population_id: Optional[str] = None,
) -> Tuple[QuadrantGate, List[Population]]

create(
    experiment_id: str,
    x_channel: str,
    y_channel: str,
    name: str,
    x: float,
    y: float,
    labels: List[List[float]] = [],
    skewable: bool = False,
    angles: List[float] = [0, pi / 2, pi, 3 * pi / 2],
    gid: Optional[str] = None,
    gids: Optional[List[str]] = None,
    locked: bool = False,
    tailored_per_file: bool = False,
    fcs_file_id: Optional[str] = None,
    fcs_file: Optional[str] = None,
    create_population: Literal[False] = False,
) -> QuadrantGate

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(...)]