Templates contain your entire analysis, minus the FCS files. They are helpful when you analyze the same type of data over and over. So, if you analyze the data the first time, save the workspace and also save it as a template.  That way, when you run the experiment next week again, you can open the template, drag in your new files and have the entire analysis done for you already.  It saves time!

Templates include all of your usual gestures of organizing and analyzing the data:

  1. Organizing samples into groups
  2. Gating the samples
  3. Batch reports from the table and layout editors

Templates can be used in either interactive mode or via command line. This section will deal with the creation and interactive use of templates.

1) Organizing samples into groups

This is the most important part of designing the template. If all your samples have the same analysis structure (gates, stats., etc.), then you can just use the “All Samples” group (make sure you still place the analysis structure into the “All Samples” group before saving as a template).

If you use additional FlowJo groups, the group must be set up in a way that will automatically include the right samples with the right groups. Most Flowjo analysis in a template will be attached to a group, so we want to put equivalent samples into the same group for that reason.

When designing a group, pay attention to two attributes: inclusion criteria and that the group is “live”.

Inclusion criteria are like search terms — you can specify what attributes define the equivalency of your samples. For your convenience, if you add data to a FlowJo workspace, there will be some automatically proposed criteria that are derived from reagent combinations:

The best way to group samples is by reagent combination.

2) Compensation

Very often the gates we’re applying to samples in Step 3 will rely on the samples being compensated in this step. If a non-compensated sample is gated with a tree that references gated parameters, stats and frequencies will not be calculated. We can therefore think of compensation as a prerequisite for gating.

To compensate in vX, rather than defining a complex compensation script, the paradigm shifted to “defining a group for compensation samples”. This group is where FlowJo vX will check for whether or not compensation is necessary for this template.

By default in vX, the “Compensation” group includes any files that contain the word “comp” in the name, or the word “unstained” (for the unstained control).

To test whether or not compensation will work with your template, try adding the compensation files and see if they go to the group “Compensation”. If not, you may drag-and-drop your compensation controls into this group or you may adjust the compensation group’s inclusion criteria until the group contains all your single stained controls and none of the other samples.

Then, under the “Tools” tab, within the “Cytometry” band, open “Compensation” to see if the data is correctly compensated. If this step works, you can move on to defining table and layout editor options.

Note: If data is brought into a template that was generated from a workspace in which compensation was applied, the comp group shows that it has a matrix (which is devoid of samples).  Upon loading the next set of compensation control samples, and getting them into the “Compensation” group as described above, be sure to click on a sample assignment drop-down in the compensation editor and select “reset all” to calculate a new compensation matrix (as shown below).

Screen Shot 2013-11-26 at 8.37.57 PM

3) Gating the samples

Gating in templates is not done by hand. It’s done by groups…or more to the point, by matching the correct samples with the correct gate-owning groups. There are two components to this:

A – Making the first-pass gating trees (this gating is done by hand) and attaching them to a group.

B – Making that group inclusion criteria match only the samples that belong to that gating tree, then making the group “live”.

This connects back with the point that samples should be grouped by reagents. If your template’s groups are designed correctly, when you add samples they should automatically migrate to the correct group and inherit the appropriate gates.

*This is the critical step in making your template behave properly.  Gates and/or statistics MUST be group-owned for the template to ‘remember’ the analysis structure.  If the analysis structure is not placed on a group before the template is saved, then samples loaded into the template WILL NOT be gated.

Another note about gates: Applying gates in using a template for repeated analysis depends on both the parameter names matching exactly.  In addition, in versions 10.0.7 and later, transforms are saved with a template such that they will be applied before gates are drawn to preserve gating geometry.

4) Batching tables and layouts

Each table and layout should be designed to work in batch mode — either by sample (i.e. every tube in the group) or by panel (i.e. every N tubes at a time). The difference for templates is rather than viewing the batch results directly in FlowJo in a new layout window, you might instead want to save the tables as CSV / Excel files, and send layout batches directly to your printer (or as a PDF to save paper).

The options for these settings are present in the respective editors’ batch settings:

Table: we recommend against selecting printer or “show in FlowJo”. Any of the other file options will do…also, select a path that is visible to the template when you execute it!

Layout: we recommend against selecting printer or “new layout”. Any of the file options will generally meet your needs; after all you can always print a PDF after reviewing it was assembled correctly.  Also, select a path that is visible to the template when you execute it!

If designing tables/layouts for command line scripting, you may wish to enable the “autobatch” attribute. This will render the tables/layouts marked as “autobatch” able during the invocation of the command line process.

Also see: Layout Editor Batching and Table Editor Batching

5) Batch exporting or concatenating data

The last commonly applied facet of templates is the batch-export or batch-concatenation of samples. This tool is a group operation: create your group with the inclusion criteria and the “live” attribute enabled. Then right-click the group name and select “Group Export” from the right-click menu for ungated (all events) export; or, to export/concatenate a specific subset, right-click on that subset from the group’s tree of gates.

The dialog above allows the selection of which parameters to export (left-side list of checkboxes). It’s sometimes a good idea to uncheck uncompensated parameters and/or parameters used to do gating. This makes the exported files smaller.

You can choose a custom number of events here. This is when it is absolutely necessary to have 5000 events in every gate. First make a gate in FJ that has at least 5000 cells, then export it this way to make sure it has exactly 5000.

“Format” lets you choose between CSV and FCS, depending on where your data is headed next.

Lastly, the “Concatenate” option will merge all contents of the group into a single export. If you choose the FCS option, your exported FCS file will have an additional parameter to help you differentiate the source files (retaining the group’s sort order at the time of processing the files.)

When loading templates from older versions of FlowJo, make sure that custom names are used for column headers in the Table Editor.

See also: Exporting