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 tens of thousands 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.

Creating and Organizing Experiments

Experiments can be organized using folders and tags. Folders and experiments can be created, moved and shared from your inbox.

Creating a new experiment

Experiment Creation

  1. Choose New from the toolbar above the inbox. The experiment will be created in the folder you're looking at.

    experiment toolbar

  2. The new experiment's summary page will be displayed with the name field automatically selected. Type a name for the new experiment.

  3. Optional: add tags and comments.
  4. Upload FCS files or import them from other experiments.
  5. Add any additional files by dragging and dropping into the browser window.

Creating a new folder

Howto

  1. Select the folder in which you wish to create a new folder.
  2. Click on New Folder in the sidebar. inbox sidebar
  3. In the pop-up box, type a name for the folder and click OK.

Other options in the sidebar allow you to organize folders by sharing, moving, deleting, and renaming them.

Tip

  • When in a folder, you can organize your experiments. Right-click on an experiment in the inbox to rename, duplicate, share, delete, or move it.

Tags

Tags can be added to your experiments to help with organization. Tags are displayed in folders next to your experiments, and in the experiment summary page. CellEngine saves tags you've used before to make it easier to maintain consistent labeling.

Adding and removing tags

Tags can be added to or removed from multiple experiments in the same folder. To tag from a folder:

Howto

  1. Navigate to the folder with the experiments you want to tag.
  2. Check the box beside each experiment to be tagged.
  3. Click on Tag in the toolbar above the experiments. Existing tags will be shown in a dropdown with checkboxes. The checkbox will be unchecked, checked, or indeterminate to indicate whether the tag is applied to none, all, or some of the selected experiments.
  4. Search tags by typing in the Search box. To add/remove all the tags in the filtered list, click on tag all select all matching.
  5. To add or remove existing tags, check the boxes next to them.
  6. To make a new tag, click on Create New. Type in the tag name, then click on Create. The new tag will automatically be applied to all the experiments selected.

To add or remove a tag from within an experiment, follow these steps:

Howto

  1. Go to the experiment summary. Tags lists the current tags for the experiment.
  2. To remove a tag, click the X on the tag.
  3. To add a tag, click on Start typing. Existing tags will be shown in a drop-down list. Click on a tag to add it, or type a new tag name and press enter.

Filtering Experiments

  • If you have many experiments in a folder, it can be helpful to narrow your search.
  • To filter by name and tags, click on filter icon Filter on this column in the Name column. In the search box, type to filter experiments by name and tags.
  • To filter by tags only, click on tag icon Match tags. Choose a tag from the list or type to narrow down the tag list.
  • You can also filter by researcher. In the Primary Researcher column, click on filter icon Filter on this column. Type the researcher's name in the Search text box to narrow the list.

Navigation is accomplished by a navigation toolbar at the top of each page, and a contextual sidebar to allow easy access to your experiments.

The navigation bar is located at the top of the page, just under the search bar.

navigation bar

It displays the path to the folder, experiment or illustration you’re working on. You can click on any part of the path to move there.

The navigation bar can also be used to rename parts of your experiment. To rename part of the path:

Howto

  1. Click on your current path to rename the folder, experiment, or illustration you're currently working on, or double-click on any other part of the path to select its name.
  2. Type in the new name.

The left-hand sidebar helps with navigation between folders or within an experiment. If you’re in the inbox, the sidebar displays the folder structure.

Howto

  1. Click on any folder in the sidebar to display its experiments.
  2. Click on the arrow next to a folder in the sidebar to expand/hide its contents.

When you are in an experiment, the sidebar allows you to navigate to different parts of an experiment, including gating, annotations, panels, illustrations, algorithms, population export or statistics export.

You can also share, discard, and duplicate your experiment from the sidebar. Duplicated experiments replicate all but the revisions or retention policies of the source. If you need to duplicate only a portion of an experiment (e.g. compensations), consider importing.

Searching Experiments

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. Optional: 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.

See Also