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

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…

5 Drool Worthy Imaging Advances Of 2020

5 Drool Worthy Imaging Advances Of 2020

By: Heather Brown-Harding, PhD

2020 was a difficult year for many, with their own research being interrupted- either by lab shutdowns or recruitment into the race against COVID-19. Despite the challenges, scientists have continued to be creative and have pushed the boundaries of what is possible. These are the techniques and technologies that every microscopist was envious of in 2020. Spatially Resolved Transcriptomics Nature Methods declared that spatially resolved transcriptomics was the 2020 method of the year. These are a  group of methods that combine gene expression with their physical location. Single-cell RNA sequencing (scRNAseq) was originally developed for cells that had been dissociated…

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

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

By: Tim Bushnell, PhD

There are 4 major ways to sort cells. The first way can use magnetic beads coupled to antibodies and pass the cells through a magnetic field. The labeled cells will stick, and the unlabeled cells will remain in the supernatant. The second way is to use some sort of mechanical force like a flapper or air stream that separates the target cells from the bulk population. The third way is the recently introduced microfluidics sorter, which uses microfluidics channels to isolate the target cells. The last method, which is the most common––based on Fuwyler’s work––is the electrostatic cell sorter. This…

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

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

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 – this can be a frustrating process. A lot of scientists and students consider the new microscope hunt quite scary for a variety of reasons. It might be that you’re worried you won’t get the right microscope and that you’ll regret it, or you may find that dealing with salespeople, in general, makes you kind of uncomfortable. But remember, salespeople are just human beings like you and me, and if we can treat them as such, the whole process of…

Ask These 7 Questions Before Purchasing A Flow Cytometer

Ask These 7 Questions Before Purchasing A Flow Cytometer

By: Tim Bushnell, PhD

I am still convinced that my first cell sorter was possessed. The number of issues that I had with the system remains hard for me to believe, even after all these years. It had been purchased, in part, from one vendor because the sales rep for a competitor was nowhere to be found. At that time, I admit I wasn’t overly diligent in my research process. Since then, I’ve pinpointed some critical questions that need to be answered before purchasing a new instrument. At the end of the process, a shiny new instrument will arrive at your facility. Make sure…

Instrument Quality Control For Reproducible Flow Cytometry Experiments

Instrument Quality Control For Reproducible Flow Cytometry Experiments

By: Tim Bushnell, PhD

The flow cytometer is an integral component of any flow cytometry experiment, and special attention should be paid to ensuring that it is working correctly and consistently. As an end-user, the researcher should be able to sit down at a machine and know that it is performing the same way today as it was yesterday and last week. Equally important is that if any changes in instrument performance have occured, the end-user knows how they have been addressed and corrected, rather than letting them fester and potentially affect the results. Quality control measurements can include a variety of targets, such…

How to Optimize Flow Cytometry Hardware For Rare Event Analysis

How to Optimize Flow Cytometry Hardware For Rare Event Analysis

By: Tim Bushnell, PhD

Preparing for rare event analysis requires an understanding of the power and limitation of the instrument to be used. From how fast to run the fluidics, to how the signal is processed to the number of gates that can be used in the sorting experiment, each factor impacts the outcome of the experiment.

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.