Analyze Flow Cytometry Data

Cytometry is a full flow analysis environment in the browser. Upload FCS files, draw gates, compensate, cluster, and pull statistics out, with no desktop software and nothing to install.

The workspace has two tabs. FCS Datasets holds your files. Analysis holds the gating work you build from them.

Uploading FCS Files

Files live in datasets, which group the files you want to analyze together: a panel, a run, an experiment.

New dataset opens the upload dialog box. Drop your .fcs files on the left, then on the right either name a new dataset and choose whether it's private or shared, or pick one you already have. Once a dataset exists you can also drag files straight onto it.

Each file you add lists what its header says is inside, the event count, the number of parameters, the cytometer that wrote it, and the file size, so you can catch the wrong tube before it uploads rather than after. A file whose name appears twice in the list is marked Duplicate. A file that isn't FCS at all is flagged there and left out of the upload, and the rest of the batch still goes.

Conspecta supports FCS 3.0, 3.1, and 3.2, which covers everything a current cytometer writes. Version 3.1 checksums are verified on the way in. Files stored as ASCII text rather than binary aren't supported.

An FCS 2.0 file still opens, but it's from the 1990s and some of its legacy encodings can be misread, so Conspecta flags it rather than pretending the result is trustworthy. Re-export from your acquisition software if you can.

Opening a dataset gives you its files as a table: name, sample, event count, cytometer, size, and upload date, with the tube, well, and tube-label identifiers from the file's own keywords underneath the name. Anything the parser couldn't read is flagged rather than hidden. From here you can select files to start an analysis over just the ones you ticked, attach them to a sample, move them to another dataset, or remove them.

The Sample column names the specimen each file was acquired from, and clicking it opens that sample. Sort by it to bring the files nobody has attached yet to the top. Those read Attach instead of a name. A file pooled from several specimens names the first and counts the rest.

Attach, or Change on a file that already has a sample, opens the picker for that one file with its current specimens already ticked under Selected. Tick another to add it; untick one to detach the file from it; Save applies both at once. Saving with nothing ticked detaches the file from every sample, which is how you undo an attachment without leaving the dataset.

Attach to sample in the toolbar does the same for every file you've ticked, and only adds. The sample's Connections tab then lists those files, and Flow analysis on the sample opens a cytometry analysis over them, so the chain from specimen to result holds together without you retyping anything. If every file you ticked carries the same tube label and exactly one sample answers to it, that sample is marked Suggested at the top of the picker. You still choose. The tube label is whatever someone typed at the cytometer, so Conspecta offers a match and never makes one for you.

Add a description… under the dataset's name records what the run is (the panel, the harvest day, the condition), so the context travels with the files. Press Enter to save.

Deleting a dataset sends it to Trash, restorable for 30 days.

Bringing Gating In

Reading a Gating File

Import gating, on a dataset's toolbar, reads a FlowJo .wsp workspace or a Gating-ML 2.0 file (.xml or .gml, the standard FlowJo, Cytobank, and the R CytoML packages write) and shows you what's in it. For a workspace that means each sample, its gating hierarchy, the counts FlowJo recorded, and whether the matching data file is already in this dataset. Reading changes nothing, so it's safe to do before you've decided anything. The file stays on your machine and is read in your browser.

Counts start out labelled as FlowJo's, because until you ask for more they're what FlowJo last calculated rather than anything Conspecta has worked out. A gate Conspecta can't rebuild is listed and marked with the reason in plain words on its own row, never quietly dropped, so what you see is the whole strategy and not just the parts that came across.

Workspaces from FlowJo 10 are supported. Version 9 and earlier used a different format and are refused with a message rather than read incorrectly. The same goes for Gating-ML 1.5, an older version of the standard: export the file as Gating-ML 2.0 and try again.

Checking a Workspace Against Your Data

Check against my data rebuilds the strategy, runs it over the files in this dataset, and puts Conspecta's own count beside FlowJo's for every population. Each row then says whether the two agree, differ (showing both numbers), or couldn't be checked, and a population Conspecta couldn't rebuild is never counted as agreement. This is the honest version of "does it work on my data", and it's worth reading before you rely on any of it.

Expect most populations to match to within a fraction of a percent and some to differ. Ellipse gates are rebuilt exactly as the file states them, and FlowJo's own count can still sit a fraction of a percent away, because FlowJo counts events through a slightly grown, screen-resolution copy of its own ellipse. A gate on a marker that a spectral instrument never stored can't be rebuilt at all and says why, because the workspace calculates it from the raw detector channels and Conspecta doesn't yet reproduce that calculation.

