The Daily Dongle

FlowJo v765 Mac Command Line

FlowJo v7.6.5 has a nifty command line feature extension for templates. (The FlowJo license allows Mac users to run both our C version (currently v9), and our Java version (currently v7.6.5); the feature sets of the 2 programs being slightly different). 

For repetitive analysis workspaces amenable to templates, the command line feature allows one to use a script to run FlowJo, open a template, and have it load/analyze data, and output reports (layouts and tables). Nice to get your computer to do some work while you are at the ballgame, or home asleep!

 

Here is an example:

1. first set up your FlowJo template.

Autobatch templates

(note: currently Layouts and Tables work in templates, group FCS Export won't execute from templates)

2. On your mac use a text editor to write your shell script to open FlowJo with command line arguments.

-Below is a simple example shell script on my mac to open a FlowJo template, load some data (the template outputs a Table, and a Layout), then flowjo quits.

Screengrab before running the script:

(double click image to make larger)

And, after double clicking the file "flowjo765mac autobatch.command"  

(terminal window opens and runs the script, causing flowjo to open, load the template workspace, load data, export a layout and table, and quit)

 

One can use Mac OSX built in Applescript language and/or Automator to make more complex automation scripts, including Folder actions.

OS X Folder Actions guide

FlowJo Table Options

For many FlowJo power users, FlowJo tables are integral to their flow data analysis. A few users have written into support lately asking how to modify the first column of the table (typically sample name).

 

The Issue:

The default in FlowJo tables is to use the same naming convention as the workspace, plus add numbers before the name. People ask how to get rid of the numbers shown in the picture below:

 

Here is how:

In the table editor, before creating the table, one needs to modify the table creation options (iteration). Instead of using the default (Group tubes by numerical order), one can choose to Group by keyword.

With the Table Editor window open, click the Tables Menu and choose Iteration-Options to open the Batch Iteration Options Dialog Window. (pict below). Set the options to Group tubes by keyword $Fil (or sampleID, or whatever keyword you prefer. $Fil is the standard fcs keyword for the original tube filename saved on the cytometer).

 

More info on Table options:

http://www.flowjo.com/v9/html/tables.html

http://flowjo.typepad.com/the_daily_dongle/2011/09/patient-day-tables-keyword-iteration-.html

 

Layout Batching with a control

Background

Many of our users know about the nice time saving FlowJo feature of batching Layouts with a control (the control doesn't change in each overlay graph). Someone recently asked us about making a batched layout with a control, but wanted to skip the graph that shows the Control tube plotted against the Control tube.

Solution

If you set up your Groups so that your controls are in one group, and your samples are in another (separate from the All-Samples group), then when you batch the layout, choose to iterate only over the tubes in the samples group. (double click the screengrab below for a larger picture)

 

Results:

Comp Matrix file tips

This post deals with compensation matrix file issues for our Mac version and covers:

• Comp matrix file format
• Loading a comp matrix file 
• Comp parameter default naming

 

File Format:

If you save a compensation matrix from flowjo and open the file In a text editor (say TextWrangler), you can see that the values are tab separated with end-of-line CR  (Mac classic). The Parameter names in the text file have to match the parameter names in your FCS data file. (click image below to enlarge)

 

Loading a comp matrix file

From the "Platform : Compensate : Load Matrix Form File" menu item in Flowjo v9, pick your matrix file.

(If someone sent you the matrix file and it is greyed out, the file type may not be TEXT. Some servers will change the HFS filetype. No worries. Open the file in TextWrangler and resave, or use the Terminal unix command SetFile. i.e. SetFile -t TEXT filename

If your matrix list gets long, one can remove an unused matrix from the matrix list in V9.

Comp parameter default naming

By default, FlowJo v9 will name compensated parameters by enclosing the original parameter name with < >. If you want to change the default for a matrix, edit the matrix file changing the " <  >" to what you like, maybe "Comp_"  like in our Java version v7.6.5. 

One can also load a Flowjo v9 matrix file into our Java version, v7.6.5, if it is named with the .mtx extension. 

Three Rules for Compensation Controls

First and foremost, there must be a single stained control for every parameter in the experiment!

In addition, there are three rules for “good” compensation controls:

1) Controls need to be at least as bright or brighter than any sample the          compensation will be applied to

2) Background fluorescence should be the same for the positive and negative control

3) Compensation controls MUST match the exact experimental fluorochrome

 

1) Controls need to be at least as bright or brighter than any sample the compensation will be applied to

An important consideration is to select the sample with the brightest fluorescence of the experiment. “Dimness” is relatively irrelevant. Only brightest matters, and that is so that low spillovers can be accurately estimated. For example, if a spillover is so low that a MFI of 10,000 doesn't cause enough spillover to be above autofluorescence, then the system assumes no compensation is necessary. At a MFI of 100,000, the spillover becomes apparent and then compensation value can be accurately assessed. Compensation is only about estimating the slope. The bottom line is that because the compensation coefficients are computed based on the RATIO of the DIFFERENCE in MFI's (of the spillover channel and the primary channel), so small absolute errors in the position of the negative control become irrelevant as the positive controls become brighter. The error in the compensation coefficient is the sum of the absolute errors in the MFI's of both the negative and the positive control; the latter has an inherently much larger absolute error than the former.

