Skip to content

Experiments

Experiments are the primary container for your analysis. They contain your FCS files, attachments, annotations, gates, illustrations and all other analysis information.

FAQ: I'm running a multi-day study. Should I put each day in a separate experiment?

CellEngine can analyze experiments with 10,000s of files. You should put files that you want to compare into the same experiment. You can upload and analyze files as they are acquired over the course of days, months or years.

Organization and Searching

Experiments can be organized using folders and tags. Folders and experiments can be created, moved and shared from your inbox. Tags can be assigned to and removed from experiments either from the inbox or from an experiment's detail page.

The inbox search defaults to searching experiment titles, paths and tags. You can search specific fields and experiment comments using combinations of these search operators:

What you can search Example
The title, path and tags splenocytes mouse (all terms, any order)
"mouse splenocytes" (exact phrase)
Only in the title title:(splenocytes mouse) (all terms, any order)
title:splenocytes title:mouse (all terms, any order)
title:"mouse splenocytes" (exact phrase)
Only in the path path:(validation cohort1) (all terms, any order)
path:validation path:cohort1 (all terms, any order)
path:"validation cohort1" (exact folder name)
Only in tags tag:(splenocytes mouse) (all terms, any order, across all tags)
tag:splenocytes tag:mouse (all terms, any order, across all tags)
tag:"mouse splenocytes" (exact phrase in one tag)
In comments comments:(splenocytes mouse) (all terms, any order)
comments:splenocytes comments:mouse (all terms, any order)
comments:"mouse splenocytes" (exact phrase)

Sharing Experiments

By default, experiments are only visible to you. You can share with other users following the steps below. See Access Management for additional information.

Permissions are inherited from folders. For example, if you grant another user the "Basic read/write" role on a folder, that user will be able to view and modify all experiments and sub-folders in that folder.

Sharing with specific users

Howto

  1. Click the share button in the left sidebar.
  2. Enter two or more letters from another user's name or email address, then select the user from the autocomplete. Repeat for any additional users.
  3. Select the access level. A brief description of each level is provided in the table below and shown when you hover over the options in the sharing dialog.
  4. Optionally, write a message to the new users, for example explaining why you are sharing the experiment with them.
  5. Click update.
Role Description
Limited read-only Can view experiment, but not save a copy or download files. Can view folder.
Read-only Can view and save a copy of experiment and download files. If a user wants to modify the experiment, they will have to save their own copy first.
Basic read/write Can modify experiment or folder, but not delete it or share it. This is the suggested role to provide to other users if you want them to have read/write access.
Full read/write Can modify, delete and share experiment or folder. This is the default role assigned to you when you create a new experiment or folder.

Sharing and Domains

If you are in a domain, the sharing dialog will only autocomplete users in your same domain. If you want to share an experiment with a user outside of your domain, you must enter their full e-mail address. Additionally, you must have the experiment.changePermissionExternal permission.

Removing a user from an experiment

Howto

  1. Click the share button in the left sidebar.
  2. Click the remove button next to the user whom you wish to remove.
  3. Click update.

Experiment Revisions and Audit Trail

Experiment revisions are complete snapshots of an entire experiment, including gates, compensation matrices, annotations and illustrations. They cannot be modified or deleted. Snapshots are ideal for locking an analysis once you are done with an analysis.

To create a new revision, click save revision on the experiment summary page. To view a revision, click on the row in the revisions table.

For more information and use in 21 CFR 11-compliant workflows, see 21 CFR 11 Compliance.

Retention Policies

You can set a Retention Policy on an experiment to govern how long the experiment must be retained before it can be deleted. Keep the following in mind:

  • Once you create a Retention Policy, it cannot be deleted.
  • Retention Policies can be extended.
  • Retention Policies only block deletion of experiments and folders; they do not prevent you from adding new experiments to a folder, nor from modifying existing experiments. To create permanent records, Retention Policies can be used in conjunction with Experiment Revisions, which are immutable, permanent snapshots of experiments.

Creating a Retention Policy

Howto

  1. Click the add retention policy button located on the experiment summary page.
  2. In the dialog that opens, enter a duration for the policy.
  3. Click apply.

Retention Policies may be extended by the same procedure.

Exporting Gating-ML

CellEngine can export an experiment's compensations, scales, gates and populations as a Gating-ML 2.0 XML file.

Howto

  1. On the experiment summary page, click the export Gating-ML button in the Experiment Details pod.
  2. In the dialog box, select global gates to export global gates, or a specific FCS file to export the gates tailored to that file. (See limitations below for more information.)
  3. Click export. An XML file will be downloaded.

Limitations

The Gating-ML 2.0 format has several limitations to be aware of:

  • There is no standardized way to communicate the name of gates, populations or compensations matrices (only a unique ID is standardized). CellEngine encodes resource names in a non-standard "name" attribute.
  • There is no standardized way to communicate which gates apply to which FCS files (i.e. gate tailoring). CellEngine lets you either export the global gates, or export the tailored gates for a specific FCS file (along with any non-tailored gates).
  • Gating-ML does not allow detector names and channel names to be the same if compensation is applied. As such, channel names are prefixed with an underscore ("_") if the experiment's active compensation is set to a custom compensation matrix.
  • Gating-ML does not support skewed quadrant gates. During export, skewed quadrant gates will be orthogonal.

Additionally, CellEngine does not currently support Gating-ML export of all Boolean populations or populations using linked gates.