How to annotate data with sample tags in the Cytobank platform (tutorial)


This article walks you through an example of how to annotate data with sample tags. If you haven't already, please read the overview of sample tags for background on the subject.

If you want to follow along, look for the public Illustration Editor Example Data experiment on your Cytobank server. This experiment is a PBMC sample stimulation assay with two conditions, unstimulated and stimulated, and four healthy donor individuals.


To make a copy of the experiment for your own use, open the experiment, and Clone it without sample tags (annotations), such that you can add them yourself.

Use the links below to jump to the relevant section:

Why do we need to annotate files with sample tags?

Sample annotation is an essential step for generating the desired reports of your data analysis. In the Cytobank platform, we create illustrations based on sample tags. It is important to tag your files before creating illustrations in the Illustration editor, running statistical inference and especially before setting up a paired statistical test.

Below is an example showing how we use the sample tag information from this tutorial to generate statistical plots to compare and assess significance between two conditions.


(The 8 samples were annotated based on the individual number and condition. The median fluorescence intensity of TNFa of the CD4+ and CD8+ populations is compared between the two conditions: unstimulated (blue) and stimulated (orange). Sample tags were leveraged to lay out the illustration and to run an inference test comparing the two conditions. The resulting p-value of the paired Student’s t-test with a Bonferroni correction shows that the observed differences are statistically significantly different.)

Sample Tag Manager anatomy


(1) Sample annotation table

This table displays the FCS files as rows and the experimental variables or dimensions as columns. The sample tags or categories are annotated in a spreadsheet format. You can use the sample annotation table as a spreadsheet to copy sample tags, type to include information, etc.

Use the column headers to edit sample tag names.

Sample tag edit.gif

And to filter the displayed FCS files.

Sample tag filtering column.gif

Only files categorized as experimental or other controls, and files belonging to visible panels, are displayed in the sample annotation table. Check out these articles to learn more about file categories and panel visibility in the Cytobank platform.

(2) Add dimension

Use this menu to add a new dimension from the list of existing dimensions or to Define a custom one.

(3) Apply changes

Click on Apply changes when you want to save the sample tags version and to apply them to the rest of the Cytobank experiment.

(4) Search field

Type to filter the displayed FCS files and their associated sample tags. Delete the text or click on Clear filter to show all FCS files and sample tags again.

Sample tag filtering box.gif

(5) Undo, Redo and Undo all changes

Click Undo or Redo buttons to revert or do one change over again. Click the Undo all changes button to revert all changes to the last saved sample tags version.

(6) Bulk add tool

Click on Bulk add to add several sample tags at once and to annotate files automatically based on the filenames. Use this tool after adding the desired dimension, then enter a comma-separated list of tags and select Add tags.


A message will inform you of the number of filenames that matched each tag.


The newly added sample tags will display in the sample annotation table.


(7) Duplicate file

To duplicate an FCS file in the Cytobank platform.

(8) Export sample tags as a spreadsheet

Click here to automatically download the sample tags in a TSV file.

How to annotate data with sample tags

After cloning the experiment (if you are following the tutorial) or creating a new one, you will be directed to the Set up new experiment page. Please refer to the configure experiment setup article to select appropriate data scaling, compensation and data QC settings.

To annotate files with sample tags, click on the Sample tags menu on the blue navigation bar and select Sample Tag Manager.

In the Sample Tag Manager view, click on Add dimension to include all experimental variables. In this example we will add the dimensions named Individuals and Conditions.

Next, add the sample tag name for each dimension in the sample annotation table. You can directly type the tag name in the table cells or copy and paste from a previously existing table.

(Enter sample tags by typing the tag name in the table cell.)

Sample tag copy paste excel.gif

(Copy and paste sample tags from an existing spreadsheet.)

Once you have some sample tags included in the sample annotation table, you can use the drop-down menu to annotate new files with existing sample tags, or copy and paste them.

(Add sample tags by selecting them from the drop-down menu.)

Sample tag copy paste STM.gif

(Copy and paste sample tags from the sample annotation table.)

If your FCS files were annotated during acquisition and the sample tag information is included in the file name, you can also use the bulk add option for a faster annotation. To do so, click on Add dimension to add the experimental variables, then on Bulk add and finally enter a comma-separated list of tags.

Sample tag bulk add.gif

(Bulk add sample tags matching the FCS filename.)

Finally, click the Apply changes button and accept the changes to save the current sample tags version and to apply them to the rest of the experiment to use the sample tags in other functionalities within the Cytobank platform.

If you navigate to a different part of the experiment, such as the Experiment Summary, without clicking the Apply changes button, the Cytobank platform will notify you with the following message:


Have more questions? Submit a request.


For Research Use Only. Not for use in diagnostic procedures.


Have more questions? Submit a request