Command line FlowJo is the way to use FlowJo without a user interface (“headless”) or human intervention.
Using command line FlowJo, the user has various options to load data, perform auto-compensation, calculate gates and statistics, generate reports, import CLR files, export populations, and save results. Importantly, users can use command line to execute FlowJo templates on data sets and produce output files such as PDF, HTML, CSV, FCS, and ACS. In addition, the user can create a new workspace from a list of sample files, and then import CLR files produced from an external analysis into the ACS file. This document describes the general operation of command line processing, how to invoke command line FlowJo, and the various arguments.
General operation
Command line FlowJo:
– Opens the specified template (WSPT), workspace (WSP), or ACS file. If it is an ACS file, the most recent embedded workspace is used.
– Loads the data into the workspace, assigning samples to the appropriate groups, performing compensation, gating, and statistic calculations as needed.
– Performs automated batching of layouts and tables. Output files may be redirected to a specific folder.
– Performs automated exporting of FCS, CSV, or CLR files. Output files may be redirected to a specific folder.
– Imports the specified folder of external CLR files. CLR files are mapped to samples by name.
– Saves the workspace or acs file. If it is a workspace, it is stored in the same folder as the template.
Note: You must use quotes to reference any file directories that have spaces in them. See below for an example.
How to invoke command line FlowJo
Command line FlowJo is invoked by referencing an installed version of FlowJo. How you invoke FlowJo depends on the operating system.
Windows XP Command Line:
You will want to open your Programs Folder and make note of the exact FlowJo name. At root folder level and the name of the .exe file.
It’s best to use the tab command to find the right file structure with this OS system. So to locate XP’s program files and FJ, type in Command Line
C:Pro and hit the tab key till Program Files is automatically entered. Then Flo and hit the tab key to you get the FlowJo program you are using. Then Flo and hit the tab key till you get to the exe file inside the FlowJo program file.
Should look like this when finished: using the tab key filled in most of this for me.
“C:Program FilesFlowJo Vx10.8.0FlowJo_V10.exe” (quotes are very important in the cmd line for XP)
Now you can specify where your template is located, where your data is located, and what other arguments you would like to include in the command. The arguments below can be used just like the Mac.
Here is an example: I created a template file and specified and output folder after the template is ran.
BreakDown:
Command to find program to be ran:
“C:Program FilesFlowJo vX10.8.0FlowJo_Vx10.exe”
Command to find template:
“C:Documents and SettingsUserNameDesktoptest.wspt”
Command to find data:
“C:Documents and SettingsUserDesktopPanel_1.1”
Arguments: for this test, I just wanted my outputs to be saved to this folder called output
Command to make and save a WSP
-save “C:Documents and SettingsUserDesktopOutput”
See below for more argument items to use via command line. Can use same as Mac.
Command to make and save a WSP
-saveAs “C:Documents and SettingsUserDesktopOutput”
-save: also saves but not to a specified folder.
WindowsOS Command Line:
Use notepad to create a text file with the suffix “.bat” – for example in the figure below, we created a text file containing:
“C:Program FilesFlowJo VxFlowJo_V10.exe” “C:Documents and SettingsVince XPDesktop20120906 vX10_0_03.wsp”
and saved it as “FJ vX 10 0 3 commandline.bat” (Figure 1A). We then simply go to Start/Run/cmd.exe to open the DOS Command Shell, and can drag and drop this bat file into the shell (Figure 1B). One can similarly reference data folders and templates in this .bat file to automate analysis of FCS files.
Figure 1. Windows OS Command Line A. Using notepad to generate a .bat file referencing a workspace to open using command line. B. Drag and drop this .bat file to the DOS command shell (cmd.exe).
The general form of this for Windows is:
C:Program FilesFlowJo VxFlowJo_V10.exe
MacOSX Command Line:
To invoke command line on the Mac, open the application “Terminal” and enter the commands that will be passed to FlowJo:open -W -g -a /Applications/FlowJo.app/ --args /Users/mike/Desktop/CommandLineDemo/TCellSubsets.wspt /Users/mike/Desktop/CommandLineDemo/ -saveAs /Users/mike/Desktop/CommandLineDemo/TCellDataInitialWorkspace.wsp -outputFolder /Users/mike/Desktop/CommandLineDemo/Output
Note that in this case, quotes (“”) are unnecessary as none of the files nor folders contain spaces.
Figure 2. MacOSX Command Line in Terminal.
which does the following…open -W -g -a /Applications/FlowJo.app/ --args
which invokes FlowJo Version 10 (the -W and -g options indicate to wait for the application to exit before proceeding, and to not bring the application to the foreground when executing), as described above, and passes everything after –args to FlowJo as a list of tasks to perform. Those tasks are..
1) /Users/mike/Desktop/CommandLineDemo/TCellSubsets.wspt
Open the TCellSubsets Template which is saved to a folder on the desktop (for more information on creating a template, please see this page).
2) /Users/mike/Desktop/CommandLineDemo/
Points FlowJo to the CommandLineDemo folder where the fcs files to be analyzed are stored. FlowJo executes the template using this data, performing the specified analysis determined by the template.
3) -saveAs /Users/username/Desktop/CommandLineDemo/TCellDataInitialWorkspace.wsp
Saves the workspace created from executing the template to the directory and with the name indicated. Thus, to see the workspace when FlowJo has completed its execution, you can open the TCellDataInitialWorkspace.wsp in the CommandLineDemo folder.
4) -outputFolder /Users/username/Desktop/CommandLineDemo/Output
Saves the output of the template (PDF, HTML files, etc.) to the folder indicated. Thus, if a PDF batch report is specified in the Layout Editor of the TCellSubsets template, this PDF will be saved to the “Output” folder.
The general form of this for Mac is:
open -W -g -a /Applications/FlowJo.app --args flowjo command line arguments (see below)
Command line arguments
The first argument MUST be a reference to one of the following file types:
.wspt – a FlowJo template
.wsp – a FlowJo workspace
.acs – a FlowJo ACS file
.txt – a list of sample files
If the first argument is a FlowJo template, there should also be additional arguments to specify the path to individual fcs files or the path to a folder of fcs files. n.b. that you must use quotes to reference any file directories that have spaces in them.
The following reserved arguments are optional and can be in any order:
-save
When all operations are complete, save the FlowJo workpace. If the first argument is a template or sample list file, a new workspace is created. If the first argument is an ACS file, then a new workspace version is created and the table of contents is updated.
-saveAsACS
When all operations are complete, save all data and imported files to an ACS container file. A new workspace version is created and the table of contents is updated.
-doComp
If this option is specified, FlowJo will use the compensation wizard to generate a compensation matrix. Samples that are automatically assigned to the Compensation group will be used, and if successful, the compensation matrix will be saved to a file. In addition, the compensation wizard gating graphs will be saved to a layout in the layout editor, and a report will be generated to show the gating used.
-prefs
Use the given prefs file when FlowJo is initializing. If this argument is omitted, then the user’s default prefs file is used.
-outputFolder
This is the folder where the output files from automated batching and export are placed.
-importCLR
This specifies a folder containing CLR files to be imported into the workspace. If the name of a CLR file includes the sample file name, then the CLR file is imported for that sample.
-keepCacheDir
If data files are referenced by an http URI, files are downloaded to FlowJo’s cache folder. This folder is normally deleted when FlowJo exits. If this argument is specified, the cache folder is not deleted.
-outputEngineInfo
Before FlowJo exits, it will write a file named ‘EngineInfo.xml’ that contains information about data files and engine requests. If the -outputFolder is specified, it will write to that folder.
-showCache
When all operations are complete, output the contents of the FlowJo engine cache to the console.
-verbose
Print extra information about the execution of command line FlowJo.
-dataFolder
This is an alternative folder in which to search for fcs data files that cannot be found.
-inputCompMatrix
Import the specified comp matrix xml file into the workspace, and apply the matrix to all samples.
-sampleQuality
Perform the sample quality check for each sample, and output a file named SampleQualityInfo.csv.
-help
Output to the console information about the command line arguments.
-uniqueId
If this option is specified, the name of output files will include the same timestamp.
-allGraphs
Generate a graph to the file system for each sample and population in the workspace. The graph’s format (jpg, png, etc) is determined by the preference for the graph window’s file format. The graph’s type (pseudocolor, histogram, etc) is determined by the graph specification in the workspace.
-batch
This option can be included to export layouts to pdf. The layout will only be exported if it has been set to “Batch to: PDF” and the “Command Line” option is selected.
-batchTable
This option can be included to export the Tables from the Table Editor. The layouts will be exported using the settings assigned to them in the table editor.