How To Annotate Your Data With FlowJo Keywords

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.

Join Expert Cytometry's Mastery Class
Tim Bushnell, PhD
Tim Bushnell, PhD

Tim Bushnell holds a PhD in Biology from the Rensselaer Polytechnic Institute. He is a co-founder of—and didactic mind behind—ExCyte, the world’s leading flow cytometry training company, which organization boasts a veritable library of in-the-lab resources on sequencing, microscopy, and related topics in the life sciences.

Similar Articles

3 Must-Have High-Dimensional Flow Cytometry Controls

3 Must-Have High-Dimensional Flow Cytometry Controls

By: Tim Bushnell, PhD

Developments such as the recent upgrade to the Cytobank analysis platform and the creation of new packages such as Immunocluster are reducing the computational expertise needed to work with high-dimensional flow cytometry datasets. Whether you are a researcher in academia, industry, or government, you may want to take advantage of the reduced barrier to entry to apply high-dimensional flow cytometry in your work. However, you’ll need the right experimental design to access the new transformative insights available through these approaches and avoid wasting the considerable time and money required for performing them. As with all experiments, a good design begins…

The Fluorochrome Less Excited: How To Build A Flow Cytometry Antibody Panel

The Fluorochrome Less Excited: How To Build A Flow Cytometry Antibody Panel

By: Tim Bushnell, PhD

Fluorochrome, antibodies and detectors are important. The journey of a thousand cells starts with a good fluorescent panel. The polychromatic panel is the combination of antibodies and fluorochromes. These will be used during the experiment to answer the biological question of interest. When you only need a few targets, the creation of the panel is relatively straightforward. It’s only when you start to get into more complex panels with multiple fluorochromes that overlap in excitation and emission gets more interesting.  FLUOROCHROMES Both full spectrum and traditional fluorescent flow cytometry rely on measuring the emission of the fluorochromes that are attached…

Flow Cytometry Year in Review: Key Changes To Know

Flow Cytometry Year in Review: Key Changes To Know

By: Meerambika Mishra

Here we are, at the end of an eventful year 2021. But with the promise of a new year 2022 to come. It has been a long year, filled with ups and downs. It is always good to reflect on the past year as we move to the future.  In Memoriam Sir Isaac Newton wrote “If I have seen further, it is by standing upon the shoulders of giants.” In the past year, we have lost some giants of our field including Zbigniew Darzynkiwicz, who contributed much in the areas of cell cycle analysis and apoptosis. Howard Shapiro, known for…

What Star Trek Taught Me About Flow Cytometry

What Star Trek Taught Me About Flow Cytometry

By: Tim Bushnell, PhD

It is no secret that I am a very big fan of the Star Trek franchise. There are many good episodes and lessons explored in the 813+ episodes, 12 movies (and counting). Don’t worry, this blog is not going to review all 813, or even 5 of them. Instead, some of the lessons I have taken away from the show that have applicability to science and flow cytometry.  “Darmok and Jalad at Tanagra.”  (ST:TNG season 5, episode 2) This is probably one of my favorite episodes, which involves Picard and an alien trying to establish a common ground and learn…

5 Flow Cytometry Strategies That Sun Tzu Taught Me

5 Flow Cytometry Strategies That Sun Tzu Taught Me

By: Tim Bushnell, PhD

Sun Tzu was a Chinese general and philosopher. His most famous writing is ‘The Art of War’, and has been studied by generals and CEOs, to glean ideas and strategies to help their missions. I was recently rereading this work and thought to myself if any of Sun Tzu’s lessons could apply to flow cytometry.  So I have identified 5 points that I think lend themselves to thinking about flow cytometry.  “Quickness is the essence of the war.” In flow cytometry, speed is of the essence. The longer the cells are out of their natural environment, the less happy they…

A Basic Guide To Flow Cytometry (3 Foundational Concepts)

A Basic Guide To Flow Cytometry (3 Foundational Concepts)

By: Meerambika Mishra

Mastering foundational concepts are imperative for successfully using any technique or system.  Robert Heinlein introduced the term ‘Grok’  in his novel Stranger in a Strange Land. Ever since then it has made its way into popular culture. To Grok something is to understand it intuitively, fully. As a cytometrist, there are several key concepts that you must grok to be successful in your career. These foundational concepts are the key tools that we use day in and day out to identify and characterize our cells of interest.  Cells Flow cytometry measures biological processes at the whole cell level. To do…

Which Fluorophores To Use For Your Microscopy Experiment

Which Fluorophores To Use For Your Microscopy Experiment

By: Heather Brown-Harding, PhD

Fluorophore selection is important. I have often been asked by my facility users which fluorophore is best suited for their experiments. The answer to this is mostly dependent on whether they are using a widefield microscope with set excitation/emission cubes or a laser based system that lets you select the laser and the emission window. Once you have narrowed down which fluorophores you can excite and collect the correct emission, you can further refine the specific fluorophore that is best for your experiment.  In this blog  we will discuss how to determine what can work with your microscope, and how…

4 No Cost Ways To Improve Your Microscopy Image Quality

4 No Cost Ways To Improve Your Microscopy Image Quality

By: Heather Brown-Harding, PhD

Image quality is critical for accurate and reproducible data. Many people get stuck on the magnification of the objective or on using a confocal instead of a widefield microscope. There are several other factors that affect the image quality such as the numerical aperture of the objective, the signal-to-noise ratio of the system, or the brightness of the sample.  Numerical aperture is the ability of an objective to collect light from a sample, but it contributes to two key formulas that will affect your image quality. The first is the theoretical resolution of the objective. It is expressed with the…

What Is Total Internal Reflection Fluorescence (TIRF) Microscopy & Is It Right For You?

What Is Total Internal Reflection Fluorescence (TIRF) Microscopy & Is It Right For You?

By: Heather Brown-Harding, PhD

TIRF is not as common as other microscopy based techniques due to certain restrictions. We will discuss these restrictions, then analyze why it might be perfect for your experiment.  TIRF relies on an evanescent wave, created through a critical angle of coherent light (i.e. laser) that reaches a refractive index mismatch.  What does it mean in practice?  A high angle laser reflects off the interface of the coverslip and the sample. Although the depth that this wave penetrates is dependent on the wavelength of the light, in practice it is approximately 50-300nm from the coverslip. Therefore, the cell membrane is…

Top Technical Training eBooks

Get the Advanced Microscopy eBook

Get the Advanced Microscopy eBook

Heather Brown-Harding, PhD

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

Get The Free Modern Flow Cytometry eBook

Get The Free Modern Flow Cytometry eBook

Tim Bushnell, PhD

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

Get The Free 4-10 Compensation eBook

Get The Free 4-10 Compensation eBook

Tim Bushnell, PhD

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.