Skip to content

How To Annotate Your Data With FlowJo Keywords

Written by Tim Bushnell, PhD

Do you annotate your data properly?

If you don’t, you’re not alone. Most people don’t take advantage of the keywords embedded in the FCS (Flow Cytometry Standard) files to annotate their data. FlowJo makes this easy to do.

First off, what are keywords and why do you want to use keywords?

The flow cytometry standard file formats (FCS) was developed by the International Society for the Advancement of Cytometry (ISAC) to create a standard file format for all cytometers to use. The purpose of this was so that no matter who manufactured the instrument, or the analysis software, files could be created and read in any system.

As part of this FCS standard, ISAC created a set of core keywords that MUST be used. These include information on the parameters, scaling, FCS file format, date, file name, and numerous others. You can read more about the FCS file format here.

When it comes to annotating your flow cytometry data with keywords, there are 3 things you need to know…


1. Certain keywords are “required” by the Flow Cytometry Standard (FCS).

This is the list of primary keywords required:

$BEGINANALYSIS Byte-offset to the beginning of the ANALYSIS segment.
$BEGINDATA Byte-offset to the beginning of the DATA segment.
$BEGINSTEXT Byte-offset to the beginning of a supplemental TEXT segment.
$BYTEORD Byte order for data acquisition computer.
$DATATYPE Type of data in DATA segment (ASCII, integer, floating point).
$ENDANALYSIS Byte-offset to the last byte of the ANALYSIS segment.
$ENDDATA Byte-offset to the last byte of the DATA segment.
$ENDSTEXT Byte-offset to the last byte of a supplemental TEXT segment.
$MODE Data mode (list mode – preferred, histogram – deprecated).
$NEXTDATA Byte offset to next data set in the file.
$PAR Number of parameters in an event.
$PnB Number of bits reserved for parameter number n.
$PnE Amplification type for parameter n.
$PnN Short name for parameter n.
$PnR Range for parameter number n.
$TOT Total number of events in the data set.

Many of these keywords have little value to you, as the user. They can help with troubleshooting, if you are having trouble in the analysis program, but for the most part, not many people need these keywords.

Flow cytometry FlowJo keywords can be used for annotation

2. Other keywords are optional and can assist you in analyzing your data.

The keywords that will help you analyze your data are the optional keywords. Although these keywords are considered optional, most cytometer manufacturers still use them.

$ABRT Events lost due to data acquisition electronic coincidence.
$BTIM Clock time at beginning of data acquisition.
$CELLS Description of objects measured.
$COM Comment.
$CSMODE Cell subset mode, number of subsets to which an object may belong.
$CSVBITS Number of bits used to encode a cell subset identifier.
$CSVnFLAG The bit set as a flag for subset n.
$CYT Type of flow cytometer.
$CYTSN Flow cytometer serial number.
$DATE Date of data set acquisition.
$ETIM Clock time at end of data acquisition. ISAC Recommendation FCS 3.1 – Data File Standards for Flow Cytometry 11/34
$EXP Name of investigator initiating the experiment.
$FIL Name of the data file containing the data set.
$GATE Number of gating parameters.
$GATING Specifies region combinations used for gating.
$INST Institution at which data was acquired.
$LAST_MODIFIED Timestamp of the last modification of the data set.
$LAST_MODIFIER Name of the person performing last modification of a data set.
$LOST Number of events lost due to computer busy.
$OP Name of flow cytometry operator.
$ORIGINALITY Information whether the FCS data set has been modified (any part of it) or is original as acquired by the instrument.
$PLATEID Plate identifier.
$PLATENAME Plate name.
$PnCALIBRATION Conversion of parameter values to any well defined units, e.g. MESF.
$SMNO Specimen (e.g. tube) label.
$SPILLOVER Fluorescence spillover matrix.
$SRC Source of the specimen (patient name, cell types)
$SYS Type of computer and its operating system.
$TIMESTEP Time step for time parameter.
$TR Trigger parameter and its threshold.
$VOL Volume of sample run during data acquisition.
$WELLID Well identifier.

Many of these keywords have values that are recorded by the cytometer. However, many of these keywords are also empty, so you can put in whatever you want during acquisition! PatientID, treatments, stains, studyID, groups, etc. Think about what may help you in your analysis, or to track your data when you export it. You should consider putting in these keywords.

Annotate your FlowJo experiments for future reference

3. You can create keyword formulas to simplify the data analysis process.

To begin working with keywords in FlowJo

  • Load some data in FlowJo and in the workspace
  • Right-click on a sample
  • Go to Sample Info (or Inspect). An interface will open that displays all the keywords and their values.

FlowJo annotation parameters and stains

  • Keywords like $BTIM and $ETIM denote start time and end time.
  • $DATE is self-explanatory.
  • $FIL is the file name.
  • $TOT is the total number of events that were acquired.

These are just examples of commonly used keywords. FlowJo has a full list of keywords on their website, here.

Keywords are embedded into the FCS files, so you can’t edit them. However, FlowJo does allow you to add them as a column in the workspace and edit them for that workspace.

