Sharing Flow Cytometry Analysis Across Labs: Workspace Files and Reproducibility Pitfalls

You email a collaborator your FlowJo workspace file so they can replicate your gating on their cohort. A week later they reply: the file opens, but the FCS files are listed as missing, the gates land in the wrong places after they relocate the files, and their percent-positive numbers differ from yours by a meaningful margin. Nobody made an obvious mistake — the workspace travelled, but the analysis did not. This post enumerates the specific FlowJo workspace file collaboration across labs pitfalls that cause this, and the practical steps that prevent each one.

Why workspace files are deceptively portable

FlowJo workspace files (.wsp) are XML documents that reference FCS files by path and encode gate coordinates, transform parameters, and statistics tables. They do not contain raw data. That design is fast and small but makes the workspace fundamentally a description of a local environment: file system, FlowJo version, instrument, and a particular transform configuration. When the workspace moves to a different environment, anything the environment supplies can drift — and most of the failures below are exactly that kind of drift.

Mistake 1 — Shipping the .wsp without the FCS files in the same folder structure

What it looks like: collaborator opens the workspace and every sample shows “Missing FCS”. They relocate the files manually and the workspace works again — but if the original gating was on an instrument where parameter naming differs between brands, relocated files may load with different channel labels.

Why it happens: workspace files reference FCS files by path, not by content. Some lab paths are absolute (/Volumes/CoreLab/Experiment_2025-03/FCS/), others relative to the workspace location. Either way, the path embedded in the workspace rarely survives the trip to a new environment.

How to avoid it: put the .wsp and all referenced FCS files in a single folder, zip the folder, and ship the zip. Use relative paths in the workspace (FlowJo’s “Save As” with the “portable” option keeps paths relative). Document the folder structure in a README inside the zip so a collaborator who hits a path issue can locate files manually.

Mistake 2 — Assuming the same biexponential transform across FlowJo versions

What it looks like: gates appear in slightly different positions on the collaborator’s plots even though the workspace XML lists the same gate coordinates. Percent-positive values shift 2–8% from the original analysis.

Why it happens: gate coordinates are stored in transformed (display) space, not in raw channel values. FlowJo’s proprietary biexponential transform — informally “Biex” — uses internal lookup tables that have changed between major versions (FlowJo 9, 10.x, and v11), and the “width basis” default differs slightly. A gate drawn at x = 100 on FlowJo 10.8 may correspond to x = 102 on FlowJo 11 because the underlying data-to-display mapping shifted.

How to avoid it: state the FlowJo version in your collaboration email and methods section. If the version mismatch is unavoidable, export the analysis as Gating-ML 2.0 alongside the .wsp — Gating-ML 2.0 stores gate boundaries with explicit transform definitions (logicle T, W, M, A) rather than software-version-dependent lookups. The ISAC Gating-ML 2.0 standard exists specifically to make gates portable across software.

Mistake 3 — Sending pre-compensated FCS files with the compensation matrix still attached

What it looks like: collaborator opens the workspace, FlowJo detects the $SPILLOVER keyword in the FCS files, and applies compensation on top of data that was already compensated at acquisition. Populations end up double-corrected and visibly distorted.

Why it happens: most cytometers export uncompensated data with the spillover matrix embedded as metadata, expecting the downstream software to apply it. Some older workflows (and some clinical labs running on a specific BD configuration) export pre-compensated data with the matrix still embedded. The receiving software cannot distinguish “already compensated” from “uncompensated with matrix” without a clear flag.

How to avoid it: state the compensation status of every shipped FCS file in writing — in the README, in the email, and in the methods if this is publication-bound work. Better: ship uncompensated FCS files and let the receiving software apply the matrix, which is the standard modern practice. If you must ship pre-compensated files, strip the $SPILLOVER keyword first or set it to the identity matrix so downstream software does not apply it again. The spectral overlap compensation primer covers the math behind why double-compensation is unrecoverable without re-acquiring the data.

Mistake 4 — AI-assisted gates do not travel with the workspace

What it looks like: your workspace has gates that were AI-suggested and accepted — the analysis is correct on your machine. The collaborator opens it and the gates are there, but if they add new files to extend the analysis, the AI gate suggestions are not available because the model was trained on your account, not theirs.

Why it happens: per-user AI gating (Cytomaton’s k-NN model, FlowJo Workspace AI in newer versions) trains on the operator’s prior gating history. The model lives in the user account, not the workspace. The collaborator inherits the gates you drew but not the model that would suggest the next ones.

How to avoid it: do not rely on AI-assisted features for cross-lab collaboration unless the receiving lab has either (a) the same tool with shared/team-level training, or (b) explicit re-training on a comparable gate corpus. For high-stakes collaborations, draw all gates manually so the workspace is self-contained. Document any AI involvement in methods (algorithm, training-set size, what was accepted vs adjusted) so the analysis is reproducible by humans even if the AI is not.

Mistake 5 — Spectral unmixing references do not transfer between instruments