The check runs only when you ask, because it downloads and reads every matching file, and flow files are large. Samples are done one at a time and a file that won't load is reported and skipped rather than stopping the rest.

A Gating-ML file carries gates, axis scales, and a compensation matrix but no samples and no counts, so there is nothing to check. Its strategy is rebuilt the moment the file is read, and anything refused says why before you decide to keep it.

Keeping It, or Taking It Elsewhere

Once you've read the receipt, Save as gating strategy keeps what came across. Each sample becomes a gating template in this project, holding its gates, the plots they sit on, the compensation matrix if the file stated one, and a note of the file it came from, which you then apply to a flow analysis the same way as any other template. For a FlowJo workspace the button appears only after the check has run, so a strategy can't be kept before you've seen the numbers it produces. For a Gating-ML file it appears as soon as the strategy is rebuilt, since there are no numbers to show. Populations that couldn't be rebuilt aren't in the template, and the template's description says how many were left out.

Export as Gating-ML writes a gating strategy out as a .xml file in the ISAC Gating-ML 2.0 standard. FlowJo, Cytobank, and the R CytoML and flowWorkspace packages all read it, so gating built or kept in Conspecta can go back out again. It's in two places: Export as Gating-ML in a template's ⋮ menu writes that template, and the same button in the import window writes each rebuilt workspace sample as its own file. To send the gating you're working on right now, save it as a template first and export from there. That leaves your project a named copy of the strategy, which is the version worth sending anywhere.

Export as FlowJo .wsp, in the same template menu, writes the strategy as a FlowJo 10 workspace file instead, the format FlowJo opens directly. The file carries one sample holding your gating tree; FlowJo will ask where the data lives when you open it, which is normal for a workspace whose files aren't beside it. Quadrant gates are written the way FlowJo itself writes them, as four corner populations. Two things this format can't say: a combined population that complements one of its inputs in place (rebuild it with a NOT population first), and two shape gates that use different axis scales on the same channel, since a workspace states one scale per channel.

In both formats, gates that can't be stated exactly are left out rather than approximated, and each one is named on screen with the reason, so you know what the file doesn't contain before you open it somewhere else. A gate is also left out when the plot it was drawn on has been deleted (without the plot, the scale its shape was drawn in is unknown), and when the gate it sits under, or a gate it combines, was itself left out, since a file referencing a gate it doesn't hold won't open cleanly anywhere.

Gating-ML describes gating and nothing else, so plots, layouts, colours, and notes don't travel with it. Use it to move the gating, and keep the analysis in Conspecta.

What Imports, and What Doesn't

Nothing is ever approximated on the way in. A gate that can't come across exactly is refused with the reason on screen, because a plausible wrong count is worse than a refusal.

Creating an Analysis

Files and analysis are separate on purpose. The same FCS files can back more than one analysis, and an analysis can draw on more than one dataset.

New analysis asks for a name, whether it's private or shared, and which datasets to include. If a dataset is still uploading, the button waits and says how many files are left, so an analysis never starts on half a panel.

The Workspace

The middle of the screen is a single zoomable canvas holding your plots as a tree, wired together by the gates between them. Drag to pan, scroll to zoom, and use the minimap in the corner on a large tree.

The sidebar is grouped by what you're doing:

Undo and redo sit at the bottom, and Cmd/Ctrl + Z / Cmd/Ctrl + Shift + Z do the same. They cover every change to the analysis: gates, plots, axes, channel names, compensation, templates, and a gate customized for a single file. A drag counts as the one move it looked like, not the hundred steps it took to get there. Loading and removing files is not on that list, since those change what you are looking at rather than what you have done to it. Everything saves automatically, and Cmd/Ctrl + S does nothing on purpose so the browser's save dialog can't interrupt you.

A large file loads in two passes: a 20,000-event preview appears immediately so you can start drawing, then the full resolution arrives behind it. Statistics always use every event, never the preview.

Project members with view-only access can open an analysis, read every gate and statistic, run comparisons, and export, but the gate tools and editing controls aren't offered. Templates stays in their sidebar and opens the library read-only, so they can look through the lab's strategies, read the discussion, and export one, not apply or change one.

Gating

Pick a gate from the Gates menu or press its key, then draw on a plot.

Three more sit in the same menu. Boolean Gate combines populations you already have with AND, OR, or NOT, and any population you've selected can be flipped to its opposite with a NOT toggle, so "CD4-positive but not CD25-positive" is a single gate. Generate Combinations is for co-expression work at panel scale: pick 2 to 8 gates and it counts every positive and negative pattern across them, so you read CD4+ CD8-, CD4+ CD8+, and the rest out of one table instead of drawing each by hand. Each row shows its events and share of the parent population you choose, empty patterns stay hidden until you untick Hide empty, and Create gate turns any row into a real Boolean gate. Singlets finds FSC-A against FSC-H, draws the doublet-discrimination gate for you, and adds the plot if you don't have one.

