Import a Flow Workspace and Analysis

2024-03-29

Premium Feature — Available with all Premium Editions of LabKey Server. Learn more or contact LabKey.

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 a similar example workspace as in the Set Up a Flow Folder walkthrough, but includes intentional mismatches to demonstrate the full import wizard in more detail.

Import a FlowJo Workspace


  • In the Flow Tutorial folder, under the Flow Summary section, click Upload and Import.
  • Click fileset in the left panel to ensure you are at the 'top' level of the file repository
  • Drop the unzipped DemoFlowWizard folder into the target area to upload it.
  • Click the 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.
1. Select Workspace
  • Select Browse the pipeline.
  • In the left panel, click to expand the DemoFlowWizard folder.
  • In the right panel, select the ADemoWorkspace.wsp file, and click Next.

Warnings

If any calculations are missing in your FlowJo workspace, you would see warnings at this point. They might look something like:

Warnings (2):
Sample 118756.fcs (286): 118756.fcs: S/L/-: Count statistic missing
Sample 118756.fcs (286): 118756.fcs: S/L/FITC CD4+: Count statistic missing

The tutorial does not contain any such warnings, but if you did see them with your own data and needed to import these statistics, you would have to go back to FlowJo, re-calculate the missing statistics, and then save as xml again.

2. Select FCS Files If you completed the flow tutorial, you may have experienced an accelerated import wizard which skipped steps. If the wizard cannot be accelerated, you will see a message indicating the reason. In this case, the demo files package includes an additional file that is not included in the workspace file. You can proceed, or cancel and make adjustments if you expected a 1:1 match.

To proceed:

  • If you have already imported the tutorial files into this folder, choose Previously imported FCS files in order to see the sample review process in the next step.
  • If not, select Browse the pipeline for the directory of FCS files and check the box for the DemoFlowWizard folder.
  • Click Next.
3. Review Samples
  • The import wizard will attempt to match the imported samples from the FlowJo workspace with the FCS files. If you were importing samples that matched existing FCS files, such as reimporting a workspace, matched samples 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 in the Matched FCS File column. See below for more on the exact algorithm used to resolve the FCS files.
  • Confirm that all samples (= 17 samples) are selected and click Next.
4. Analysis Folder
  • Accept the default name of your analysis folder, "Analysis". If you are analyzing the same set of files a second time, the default here will be "Analysis1".
  • Click Next.
5. Confirm
  • 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. Import can take several minutes.
  • When the import process completes, you will see a grid named "ADemoWorkspace.wsp" To learn how to customize this grid 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.

Related Topics