What it looks like: spectral FCS files from your Cytek Aurora ship to a collaborator with a different Aurora. They cannot reproduce your unmixed populations because the reference spectra for each fluorochrome are instrument-specific.

Why it happens: spectral unmixing uses single-color reference spectra recorded on the specific instrument, on the specific day, with the specific laser-power and detector-gain settings. References from your instrument do not validly unmix files from theirs; laser drift over weeks invalidates even your own references for new files. The reference is a per-acquisition asset, not a panel asset.

How to avoid it: for cross-lab spectral collaborations, ship the raw (unmixed) FCS files alongside the reference spectra you used for unmixing (FlowJo and SpectroFlo export both as part of the experiment package). Document the autofluorescence extraction reference. If the collaborator’s instrument differs, they must record their own references against their cells and re-unmix. Do not ship unmixed-only files and expect the unmixing to be reproducible.

Mistake 6 — Different keyword settings change parameter labels silently

What it looks like: gates designed against the “FITC-A” channel appear on a different channel when the collaborator opens the workspace, because their FlowJo instance reads $PnS (long name) while yours read $PnN (short name) for axis labels.

Why it happens: FCS files carry two parameter labels per channel — $PnN (the machine-required short name) and $PnS (the optional long descriptive name). Software preferences determine which one shows up on axes and gate definitions. BD instruments put detector names in $PnN; older instruments and some Cytek workflows use generic channel numbers there and put the meaningful name in $PnS. FlowJo’s “Use $PnS for labels” setting is global and varies between installations.

How to avoid it: rename channels in your FCS files to have consistent $PnN and $PnS before sharing (most analysis tools have a “rename parameters” bulk action). State in your README which label the workspace was built against. For long-term reproducibility, FCS 3.2 added explicit $PnTAG (dye), $PnANALYTE (target), and $PnDET (detector) keywords that resolve this ambiguity — converting to FCS 3.2 before sharing is the cleanest option if your software supports it.

Mistake 7 — Statistics tables exported as percentages, not raw values

What it looks like: collaborator wants to recompute MFI or CV on a different gating strategy but the export only contains percentages and counts. They have to re-run the entire analysis from the raw FCS files because the statistics layer was thin.

Why it happens: FlowJo’s default Layout/Table editor exports the statistics column you chose to display. If the displayed columns were only “% of Parent” and “Count”, that is all the export carries — even though the underlying data has MFI, CV, percentile values, and per-marker medians available.

How to avoid it: when shipping a final analysis for collaboration, export the comprehensive statistics table — for every gate, include % parent, % total, event count, median FI (specify per parameter), CV, and geometric mean FI where biologically relevant. Use explicit column names that name the statistic (Median_FI_CD3-FITC, not “MFI”). The downstream lab will not always have time to re-open the workspace and re-export; the file you ship should be the file they can use directly.

Practical workflow for a robust cross-lab handoff

Before sending an analysis to a collaborator:

• Zip the .wsp file, all referenced FCS files, and a README into one archive. Use a folder structure that mirrors what the workspace references.
• Include in the README: FlowJo version (or other analysis-tool version), instrument model, acquisition date, panel description (fluorochrome → marker map), compensation status of FCS files, transform used (FlowJo Biex with width basis value, or Gating-ML 2.0 logicle parameters), and any AI-assisted analysis with the algorithm details.
• Export the gating template separately as Gating-ML 2.0 alongside the .wsp. This is the open-format insurance policy — if the .wsp opens with drift, the Gating-ML 2.0 is the canonical record.
• Export a comprehensive statistics table with explicit column names. Ship as both CSV and (where available) GraphPad Prism (.pzfx).
• For spectral data, include the reference spectra files and an explicit autofluorescence reference note. State whether unmixed or raw data is being shipped.
• State which channel-label convention the workspace assumes ($PnN or $PnS). Consider renaming channels to consistent labels before sharing.

This adds maybe 20 minutes to the export step. It saves the back-and-forth that otherwise occupies multiple email threads, plus the version-control mess that follows when two labs end up with slightly different versions of “the” analysis.

When .wsp is the wrong format entirely

If the collaborator uses different analysis software, .wsp is not portable. Open and cloud alternatives to FlowJo exist, but none of them read .wsp directly with full fidelity — gate types, transform parameters, and statistics templates require interpretation. For cross-software handoff, Gating-ML 2.0 is the only format with broad ISAC-compliant support across FlowJo, Cytomaton, CellEngine, and the R/Bioconductor flowCore stack.

For long-term archival reproducibility — the kind required by the NIH Data Management and Sharing Policy — ship Gating-ML 2.0 and uncompensated FCS files with embedded $SPILLOVER metadata. That combination is independent of any single vendor and reads correctly in any compliant tool, ten years from now. The .wsp file is convenient for the next collaborator over; Gating-ML 2.0 is what the field-wide reproducibility infrastructure was built to consume.

Before designing the next panel that will eventually need to ship across labs, the fluorophore spectrum viewer shows which dyes you can substitute when a collaborator’s instrument has a different detector configuration than yours. Panel-level portability starts at design, not at handoff.