GateLabR

Interactive manual gating for SingleCellExperiment objects in R.

Open-source flow cytometry and CyTOF (mass cytometry) gating app for R — with FCS import, fluorescence compensation, hierarchical population trees, and Gating-ML exchange, all persisted inside the object.

📖 Documentation & Getting Started

GateLabR runs the same TypeScript/React interface as GateLab, backed by a thin R host for hand-gating flow cytometry and mass cytometry (CyTOF) data directly on SingleCellExperiment objects. It slots into Bioconductor-based analysis pipelines (e.g. CATALYST, diffcyt) where the events already live in R as an SCE and you want a fast, reproducible alternative to round-tripping through FlowJo or Cytobank just to draw a few gates.

Gates are drawn on an interactive D3.js canvas. Gates, populations, scales, assay bindings, compensation provenance and illustration settings persist in the SCE via metadata(), while explicit commands write panel labels to rowData() and population, division or sample annotations to colData().

For the same style of manual gating directly from FCS files without an R installation, see GateLab, the companion browser app. GateLabR is the better fit when data already live in a SingleCellExperiment or when gated populations need to return directly to colData for a Bioconductor pipeline.

Features

• Draw and edit gates interactively. Polygon, rectangle and quadrant gates on any pair of channels, with click-and-drag vertex editing, undo / redo, and per-gate colour and label.
• Positive AND population trees. Build hierarchies of populations from gate references — each population is the intersection (AND) of its gates within its parent; counts and percentages update live.
• Flow and CyTOF modes. Auto-detects the instrument type from channel names. Flow uses per-channel logicle for fluorescence and arcsinh for FSC / SSC scatter, with editable W and cofactor; CyTOF channels use arcsinh (cofactor 5).
• Flow and CyTOF compensation. Inspect, edit, sweep and apply spill matrices in the shared Compensation tab. GateLabR performs the durable calculation in R, installs a revisioned full-size SCE assay atomically, preserves the original assay, and restores saved compensated assays without recomputation. Existing compensated SCE assays can be adopted directly.
• Cytobank-compatible Gating-ML 2.0 import / export. Round-trip supported gates and positive AND population trees through Cytobank and other ISAC Gating-ML 2.0-compliant tools. Files containing NOT or OR populations, or gates whose channels cannot be matched to the loaded data, are rejected before import rather than being partially or silently altered. (FlowJo uses its own .wsp format and does not round-trip Gating-ML.)
• Workspace persistence. Gates, populations, scales, active assay, compensation provenance and illustration settings are saved inside the SCE and re-loaded automatically.
• FCS export. Export gated populations as FCS files, optionally split by sample_id.
• Sample filter and multi-sample overlay. Filter by any colData column and overlay multiple samples with distinct colours.
• Statistics tab. Per-population, per-channel summary stats (count, % parent / total, median, mean, geometric mean, SD, CV) exportable to CSV.
• Cell-division profiler. A CFSE / CellTrace dye-dilution tab: draggable per-sample division gates on a 1-D histogram (Div0…DivN), a marker-vs-dye biplot with density contours, and per-cell division calls written back to colData.
• Composition preview. A Proportions tab for quick stacked-bar and boxplot previews of any colData composition (e.g. cluster or division proportions by condition), with per-sample averaging and faceting.
• Figure export. Strategy and Illustration tabs render publication-style multi-panel grids. Illustration includes biplot and histogram grids, stacked ridgelines, and population-by-channel median / mean expression heatmaps with per-channel, per-population or z-score scaling and three colour palettes. SVG export uses gridSVG to produce Adobe Illustrator-friendly grouped vector files (rasterised data, vector axes / gates / labels).

How GateLabR compares with other tools

GateLabR fills a specific gap: an interactive GUI for gating that lives natively on a SingleCellExperiment, so it slots into a Bioconductor pipeline instead of replacing it — while keeping full R access to the same object.

	GateLabR	FlowJo	Cytobank	CytoExploreR / flowGate
Interface	GUI (Shiny) + full R access	GUI (desktop, proprietary)	GUI (cloud, proprietary)	R, with interactive gating helpers
Data object	SingleCellExperiment (Bioconductor-native)	.wsp workspace	cloud workspace	GatingSet (flowWorkspace)
Cost / licence	Free, MIT, open source	Commercial	Commercial	Free, open source
Flow / CyTOF	Both (auto-detected)	Flow-focused	Both	Flow-focused
Gates persist in the object	Yes — in metadata(); reload restores everything	Workspace files	Cloud workspace	GatingSet on disk
Gating-ML 2.0 exchange	Yes (positive AND populations)	No	Yes	Partial
Downstream hand-off	Populations → colData for diffcyt / CATALYST / any SCE tool	Export gated FCS	Export gated FCS	GatingSet → downstream

Note the Gating-ML row: of the two dominant GUIs, only Cytobank exchanges ISAC Gating-ML 2.0 — FlowJo does not (it uses its own .wsp format). GateLabR speaks Cytobank-compatible Gating-ML, so supported gate geometry and positive AND population trees move losslessly between GateLabR and Cytobank. Broader Boolean logic may be considered in a future update if there is user demand.

FlowJo is a trademark of Becton, Dickinson and Company. GateLabR is an independent project and is not affiliated with or endorsed by BD or FlowJo.

GateLabR suits two workflows. If your data already lives in R as a SingleCellExperiment, it lets you gate without round-tripping to FlowJo or Cytobank and hand populations straight to diffcyt / CATALYST. But it's equally at home as a plain FCS-in → gate → FCS / stats / Gating-ML out tool: import .fcs files, gate interactively in the GUI, and export — no R fluency needed beyond the one line to launch it.

Installation

GateLabR can be used either as an installed R package or straight from a clone.