2) Background fluorescence should be the same for the positive and negative control

Any carrier for binding fluorochromes can be used for single stain compensation controls, such as cells or particles. However, the positive and negative carrier of a parameter must have the same autofluorescence. This is because compensation is a subtraction algorithm. It is imperative to NOT include autofluorescence in the compensation calculation, so if the positive and negative have the same autofluorescence, then the autofluorescence contribution to the compensation spillover calculation will be zero. If this is met, one can apply the compensation matrix to any population. For example, one can compensate on particles and apply that to cells.

3) Compensation control fluorochromes MUST match the exact experimental fluorochrome

Each flurochrome has a unique emission profile.  Therefore, the amount of spillover will be different, even for fluorochromes that emit light at about the same wavelength (e.g. FITC and Alexa Fluor 488) 

This rule is even more restrictive when applied to tandem dyes.  Each lot of tandem dye (PE-TR, PE-Cy5, PerCP-Cy5.5, APC-Cy7, etc.) should be considered unique and require its own single stain control. If a user is using two different lots of PE-Cy7 in an experiment, then they need to have two PE-Cy7 compensation single stain controls, one from each lot. Different lots will have different conjugation ratios, i.e. more Cy7 conjugates to PE or less.

One final note

Finally, compensation controls must be treated in the same manner as experimental samples. This is because exposure to light and treatments like fixation/permeabilization may alter the fluorochrome, particularly the tandem conjugation ratio, i.e. lose some Cy7 on each PE molecule.

Compensation particles versus cells for single stain controls

There is no difference in the accuracy of the two approaches for compensation. However, compensation particles do have numerous benefits over using cells. First and foremost, precious sample does not need to be wasted on single stain controls. All the cells can then be used for the experimental samples. In addition, compensation particles typically provide the brightest signal possible for any given parameter. Compensation particles are also more precise. The reason that particles are more precise for compensation is fairly straightforward. Cells have a large variance in background fluorescence (a high CV), higher than particles. This means that the spillover computation has significant error for compensation coefficients where the measurement of spillover fluorescence on cells is dominated by the error in the autofluorescence measurement. On the other hand, the particles have a much smaller error in the distribution of background fluorescence, meaning that the spillover computation is far more precise.

Of course, particles have some limitations.   

1) Compensation particles cannot be used for dyes like PI, DAPI, or EMA -- but they can be used them with amine-reactive viability dyes.  (Also, some manufacturers are now providing specific dyes preloaded into particles to use as single stain compensation controls).

2)  Particles do not bind all antibody reagents and in some cases they simply are not bright enough.

3) For some experimental conditions using tandems (e.g. permeabilization/fixation), one must ensure that the fluorescence spectrum of the experiment does not alter the emission spectrum of the tandems attached to particles in a different manner than it would the tandems attached to cells.

So, in fact, in many experiments, a user may have one or two cell-based compensation controls for some parameters used together with bead based compensation controls for the other parameters.

- Question of comments can be sent to nick@treestar.com

 

Patient-Day Tables (Keyword Iteration)

Many Datasets can benefit from tables created using keyword iteration. A couple users have asked us about this lately. Setting up keyword iterated tables is not so intuitive the first time, so lets walk through it together using a dataset containing tubes from multiple patients, collected on multiple days. (Our Advanced Tutorial makes use of this dataset type).

The default in flowjo table batching creates a row for each tube. For a Patient-Day dataset this may look like the graph below. Admittedly, not the most desireable table, with summary stats not applicable.

 

 

More desireable is a table with different rows for each Day, different columns for each Patient, and useful table summary statistics in the last 2 rows. The table below is created by batching with Keyword Iteration.

If your tube files do not have appropriate keyword values, first create a keyword value series in flowjo. With appropriate Day and Patient keyword values for the tubes, open the Table Editor, choose Tables menu > Iteration Options, then set the Iterator to the Day keyword, and the Descriminator to the Patient keyword.

Now, set up the table by dragging nodes from the Workspace into the Table Editor from tubes that have the same Iterator Keyword Value (same Day in this case). Each dragged in node will create a column in a batched table, each change in the Iterator will create a new row in a batched table. (screengrab below, click on to open a larger image)

 

 

Note:

-The table columns use conditionally formatted numbers, in this case set to be red if the number is more than 2 standard deviations from the mean of the numbers in the column. (Conditional formatting gets set up before batching by selecting a row in the Table Editor and clicking the "i" button).

-Layout Editor batching using keyword iteration works in an analogous manner.

-The screengrabs are from our Mac version 9.3.3, but everything works similar in our Java version 7.6.x that runs on both Windows and MacOSX. 

Patient-Time data

Ever want to look at how a statistic varies Day-to-Day from Patient-to-Patient on a single plot as shown in the graph below? One strategy is to use FlowJo v9, combining the use of keyword formulas and concatenation.

The dataset below contains a T-cell panel for two patients with tubes run on different days. The tube files contain keywords for Patient and Day (Our Advanced Tutorial Dataset). Gates were made in the workspace to get the frequency of CD4+CD8+ T-cells.

