Exporting and importing Sample Tags: annotate files by spreadsheet


Besides the typical way of annotating files with Sample Tags, Cytobank supports applying Sample Tags to files via spreadsheet. This can accelerate the annotation process in certain cases and is useful for creating templates for repeat experiments.


How to import / export Sample Tags by spreadsheet

In order to use this feature, you first need a template for your particular experiment to fill out. Navigate to your experiment and select Actions > Export > Export Sample Tags:



Note that the Sample Tags export will reflect the current state of the Tags in the Experiment. If you have already annotated your files, then the Sample Tags spreadsheet will export in an annotated format (useful for templating). The resulting spreadsheet will appear as below for an Experiment with no Sample Tags assigned to files:


(note, "Plate" and "FCS File Category" may be assigned automatically upon upload of files to Cytobank, depending on the dataset)


Open the spreadsheet. Sample Tags can be simultaneously created and assigned by entering character strings into the cells of the spreadsheet in the desired columns. Consider, for example, that we wanted to accomplish the same Sample Tags assignments as in the basic annotating article linked above. We would fill out the spreadsheet as such:



This gives instructions to Cytobank to create four Sample Tags (IL10, IL6, LPS, Unstim) within the Conditions dimension and to apply the Tags to the files listed on the left. The "Unstim2" file will not be tagged.

After saving the file as either .txt  or .tsv file, it can be uploaded and applied to an Experiment. To do this, first navigate to the experiment, and then choose Actions > Import > Upload Sample Tags:



After uploading, the Experiment files will be annotated with Sample Tags!


Important usage note:

You currently cannot change the annotation status of an annotated file by uploading a spreadsheet with different Sample Tag values. This can lead to double annotating single files and can create buggy downstream behavior. If you need to upload Sample Tags by spreadsheet on top of already tagged files, make sure that the spreadsheet does not have instructions to annotate files that are already annotated (remove already existing tagging information before upload). Alternatively, navigate to the Sample Tags interface within Cytobank and elect to reset the dimension. This is an option on each Sample Tags page. Resetting the dimension will erase all Sample Tag information for a particular class of tag.


Other recommended reading

Also read the Overview of Sample Tags for a solid theoretical grounding in the concept of annotating with Sample Tags.


Have more questions? Submit a request