Option A — install as a package (recommended)

# install.packages("remotes")            # if needed
# Bioconductor dependencies are resolved automatically; if you don't already
# have BiocManager, install it first: install.packages("BiocManager")
remotes::install_github("david-priest/GateLabR")

library(GateLabR)
launchGatingApp()        # or launchGatingApp(my_sce)

Option B — clone and run from source

# 1. git clone https://github.com/david-priest/GateLabR.git
# 2. From an R session, install dependencies once (CRAN + Bioconductor):
source("path/to/GateLabR/install_dependencies.R")
# 3. Source the launcher and run (see Quick start):
source("path/to/GateLabR/launch.R")
launchGatingApp()

Dependencies (installed automatically by Option A, or by install_dependencies.R for Option B):

• CRAN: shiny, DT, jsonlite, base64enc, uuid, sp, gridSVG, png, ggplot2
• Bioconductor: SingleCellExperiment, SummarizedExperiment, S4Vectors, flowCore, xml2

R ≥ 4.2 and Bioconductor ≥ 3.16 are recommended.

Quick start

# Installed package:           Or from a clone:
library(GateLabR)              # source("path/to/GateLabR/launch.R")

# Option A: launch and pass an existing SCE
launchGatingApp(my_sce)

# Option B: launch with no SCE — the app scans the global environment
#           and lets you pick from any SingleCellExperiment objects present
launchGatingApp()

The app opens in your default browser. launchGatingApp() now starts the shared React interface. During the transition, launchLegacyGateLabR() starts the previous GateLabR-specific Shiny interface (including its former UMAP view). The three-column layout is:

Panel	Content
Left	SCE samples and workspace / Gating-ML / FCS actions
Centre	Interactive plot (tabs: Gating | Strategy | Illustration | Statistics | Panel)
Right	Gates list, population tree, bulk-rename controls

Typical workflow

1. Get your events into the app, either way:
   • Load an existing SingleCellExperiment — e.g. from CATALYST prepData() (CyTOF) or one you've built from flowCore / your own pipeline.
2. Call launchGatingApp(sce), or call launchGatingApp() to use the first SCE already loaded in your global environment.
3. Draw gates on the central plot; the gate list and population tree update live.
4. Build populations by referencing one or more gates; multiple references use AND logic.
5. Export results for downstream work — populations as new colData columns on the SCE (Export Population, e.g. for diffcyt, CATALYST, or any SCE-aware analysis), or gated events back out as .fcs.
6. Save the SCE (e.g. saveRDS(sce, "gated.rds")) — the workspace is embedded in metadata() and reloaded next time.

Data persistence

GateLabR stores its canonical workspace and host provenance inside the SCE:

metadata(sce)$gatelab_workspace
#> revisioned GateLab workspace JSON (gates, populations, scales and settings)

metadata(sce)$gatelabr_compensation
#> compensation profiles, assay bindings, revisions and provenance

rowData(sce)$gatelabr_label
#> optional Panel-tab display-name overrides

The established metadata(sce)$gating_workspace mirror remains available for compatibility with the previous GateLabR interface.

File formats supported

• Input: SingleCellExperiment assays and Cytobank Gating-ML 2.0 XML.
• Output: FCS, Gating-ML 2.0 (Cytobank-compatible or standard re-importable), SCE .rds / .qs2 (with embedded workspace and assays), per-population colData columns, CSV statistics, SVG / PDF figures.

Related

figtracer — a plain-text, git-tracked electronic lab notebook (ELN) for reproducible bioinformatics: it threads the figures your R / Python analysis produces into living, provenance-tracked lab notes. GateLabR gates your cells; figtracer keeps the resulting figures and analysis as a reproducible written record. Together they cover the single-cell / cytometry workflow from gating to lab notebook.

Citation

If you use GateLabR in published work, please cite the Zenodo archive:

Priest, D. G. (2026). GateLabR: Interactive manual gating for SingleCellExperiment objects. Version 1.0.0. Zenodo. https://doi.org/10.5281/zenodo.20404387

BibTeX:

@software{priest_gatelabr_2026,
  author    = {Priest, David G.},
  title     = {GateLabR: Interactive manual gating for SingleCellExperiment objects},
  year      = {2026},
  version   = {1.0.0},
  doi       = {10.5281/zenodo.20404387},
  url       = {https://github.com/david-priest/GateLabR},
  publisher = {Zenodo}
}

GitHub's "Cite this repository" button (powered by CITATION.cff) renders formatted citations in several styles.

License

MIT — see LICENSE.

Acknowledgements

GateLabR is developed in the Wing Lab at the Immunology Frontier Research Center (IFReC), Osaka University.

Built on top of the Bioconductor stack (SingleCellExperiment, SummarizedExperiment, flowCore), the Shiny web framework, and D3.js for the interactive plot.

Issues and contributions

If you run into a bug, or there's a feature you'd find useful, please open an issue or get in touch — I'm happy to take a look and would be glad to implement it.

A note on .fcs import: import has been thoroughly tested on files from a BD spectral flow cytometer, but not yet on files from other vendors (Beckman Coulter, Cytek, Sony, Thermo, Miltenyi, …). Channel and instrument detection is designed to be vendor-agnostic, but if a file imports incorrectly — missing markers, wrong channels, or a mis-detected flow/CyTOF mode — please let me know (ideally with the file's channel names) and I'll get it sorted.

A note on compensation: embedded-$SPILLOVER compensation has been validated on conventional fluorescence data from a BD FACSAria III / FACSymphony S6, with compensated values matching flowCore::compensate. It has not yet been exercised on embedded matrices from other vendors' acquisition software; the matrix is read vendor-agnostically (flowCore::spillover), so if compensation looks wrong for a given file please send me its channel names and spillover keyword and I'll take a look.