Skip to content

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

import_experiment_resources(experiment_id, src_experiment_id, what, channel_map, dst_population_id)

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)

save_experiment_revision(_id, description)

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