API Client

The CellEngine APIClient object is the low-level interface between the CellEngine API and entities in the Python SDK. After authenticating, you may either use the APIClient directly or interact with the higher-level SDK entities.

Assuming you have instantiated the APIClient object:

import cellengine
client = cellengine.APIClient("username")
# Password: <enter your password here>
# Alternatively, set CELLENGINE_PASSWORD in your environment

then the following sequences of commands are equivalent:

exp = client.get_experiment(name="my experiment")
fcsfile = client.get_fcs_file(experiment_id=exp._id, name="my fcs file")

exp = cellengine.Experiment.get(name="my experiment")
fcsfile = cellengine.FcsFile.get(experiment_id=exp._id, name="my fcs file")

exp = cellengine.Experiment.get(name="my experiment")
fcsfile = exp.get_fcs_file(name="my fcs file")

The APIClient provides higher-level methods for interacting with CellEngine. It also provides _get, _post, _patch, and _delete methods for low-level interaction with the CellEngine API. If there is a higher-level feature that's missing, please feel free to open an Issue in GitHub.

Properties

• base_url (to override the cellengine.com URL, generally for internal use)
• username
• password
• token
• user_id
• admin
• flags
• authenticated
• cache_info
• cache_clear

Methods

cellengine.APIClient

Bases: BaseAPIClient

authenticated = self._authenticate(self.username, self.password, self.token) instance-attribute

base_url = os.environ.get('CELLENGINE_BASE_URL', 'https://cellengine.com') instance-attribute

cache_clear = self._get_id_by_name.cache_clear instance-attribute

cache_info = self._get_id_by_name.cache_info instance-attribute

password = password or os.environ.get('CELLENGINE_PASSWORD') instance-attribute

token = token or os.environ.get('CELLENGINE_AUTH_TOKEN') instance-attribute

user_id = None instance-attribute

username = username or os.environ.get('CELLENGINE_USERNAME') instance-attribute

apply_tailoring(experiment_id, gate, fcs_file_ids)

Tailor a gate to a file or files.

clone_experiment(_id, props={})

create_fcs_file(experiment_id, body)

Creates an FCS file by copying, concatenating and/or subsampling existing file(s) from this or other experiments. Can be used to import files from other experiments.

delete_attachment(experiment_id, _id=None, name=None)

Delete an attachment

delete_entity(experiment_id, entity_type, _id)

delete_experiment(_id)

Marks the experiment as deleted.

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

delete_folder(_id)

Marks the folder as deleted.

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

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

Deletes a gate or a tailored gate family.

Specify the top-level gid when working with compound gates (specifying the gid of a sector (i.e. one listed in model.gids) will result in no gates being deleted). If _id is specified, only that gate will be deleted, regardless of the other parameters specified. May be called as a static method from cellengine.Gate or from an Experiment instance.

Parameters:

Name	Type	Description	Default
experiment_id	str	ID of experiment.	required
_id	Optional[str]	ID of the gate to delete.	None
gid	Optional[str]	ID of gate family to delete.	None
exclude	Optional[str]	Gate ID to exclude from deletion. Deprecated. Use the untailoring API instead.	None

Example

cellengine.Gate.delete_gate(experiment_id, gid = [gate family ID])
# or
experiment.delete_gate(_id = [gate ID])

Returns:

Type	Description
None	None

delete_gates(experiment_id, ids)

download_attachment(experiment_id, _id=None, name=None)

Download an attachment

download_fcs_file(experiment_id, fcs_file_id, **kwargs)

Download events for a specific FcsFile

Parameters:

Name	Type	Description	Default
experiment_id	str	ID of the experiment	required
fcs_file_id	str	ID of the FcsFile	required
**kwargs	Any	compensatedQ (bool): If true, applies the compensation specified in compensationId to the exported events. For TSV format, the numerical values will be the compensated values. For FCS format, the numerical values will be unchanged, but the file header will contain the compensation as the spill string (file-internal compensation). compensationId (str, optional): Required if populationId is specified. Compensation to use for gating. headers (bool): For TSV format only. If true, a header row containing the channel names will be included. original (bool): If true, the returned file will be byte-for-byte identical to the originally uploaded file. If false or unspecified (and compensatedQ is false, populationId is unspecified and all subsampling parameters are unspecified), the returned file will contain essentially the same data as the originally uploaded file, but may not be byte-for-byte identical. For example, the byte ordering of the DATA segment will always be little-endian and any extraneous information appended to the end of the original file will be stripped. This parameter takes precedence over compensatedQ, populationId and the subsampling parameters. populationId (str): If provided, only events from this population will be included in the output file. postSubsampleN (int): Randomly subsample the file to contain this many events after gating. postSubsampleP (float): Randomly subsample the file to contain this percent of events (0 to 1) after gating. preSubsampleN (int): Randomly subsample the file to contain this many events before gating. preSubsampleP (float): Randomly subsample the file to contain this percent of events (0 to 1) before gating. seed: (int): Seed for random number generator used for subsampling. Use for deterministic (reproducible) subsampling. If omitted, a pseudo-random value is used. addEventNumber (bool): Add an event number column to the exported file. When a populationId is specified (when gating), this number corresponds to the index of the event in the original file.	{}