H returns you to the move tool. Esc cancels a gate you're partway through drawing. A drag that's too small to be a real gate is refused rather than creating something microscopic.

As soon as a gate exists, Conspecta asks you to name it, suggesting a name from the axes. Cancel deletes the gate, so if you meant to keep it with the suggested name, press the confirm button rather than closing the dialog box.

What a Gate's Label Says

On the plot itself, each gate carries a small label: its name, and under it the percentage of its parent population that fell inside. The name picks up a suffix in two cases.

· this file means the gate's boundary has been tailored for the tube you're viewing, through Customize for this file. Its count differs from the same gate on your other tubes on purpose, and its outline is drawn dashed to match. See Flow Files and Templates.

· 2/3 means the gate could be placed on two of your three loaded files but not the third, usually because that file's panel is missing a channel the gate was drawn on. A gate that reaches every file says nothing, so a suffix here always means something needs looking at.

Once a plot carries more than eight gates, which is what turning a clustering run into gates gives you, the labels drop to names alone so they stop covering each other. Hover a gate, or select it, to read its percentage.

The Gate Badge

Between a parent plot and the plot beneath it sits the gate's badge, and it's the control surface for that gate. It shows the gate's color, its name, and how many events fell inside it as a count and a percentage.

While you drag a gate, the badge tracks it with a running estimate, marked with a ~ because it is measured on a sample of the events rather than all of them. Let go and the exact number replaces it.

Click the name to rename it. Click + to create a child plot from this population. The ⋮ menu holds the rest: change its color, add a note explaining why the gate sits where it does, Show Stats, Lock Gate so a stray drag can't move it, Drill Down, Export FCS to download that population as its own file, Save population to project to keep it in the project instead, and Delete Gate. With more than one file loaded it also offers Customize for this file, which lets you move the gate on the tube you're viewing without moving it on the others. See Flow Files and Templates.

Save population to project writes the population as a new FCS file among your project's files, prefilled with the gate and source file names, so you can work on a subset as its own dataset. The saved file remembers which analysis and gate it came from: its row in the dataset's file table and its File Information panel both read Derived from, and the link opens the source analysis. Derived from follows the source analysis's own sharing, so it shows for anyone who can open that analysis and is left off for everyone else. The file stays available to the whole project either way; only the line saying where it came from is held back, so a private analysis doesn't announce its gate names through the files it produced. The dialog box also offers to open a new analysis on the saved file right away, linked to the same sample as the analysis you saved from. Members with view-only access keep Export FCS but not this.

A quadrant's four corners get badges of their own. A corner is one of the populations the quadrant cut rather than a gate in its own right, so its badge covers that corner: Show Stats, Drill Down, Export FCS, and Save population to project. Renaming, notes and Delete Gate stay with the quadrant gate itself. Its color swatch recolors the whole quadrant, for the same reason.

Deleting a gate takes its descendants with it, and names them in the confirmation so you know what you're about to lose.

The Hierarchy

The tree of plots is your gating hierarchy. There's no separate population list to keep in sync: the plot beneath a gate shows that population, and the path above the plots reads out the full gating route, such as All Events › Lymphocytes › CD3+ › CD4+. Click any step in that path to jump back up.

Double-click a gate, or use its + button, to open a child plot beneath it. Conspecta picks sensible axes and scaling for the new plot.

A polygon or ellipse is stored as the shape you drew, which only means something against the axis scaling of the plot you drew it on. Remove that plot and Conspecta can no longer confirm how to count it, so a banner names the gate and its numbers should be treated as provisional until you add a plot back with the same two parameters under the same parent gate. Rectangles, ranges, and quadrants are unaffected, because their edges run along the axes and land in the same place at any scaling.

Back-gating is on each plot's ⚙ menu, which lists the populations gated beneath that plot and overlays any of them on it, in a color you choose. It's the fastest way to answer "where did those cells sit on the original scatter".

Parameters

Click an axis label to change what it shows. The menu lists every channel in the file, then a Computed section for anything produced by clustering or dimensionality reduction, then the scale: Lin, Log, Logicle, or Asinh.

Rename Parameters, under Analysis → Cell Analysis, gives channels readable names. Rename FL2-A to CD8 PE once and it reads that way on every axis, in every statistic, and in every export.

Keyboard