To make the graph:

- Create a keyword from the Freq of CD4+CD8+ statistic.
(see http://flowjo.typepad.com/the_daily_dongle/2011/07/focus-group.html)

-Concatenate the files, creating additional parameters for the Day, Patient, and CD4+CD8+ keywords.
(see http://flowjo.typepad.com/the_daily_dongle/2008/06/how-the-new-concatenation-works.html)

-Load the concatenated file back into the workspace, and display CD4+CD8+ vs Day.

-Switch the default pseudo-color plot to Polychromatic, assigning a color to the Patient parameter.

Or, another way to visualize and gate on the data:

Focus Group

A user wrote in to support the other day, wanting to select a group of samples (out of hundreds in the workspace) based on a Statistic. Many savvy FlowJo users know they can create Groups of samples based on Keyword criteria or staining protocol. What about creating a Group based on a Statistic (or formula)? 

One can do this in Flowjo v9 in the Workspace using Keywords and FJML formulas, and/or in the Table Editor.

Creating a Focus Group with a Keyword defined by a statistic

-Edit a newly created Keyword by double clicking the first cell in the Keyword column. Define the Keyword with an FJML statistical formula (begin the keyword with FJML=).

For example, One may want to create a Keyword based on the Statistic: percent CD4 CD8 double positive T cells. Once the gates and stat nodes are created, one easy way to get the FJML formula is to drag the stat for CD4+CD8+ into the Layout Editor, double click the stat in the LE to see the FJML. Copy/paste the formula into the Workspace Keyword:

 
 

For an overview of Keyword formulas, please see these previous posts: 

http://flowjo.typepad.com/the_daily_dongle/2011/01/fjml-keyword-examples.html

http://flowjo.typepad.com/the_daily_dongle/2010/05/fjml-in-fj-mac.html

 

Once the Keyword value is created for the first sample, Copy it to the other samples using Workspace menu > Copy Value to Group

Now, one can create a new (Focus) Group based on the desired criteria:

 

 

Creating a Focus Group from within a Flowjo Table

Create the Table, double click the stat column title to sort the column, select the samples of interest, click Create Group from Selected Samples:

 
 

Keystroke Shortcuts in FlowJo

Find 'em here: http://www.flowjo.com/home/shortcuts.html

Oceans of Flow

Daniel Vaulot's work over the last decade has been instrumental in application of flow cytometry to oceanography. In particular, flow is well suited for the study of the smallest size class of the plankton (below 2 µm), called picoplankton, which is  composed of heterotrophic prokaryotes, prochlorophytes (Prochlorococcus), cyanobacteria (Synechococcus) and eukaryotes. The light-scattering parameters and fluorescence of natural photosynthetic pigments (chlorophyll, phycoerythrin) allows the identification of different groups that differ in terms of size and pigment content. Fluorescent microspheres (beads) are normally added as internal reference.

The small picoplankton requires lowering of instrument threshold levels in order to detect. One consequence of this is the acquisition of background "noise", as observed in the Figure below. In this plot, the large round population at the origin is not a picoplankton subpopulation, but rather a collection of background noise.  One of the main problems of collected noise is that it contributes to the file size. In this example, the >99% of noise equates to a file size of more than 100MB! Working with 100MB files are not fun. What can FlowJo do to make life easier?

 

Create a gate to include the populations of interest and to exclude most of the noise; as seen in Figure below. Alternatively you can use a "Not Gate". I have chosen to still keep some of the noise for referencing purposes.

 

Select the gate that you just created for one of the samples in your Workspace. For example, in the above Figure, the gate selected would be the "Export Gate". Now go to the main Workspace Tab and select the Export/Concatenate option. As per the Figure below, you will get a dialog box. Here you have to select Output Format as FSC 3.0 and use the "Select.... " option to choose a file name and file saving destination. This step generates a new FCS 3.0 file without a the huge chunk of noise.  This new file can be introduced into a FlowJo Workspace like any other FCS file, as seen in Figure 3. The new files are only about 700kb!

 

Once you have created the gates for populations of interest; in this case of Euk, Pro, Syn and Beads (see below), these can be overlayed in the Layout Editor.

 

In fact the Legend created (which appears as you overlay) allows you to remove the noise altogether by commanding the noise layer to be deleted (menu option appears when you mouse-right click on the Legend). Just remember that frequency statistics are based on the total events available on the plot, as such the percentage values for Euk, Pro, Syn and Beads will change based on inclusion or exclusion of noise events.

 

References:

Simon, N., Barlow, R. G., Marie, D., Partensky, F., Vaulot, D. (1994). Flow cytometry analysis of oceanic photosynthetic picoeucaryotes. J. Phycol. 30: 922-935

Vaulot, D., Marie, D., Olson, R. J., Chisholm, S. W. (1995). Growth of Prochlorococcus, a photosynthetic prokaryote, in the equatorial Pacific Ocean. Science 268: 1480-1482

Vaulot, D., Partensky, F. (1992). Cell cycle distributions of prochlorophytes in the North Western Mediterranean Sea. Deep Sea Res. 39: 727-742