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¶
Choose New from the toolbar above the inbox. The experiment will be created in the folder you’re looking at.
The new experiment’s summary page will be displayed with the name field automatically selected. Type a name for the new experiment.
- Optional: add tags and comments.
- Upload FCS files or import them from other experiments.
- Add any additional files by dragging and dropping into the browser window.
Creating a new folder¶
- Select the folder in which you wish to create a new folder.
- Click on New Folder in the sidebar.
- 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.
- 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 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:
- Navigate to the folder with the experiments you want to tag.
- Check the box beside each experiment to be tagged.
- 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.
- Search tags by typing in the Search box. To add/remove all the tags in the filtered list, click on select all matching.
- To add or remove existing tags, check the boxes next to them.
- 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:
- Go to the experiment summary. Tags lists the current tags for the experiment.
- To remove a tag, click the X on the tag.
- 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.
- 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 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 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 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.
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:
- 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.
- 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.
- Click on any folder in the sidebar to display its experiments.
- 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.
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||
|Only in the title||
|Only in the path||
|Only in tags||
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¶
- Click the share button in the left sidebar.
- Enter the user with whom to share:
- If you have previously shared an experiment/folder with a user, if they have previously shared an experiment/folder with you, or if they are in your domain, then enter part of their name and select them from the autocomplete.
- Otherwise, enter the user's full email address.
- 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.
- Optional: write a message to the new users, for example explaining why you are sharing the experiment with them.
- Click update.
|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.|
Removing a user from an experiment¶
- Click the share button in the left sidebar.
- Click the remove button next to the user whom you wish to remove.
- 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.
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¶
- Click the add retention policy button located on the experiment summary page.
- In the dialog that opens, enter a duration for the policy.
- Click apply.
Retention Policies may be extended by the same procedure.
CellEngine can export an experiment’s compensations, scales, gates and populations as a Gating-ML 2.0 XML file.
- On the experiment summary page, click the export Gating-ML button in the Experiment Details pod.
- 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.)
- Click export. An XML file will be downloaded.
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
- 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.
- Gating-ML does not support the Boolean xor operator, whereas this operator can be used via CellEngine's API. During export, xor operators will be converted to a combination of other Boolean operators.