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_compensation(
    name: str,
    channels: List[str],
    spill_matrix: List[float],
) -> Compensation

create_compensation(
    name: str, *, dataframe: DataFrame
) -> Compensation

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_ellipse_gate(
    *args, create_population: Literal[True], **kwargs
) -> Tuple[EllipseGate, Population]

create_ellipse_gate(
    *args, create_population: Literal[False], **kwargs
) -> EllipseGate

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_polygon_gate(
    *args, create_population: Literal[True], **kwargs
) -> Tuple[PolygonGate, Population]

create_polygon_gate(
    *args, create_population: Literal[False], **kwargs
) -> PolygonGate

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_quadrant_gate(
    *args, create_population: Literal[True], **kwargs
) -> Tuple[QuadrantGate, List[Population]]

create_quadrant_gate(
    *args, create_population: Literal[False], **kwargs
) -> QuadrantGate

Create a QuadrantGate.

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

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

create_range_gate(
    *args, create_population: Literal[True], **kwargs
) -> Tuple[RangeGate, Population]

create_range_gate(
    *args, create_population: Literal[False], **kwargs
) -> RangeGate

Create a RangeGate.

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

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

create_rectangle_gate(
    *args, create_population: Literal[True], **kwargs
) -> Tuple[RectangleGate, Population]

create_rectangle_gate(
    *args, create_population: Literal[False], **kwargs
) -> RectangleGate

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=[])

import_resources(src_experiment_id, what, channel_map={}, dst_population_id=None)

Imports resources from another experiment.

Parameters:

Name	Type	Description	Default
src_experiment_id	str	The ID of the source experiment.	required
what	ImportOpts	A dictionary with the following optional keys: - populations: Whether to import populations. - illustrations: Whether to import illustrations (True = all, False = none), or a list of specific illustration IDs to import. - compensations: Whether to import compensations (True = all, False = none), or a list of specific compensation IDs to import. - savedStatisticExports: Whether to import saved statistic exports (True = all, False = none), or a list of specific export IDs to import. - annotations: Whether to import annotations (True = all, False = none), or a list of specific annotation names to import.	required
channel_map	Dict[str, str]	A dictionary Object mapping channel names from source experiment to destination experiment for imported gates. Gates using channels not present in the map or with channels set to the value "" will not be imported. Populations are only imported if all of their required gates are imported (i.e. the entire set of parents must be imported). This does not affect compensation import.	{}
dst_population_id	str	The ID of the destination parent population. If not provided, the root population is used.	None

Use experiment.gates and similar to access the imported resources. Note: If it would be useful for this method to return the imported resources, open a GitHub issue letting us know.

save_revision(description)

Saves a revision of the experiment. The new revision will be the last entry in the revisions property.

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.