Configure FlowJo by adding new columns

How can this benefit you?

If you forget to name a stain properly, add the $PnS keyword and put in the name. This can be a little challenging in that you will need to know the channels. These can be found in the sample information menu under $PnN usually.

The $PnN is the parameter name, but isn’t often very useful, as this is a default name set up on the cytometer. It may just be FL1, or maybe the filter set, like 525/50.

If you add a value to the corresponding $PnS keyword though, that will show up in the graph window’s axis labels and make it easier to review the data.

Adding columns for keywords in FlowJo
You can also add new keywords in FlowJo. Just click the add new keyword button.

Setting up FlowJo workspace keyword areas

You can use this to add sample IDs, or patient numbers, treatment information, staining protocols, or other information needed for you analysis.

Grouping FlowJo samples
You can then group samples based on keywords. If you’ve never used groups, that is also something that allows you to batch process your analysis to a subset of samples.

Finally, you can embed keywords into the layout editor and the table editor in FlowJo. Use the table editor to add a formula of $ETIM-$BTIM to get the time of acquisition.

1. First, add $ETIM and $BTIM to your table.

FlowJo keyword grouping by name

2. Then go to Add Column > Formula.

Inserting new columns for keywords in FlowJo

3. Insert reference of $ETIM – $BTIM and click OK.

Here is how to annotate formula using FlowJo

The formula will appear in the table editor and when the table is created, you’ll get the column in the table. Use $TOT and divide by $VOL to get the count per unit volume. Embed $SAMPLEID to be able to easily sort samples when you put them into Excel from the table editor.

There are numerous different ways to use keywords in the table editor and layout editor. The problem is, most scientists do not annotate their data properly and pay the price when they want to repeat their experiments. By taking advantage of the above keywords and by using keyword formulas, you can save time during your analysis. Most importantly, when you go to reanalyze your data, you can utilize your previous keywords and formulas to save even more time.

To learn more about how to annotate your data with FlowJo keywords and to get access to all of our advanced materials including 20 training videos, presentations, workbooks, and private group membership, get on the Flow Cytometry Mastery Class wait list.

Tim Bushnell, PhD


Advanced Microscopy

Learn the best practices and advanced techniques across the diverse fields of microscopy, including instrumentation, experimental setup, image analysis, figure preparation, and more.
flow cytometry tablet eBook cover

Modern Flow Cytometry

Learn the best practices of flow cytometry experimentation, data analysis, figure preparation, antibody panel design, instrumentation and more. 

Advanced 4-10 Color Compensation

Advanced 4-10 Color Compensation, Learn strategies for designing advanced antibody compensation panels and how to use your compensation matrix to analyze your experimental data.

Top 40 Networking Scripts For PhDs

If you want to get replies from top employers and recruiters, this ebook is for you. These networking scripts will show you the exact words ...

Informational Interviews For PhDs

If you want to learn how to set up and execute informational interviews with PhDs working in industry, this ebook is for you. Here, you ...

Industry Resume Guide For PhDs

If you have a PhD and want to create the perfect industry resume to attract employers, this ebook is for you. Here, you will get ...

Top 20 Industry Jobs For PhDs

If you want to learn about the top 20 industry careers for PhDs regardless of your PhD background, this ebook is for you. Here, you ...

Salary Negotiation For PhDs

If you have a PhD and want to learn advanced salary negotiation strategies, this ebook is for you. Here, you will learn how to set ...

Top 20 Transferable Skills For PhDs

If you want to learn the top 20 transferable skills the industry employers ranked as most important for PhDs to include on their resumes and ...

Related Posts You Might Like

flow cytometer being tested

Getting A New Flow Cytometer? Try Before You Buy (And 2 Other Tips)

Written By: Tim Bushnell, PhD One question that I get asked on a regular basis is what flow cytometer should I purchase?  It’s not as ...
Read More

5-Point Guide To Buying A New Microscope For Your Lab

Written By: Heather Brown-Harding, PhD Have you ever noticed how painful it can be to purchase a new microscope? It would be hard to miss ...
Read More

Ask These 7 Questions Before Purchasing A Flow Cytometer

Written By: Tim Bushnell, PhD Using funds to make a capital purchase can be an exciting time in a facility. If you don’t have the ...
Read More

Instrument Quality Control For Reproducible Flow Cytometry Experiments

Written by Tim Bushnell, PhD The NIH has released a series of reproducibility guidelines that scientists must address. These guidelines have been introduced because there's ...
Read More

How to Optimize Flow Cytometry Hardware For Rare Event Analysis

Written by Tim Bushnell, PhD “Not everything that can be counted counts and not everything that counts can be counted.” — William Bruce Cameron (but ...
Read More

3 Ways The ZE5 Cell Analyzer Accelerates Flow Cytometry Research Opportunities

Written by Tim Bushnell, PhD As new instruments come on the market, vendors are quick to provide data proving the systems’ prowess including sensitivity, speed, ...
Read More