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.

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.

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.

• 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.

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.

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

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

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.

2. Then go to Add Column > Formula.

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

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.