Experiments

CellEngine API: Experiments

An Experiment is the primary unit of organization in CellEngine and contains FCS files, gates, populations, etc. For a list of accessible properties, see Properties.

Methods are available for common access and transformations on the Experiment. Most methods available from the APIClient are available on an Experiment, with the first param experiment_id implicitly passed as the current experiment's ID.

Properties

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

Methods

cellengine.resources.experiment.Experiment

The main container for an analysis. Don't construct directly; use Experiment.create or Experiment.get.

Not all properties have full support in the Python toolkit. Please open an issue if you need to use a property that is not supported.

active_compensation: Union[Compensations, str] property writable

analysis_source_experiment: Union[str, None] property

analysis_task: Union[str, None] property

attachments: List[Attachment] property

List all attachments on the experiment.

clone_source_experiment: Union[str, None] property

color_spec: List[Tuple[str, Tuple[Union[str, None], float]]] property writable

comments: List[Dict[str, Any]] property writable

Comments for experiment.

Defaults to overwrite; append new comments with experiment.comments.append(dict) with the form:

dict = {
    "insert": "some text",
    "attributes": {"bold": False, "italic": False, "underline": False}
}

compensations: List[Compensation] property

List all compensations on the experiment.

created: datetime property

data: Dict[str, Any] property writable

data_order: List[str] property writable

deep_updated: datetime property

deleted: Union[datetime, None] property writable

fcs_files: List[FcsFile] property

List all FCS files on the experiment.

gates: List[Gate] property

List all gates on the experiment.

id: str property

Alias for _id.

locked: bool property writable

name: str property writable

palettes: Dict[str, Any] property writable

path: List[str] property writable

per_file_compensations_enabled: bool property writable

permissions: List[Dict[str, Any]] property

populations: List[Population] property

List all populations in the experiment.

primary_researcher: Dict[str, Any] property writable

When setting this value, use the user's _id.

retention_policy: Dict[str, Any] property

revision_source_experiment: Union[str, None] property

revisions: List[Dict[str, Any]] property

saved_statistics_exports: List[Dict[str, Any]] property writable

scaleset: ScaleSet property

Gets the experiment's ScaleSet

sorting_spec: Dict[str, List[Union[str, None]]] property writable

tags: List[str] property writable

uploader: Dict[str, Any] property

clone(props={})

Saves a deep copy of the experiment and all of its resources, including attachments, FCS files, gates and populations.

Parameters:

Name	Type	Description	Default
props	Dict[str, Any]	Optional keys are: name (str): The name to give the new experiment. Defaults to "[Original Experiment]-1" path (List[str]): Array of folder IDs comprising the path.	{}

Returns:

Name	Type	Description
Experiment	Experiment	A deep copy of the experiment.

create(name=None, comments=None, uploader=None, primary_researcher=None, tags=[], path=[]) staticmethod

Creates a new experiment.

Parameters:

Name	Type	Description	Default
name	Optional[str]	Defaults to "Untitled Experiment".	None
comments	Optional[str]	Defaults to None.	None
uploader	Optional[str]	Defaults to the authenticated user.	None
primary_researcher	Optional[str]	Defaults to the authenticated user.	None
tags	List[str]	Defaults to empty list.	[]
path	List[str]	List of folder IDs comprising the path. Defaults to [] (root).	[]

Returns:

Type	Description
Experiment	The created Experiment.

create_compensation(name, channels=None, spill_matrix=None, dataframe=None)

Create a new compensation.

Specify either dataframe or channels and spill_matrix.

Parameters:

Name	Type	Description	Default
name	str	The name of the compensation.	required
channels	List[str]	The names of the channels to which this compensation matrix applies.	None
spill_matrix	List[float]	The row-wise, square spillover matrix. The length of the array must be the number of channels squared.	None
dataframe	DataFrame	A square pandas DataFrame with channel names in [df.index, df.columns].	None

create_ellipse_gate(*args, create_population=True, **kwargs)

Create an EllipseGate.

Accepts all args and kwargs available for EllipseGate.create().

create_gates(gates)

Save a collection of gate objects.

create_polygon_gate(*args, create_population=True, **kwargs)

Create a PolygonGate.

Accepts all args and kwargs available for PolygonGate.create().

create_population(population)

Create a population.

Parameters:

Name	Type	Description	Default
population	dict	The population to create. Use the ComplexPopulationBuilder to construct a complex population.	required

Examples:

experiment.create_population({
    "name": name,
    "terminalGateGid": GID,
    "parentId": parent._id,
    "gates": json.dumps({"$and": AND_GATES})
})

Returns:

Type	Description
Population	The new population.

create_quadrant_gate(*args, create_population=True, **kwargs)

Create a QuadrantGate.

Accepts all args and kwargs available for QuadrantGate.create().

create_range_gate(*args, create_population=True, **kwargs)

Create a RangeGate.

Accepts all args and kwargs available for RangeGate.create().

create_rectangle_gate(*args, create_population=True, **kwargs)

Create a RectangleGate.

Accepts all args and kwargs available for RectangleGate.create().

create_split_gate(*args, create_population=True, **kwargs)

Create a SplitGate.

Accepts all args and kwargs available for SplitGate.create().

delete()

Marks the experiment as deleted.

Deleted experiments are permanently deleted after approximately 7 days. Until then, deleted experiments can be recovered.

delete_attachment(_id=None, name=None)

Delete an attachment from this experiment.

delete_gate(_id=None, gid=None, exclude=None)

Delete a gate or gate family. See the APIClient for more information.

delete_gates(ids)

Deletes multiple gates provided a list of _ids.

download_attachment(_id=None, name=None)

Get a specific attachment.

get(_id=None, name=None) staticmethod

get_attachment(_id=None, name=None)

get_compensation(_id=None, name=None)

Get a specific compensation.

get_fcs_file(_id=None, name=None)

Get a specific FCS file.

get_gate(_id)

Get a specific gate.

Gates cannot be retrieved by name because all gates in a group of tailored gates have the same name, and because compound gates have a names property instead of a name property. Instead, you can filter the list of gates as follows to find a simple (not compound) gate:

[g for g in experiment.gates if g.name == "my gate"]

get_population(_id=None, name=None)

Get a specific population.

get_scaleset()

get_statistics(statistics, channels, q=None, annotations=True, compensation_id=UNCOMPENSATED, fcs_file_ids=None, format='pandas', layout='medium', percent_of='PARENT', population_ids=[])

undelete()

Clears a scheduled deletion.

update()

Save the specified changes to CellEngine and update this instance with the new values on success.

Example:

experiment.name = "New Name"
experiment.update()

upload_attachment(filepath, filename=None)

Upload an attachment to this experiment.

Parameters:

Name	Type	Description	Default
filepath	str	Local path to file to upload.	required
filename	str	Optionally, specify a new name for the file.	None

Returns:

Type	Description
Attachment	The newly uploaded Attachment.

upload_fcs_file(filepath, filename=None)

Upload an FCS file to this experiment.