get_attachment(experiment_id, _id=None, name=None)

get_attachments(experiment_id)

get_compensation(experiment_id, _id=None, name=None)

get_compensations(experiment_id, as_dict=False)

get_experiment(_id=None, name=None)

get_experiments()

get_fcs_file(experiment_id, _id=None, name=None)

get_fcs_files(experiment_id, as_dict=False)

get_folder(_id=None, name=None)

get_folders()

get_gate(experiment_id, _id, as_dict=False)

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.

get_gates(experiment_id, as_dict=False)

get_plot(experiment_id, fcs_file_id, plot_type, x_channel, y_channel, z_channel=None, population_id=None, compensation=0, properties=None, raw=False)

get_population(experiment_id, _id=None, name=None)

get_populations(experiment_id)

get_scaleset(experiment_id)

Get the scaleset for an experiment.

get_statistics(experiment_id, statistics, channels, q=None, annotations=False, compensation_id=UNCOMPENSATED, fcs_file_ids=None, format='json', layout=None, percent_of='PARENT', population_ids=None)

Request Statistics from CellEngine.

Parameters:

Name	Type	Description	Default
experiment_id	str	ID of the experiment.	required
statistics	List[str]	Statistics to calculate. Any of "mean", "median", "quantile", "mad" (median absolute deviation), "geometricmean", "eventcount", "cv", "stddev" or "percent" (case-insensitive).	required
q	int	quantile (required for "quantile" statistic)	None
channels	List[str]	for "mean", "median", "geometricMean", "cv", "stddev", "mad" or "quantile" statistics. Names of channels to calculate statistics for.	required
annotations	bool	Include file annotations in output (defaults to False).	False
compensation_id	Union[Compensations, str]	Compensation to use for gating and statistics calculation. Defaults to uncompensated. In addition to a compensation ID, three special constants may be used: UNCOMPENSATED, FILE_INTERNAL or PER_FILE.	UNCOMPENSATED
fcs_file_ids	Optional[List[str]]	FCS files to get statistics for. If omitted, statistics for all non-control FCS files will be returned.	None
format	str	str: One of "TSV (with[out] header)", "CSV (with[out] header)" or "json" (default), "pandas", case-insensitive.	'json'
layout	Optional[str]	str: The file (TSV/CSV) or object (JSON) layout. One of "tall-skinny", "medium", or "short-wide".	None
percent_of	Optional[Union[str, List[str]]]	str or List[str]: Population ID or array of population IDs. If omitted or the string "PARENT", will calculate percent of parent for each population. If a single ID, will calculate percent of that population for all populations specified by population_ids. If a list, will calculate percent of each of those populations.	'PARENT'
population_ids	Optional[List[str]]	List[str]: List of population IDs. Defaults to ungated.	None

Returns:

Name	Type	Description
statistics	Union[Dict, str, DataFrame]	Dict, String, or pandas.Dataframe

post_compensation(experiment_id, body)

post_experiment(experiment)

Create a new experiment on CellEngine.

post_folder(folder)

Create a new folder on CellEngine.

post_gate(experiment_id, body, params={})

post_gates(experiment_id, body, params={})

post_population(experiment_id, population)

update_entity(experiment_id, _id, entity_type, body)

update_experiment(_id, body)

update_folder(_id, body)

update_gate_family(experiment_id, gid, body={})

upload_attachment(experiment_id, filepath, filename=None)

Upload an attachment

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(experiment_id, filepath_or_data, filename=None)

Upload an FCS file to CellEngine

Parameters:

Name	Type	Description	Default
filepath_or_data	Union[str, BytesIO]	Local path to FCS file.	required
filename	Optional[str]	Optionally, specify a new name for the file.	None

Returns:

Type	Description
FcsFile	The newly-uploaded FcsFile