Once you have set up the folder and uploaded the FCS files
, you can import a FlowJo workspace and then use LabKey Server to extract data and statistics of interest.
This topic uses the same example workspace as in the Set Up Flow For LabKey Analysis
walkthrough, but covers the import wizard in more detail.
Import a FlowJo Workspace
1. Select Analysis
- Click the My Flow Tutorial link to return to the main folder page.
- Click Import FlowJo Workspace Analysis. This will start the process of importing the compensation and analysis (the calculated statistics) from a FlowJo workspace. The steps are numbered and the active step will be shown in bold.
- Select Browse the pipeline.
- In the left panel, click to expand the labkey-demo directory, then click the Workspaces folder.
- In the right panel, select the labkey-demo.xml file, and click Next.
- Notice the two warnings that appear.
Sample 118756.fcs (286): 118756.fcs: S/L/-: Count statistic missing
Sample 118756.fcs (286): 118756.fcs: S/L/FITC CD4+: Count statistic missing
We have intentionally incorporated these warnings to illustrate the point that if the FlowJo workspace is missing calculations for any statistics, those values won't be imported. If this were real data and you were required to import these statistics, you would have to go back to FlowJo, re-calculate the missing statistics, and then save as xml again. For the sake of this tutorial, you can safely ignore these warnings.2. Select FCS Files
3. Review Samples
- Select Browse the pipeline for the directory of FCS files.
- Click the "labkey-demo" folder to open it.
- In the right panel, check the box for the FACSData folder.
4. Analysis Folder
- The import wizard will attempt to match the imported samples from the FlowJo workspace with the previously imported FCS files. If you were importing samples that matched existing FCS files, such as reimporting a workspace, they would have a green checkmark and unmatched samples would have a red checkmark. To manually correct any mistakes, select the appropriate FCS file from the combobox next to the sample's name. See below for more on the exact algorithm used to resolve the FCS files.
- Confirm that all samples (= 68 samples) are selected and click Next.
- Accept the default name of your analysis folder, "Analysis".
- (Optional) Choose a target study folder. If the flow metadata includes PTID and Date/Visit columns matching those in the study, information from the study will be included in the FCSAnalyses table.
- Click Next.
- Review the properties and click Finish to import the workspace.
- Wait for Import to Complete. While the job runs, you will see the current status file growing and have the opportunity to cancel if necessary using the "Cancel Job" button. Import can take several minutes.
- When the import process completes, you will see a datagrid named "labkey-demo.xml." To learn how to customize this datagrid to display the columns of your choice, see this topic: Step 1: Customize Your Grid View.
Resolving FCS Files During Import
When importing analysis results from a FlowJo workspace or an external analysis archive, the Flow Module will attempt to find a previously imported FCS file to link the analysis results to.
The matching algorithm compares the imported sample from the FlowJo workspace or external analysis archive against previously imported FCS files using the following properties and keywords: FCS file name or FlowJo sample name, $FIL, GUID, $TOT, $PAR, $DATE, $ETIM. Each of the 7 comparisons are weighted equally. Currently, the minimum number of required matches is 2 -- for example, if only $FIL matches and others don't, there is no match.
While calculating the comparisons for each imported sample, the highest number of matching comparisons is remembered. Once complete, if there is only a single FCS file that has the max number of matching comparisons, it is considered a perfect match. The import wizard resolver step will automatically select the perfectly matching FCS file for the imported sample (they will have the green checkmark). As long as each FCS file can be uniquely matched by at least two comparisons (e.g, GUID and the other keywords), the import wizard should automatically select the correct FCS files that were previously imported.
If there are no exact matches, the imported sample will not be automatically selected (red X mark in the wizard) and the partially matching FCS files will be listed in the combo box ordered by number of matches.
Name Length Limitation
The names of Statistics and Graphs in the imported workspace cannot be longer than 400 characters. FlowJo may support longer names, but they cannot be imported into the LabKey Flow module. Names that exceed this limit will generate an import error similar to:
11 Jun 2021 16:51:21,656 ERROR: FlowJo Workspace import failed
org.labkey.api.query.RuntimeValidationException: name: Value is too long for column 'SomeName', a maximum length of 400 is allowed. Supplied value was 433 characters long.