Agentflow is a Python toolkit for reproducible flow cytometry analysis, with a command-line interface and an optional desktop gate editor. It is designed for scientists running repeated experiments and screens, especially panels with a few fluorescence channels and straightforward gating.
Define samples and conditions in a CSV sample sheet, review gates visually, and save the analysis as YAML or JSON. The same configuration can be rerun from the command line or Python, including by coding agents. A bundled, modified copy of FlowKit provides the analysis engine.
Active development — early evaluation release. Interfaces, configuration formats and workflows may change. Pin a commit for reproducible work. Generated gates are starting points for human review, and synthetic tests do not establish validation for your instrument, controls or assay.
Please cite FlowKit (White et al., 2021) when publishing papers, preprints, or reports using Agentflow results, alongside Agentflow's version or commit. FlowKit provides the underlying analysis engine: doi:10.3389/fimmu.2021.768541. To cite Agentflow itself, use the Zenodo concept DOI, which always resolves to the latest archived version: doi:10.5281/zenodo.23718421. Each release also has its own version DOI on Zenodo; v0.10.0 is 10.5281/zenodo.23718422. See scientific credits and methods wording and CITATION.cff for the full author list and reference.
AI coding assistants have been used to help write this package's code and documentation. OpenAI Codex assisted with the attribution documentation and export changes in this update. This is a disclosure about this package's development, not a claim about how the upstream software was written. A complete historical inventory of AI tools, model versions, and per-file contributions is not maintained. The human maintainer remains responsible for release decisions and scientific claims; AI assistance does not establish correctness or imply that every contribution has received independent human review.
Validation uses synthetic fixtures and regression tests around the bundled FlowKit 1.3.2 engine. These checks do not establish validation for every instrument, control, or assay; see current validation limits.
- Review hierarchical polygon, rectangle, histogram, Boolean and reporter-ratio gates in a Qt/Matplotlib desktop interface.
- Apply shared gates across samples, with explicit sample-specific exceptions.
- Compare samples using scatter, density, contour and histogram plots, group colors, and mean or median fluorescence summaries.
- Apply embedded or imported compensation matrices, or estimate spillover from user-defined single-stain control populations.
- Run batches without a display, export per-event Parquet and summary CSV, and exchange supported gate definitions through Gating-ML.
- Preserve gate settings, input fingerprints, reported instrument metadata and software provenance for review and reruns.
Python 3.14 or newer and uv are required for the
source-checkout instructions below. The distribution is agentflow-cytometry;
the Python import and executable are agentflow. It is not currently published
on PyPI and is unrelated to other packages named AgentFlow.
git clone https://github.com/Deliverome-Project/agentflow.git
cd agentflow
uv syncThis installs the headless analysis tools. For the desktop editor:
uv sync --extra gui
uv run agentflow guiThe repository is currently private while public-release preparation is underway;
cloning requires access until its visibility changes. On minimal Ubuntu systems,
the desktop also needs libegl1, libopengl0 and libxkbcommon0. Headless analysis
does not require Qt.
To use Agentflow in another Python project, pin a specific reviewed commit:
uv add 'agentflow-cytometry @ git+https://github.com/Deliverome-Project/agentflow.git@<commit-sha>'Replace <commit-sha> with the full commit identifier and retain your lockfile.
The bundled demo generates three samples and four single-stain controls. All files and suggested gates are labelled DUMMY / EXAMPLE — NOT VALIDATED; no experimental data is needed.
uv run agentflow demo --out local-examples/synthetic
uv run agentflow run local-examples/synthetic/workflow/samples.csv \
--recipe local-examples/synthetic/workflow/recipe.json \
--out local-examples/synthetic/run-01Open local-examples/synthetic/run-01/report.html to inspect the results. Plot images are embedded, so the HTML can be viewed on its own. Keep the complete
run folder to open linked tables, gates and provenance.
With the desktop extra installed, edit the same experiment:
uv run agentflow edit --samples local-examples/synthetic/workflow/samples.csv \
--recipe local-examples/synthetic/workflow/recipe.json --gate liveThe example hierarchy is scatter → singlets → live cells, with GFP, mScarlet and
Cy5 populations as parallel children of live cells. The viability stain and
reporter assignments are synthetic examples, not recommended detector mappings.
Save your edits, then rerun into a new output directory such as run-02.
Start with uv run agentflow inspect sample.fcs to examine acquired detector
names, marker labels and embedded compensation. Use the desktop import workflow
or the CLI walkthrough to create a draft recipe, then
review detector assignments, controls and gate boundaries for your experiment.
A sample sheet requires unique sample_id and fcs_path columns. Paths may be
relative to the sheet. Add condition and group for meaningful plot labels and
colors; plate maps require explicit plate and well columns. Other annotations,
such as dose and replicate, are retained as metadata. See the
sample-sheet and screen workflow guide.
uv run agentflow validate gates.yaml
uv run agentflow run samples.csv --recipe gates.yaml --out runs/experiment-01Batch QC rendering uses four processes by default; add --workers 1 to reduce
memory use. Plate summaries cache exact all-event statistics separately from
event arrays, and the editor yields between samples while preparing a comparison.
See performance measurements and reproducible benchmarks.
Source FCS files are not modified. Counts use all events, regardless of plot subsampling or zoom. Event analysis/export proceeds one sample at a time, with bounded parallel QC rendering; missing channels and failed samples produce errors rather than silent omissions. Completed runs use new output directories.
New fluorescence assignments default to logicle, with the upper range taken from the detector metadata. Scatter defaults to linear. Existing recipes retain their explicit transforms; changing a display preview does not change gate membership. Transform… edits a detector's recipe transform (for example logicle W when negatives pile up at zero) and migrates its gates through raw signal so they keep their boundaries; see the screen workflow guide. Histogram gates default to bounded intervals.
The population gallery supports navigation between gates, and sample comparisons use a fixed 2×2 grid. Fluorescence summaries show up to 30 samples per page and can follow the selected population. Mean and median are computed before display transforms, after compensation when applied. MFI means arithmetic mean here; replicate averaging and error bars are not inferred automatically.
Editing a gate marks that gate reviewed; affected descendants need separate review. Saving alone does not approve untouched draft gates. See saved analyses and review state for details.
Choose an embedded FCS matrix, import a labelled spillover matrix, or calculate one from explicitly selected positive and negative populations in single-stain controls. The control viewer uses logicle with raw-signal thresholds; display transforms do not change control selection or matrix estimates. Both CLI and desktop workflows are available:
uv run agentflow compensation import matrix.csv --out compensation.json
uv run agentflow compensation estimate controls.json --out estimated.jsonThe estimator uses differences in positive/negative medians; it is not a spectral unmixing workflow. Inspect control quality and before/after plots before applying a matrix. An identity matrix applies no correction and does not establish that compensation is adequate. Changing compensation invalidates gate review flags. See control configuration and matrix conventions and current validation limits.
| Output | Contents |
|---|---|
report.html and figures |
Gate-review plots, result tables and acquisition QC |
summary.csv |
Population counts, percentages, signal statistics and sample metadata |
events.parquet |
Individual events, metadata and population membership |
gates-*.gatingml.xml |
Per-sample gates, transforms and resolved compensation |
reproducibility.yaml |
Replayable recipe with software and input provenance |
run.json, recipe.json, samples.csv |
Execution record and configuration snapshots |
Keep the original FCS inputs, sample sheet, recipe and pinned environment. Snapshots identify inputs but do not bundle them or recreate the environment. Reported instrument fields are recorded as metadata, not independently verified calibration; missing values remain unknown. Inspect raw acquisition keywords for personal or sample identifiers before sharing outputs.
Desktop saves also write a *.reproducibility.yaml snapshot. Git installations
record their installation commit; checkouts record commit and dirty status.
Retain uncommitted source changes if you run from a dirty checkout. Wheels without
Git metadata record a version and source fingerprint instead of inventing a commit.
from agentflow import analyze_sample, load_recipe
from agentflow.batch import run_batch
recipe = load_recipe("gates.yaml")
statistics = analyze_sample("sample.fcs", recipe)
run_batch("samples.csv", "gates.yaml", "runs/new-run")Agents can inspect inputs, prepare sample sheets, validate recipes and run batches through the same Python and CLI interfaces used by people. The desktop editor is optional; it provides human review of the saved configuration. Gating-ML exports mathematical gate definitions, while the recipe retains application settings and review annotations. See the recipe reference and architecture.
Bug reports and reproducible examples are welcome. Use synthetic or appropriately shareable data, and include your version, command and error output. Current plans are in the roadmap and workspace design; proposed features there are not necessarily implemented.
uv run ruff check .
uv run pytest -q
uv buildAgentflow is created and maintained by Becca Carlson, its sole listed project author. This designation applies to Agentflow, not its bundled dependencies. FlowKit retains Scott White's copyright and its accompanying BSD 3-Clause license. Fonts and standard XML schemas retain their own terms and copyright holders. No upstream endorsement is implied. See third-party notices.
Original Agentflow code and documentation are licensed under the MIT License, copyright 2026 Becca Carlson. This grant excludes bundled third-party code, schemas and fonts, which retain their own licenses and notices. Public distribution of the complete bundle remains subject to the outstanding release review.
Dependency quarantine, credential scanning, release-content guards, and desktop CI are documented in Security checks.
Plots now default to density-colored dots: blue is sparse and red is dense. Threshold gates open against a second detector (usually SSC-A); choose Plot settings → Histogram for a one-dimensional view, or Threshold plot Y to change the second axis. Counts always use every event. Axes and selectors show FCS stain names alongside the original detector IDs, with configurable per-instrument channel aliases (a CytoFLEX table is built in) as a fallback. See channel names and MA900 metadata and 96-well performance measurements.
In Edit gate mode, drag inside a rectangle or completed polygon to move the whole gate; drag its handles to reshape it. For polygons, Ctrl+click inserts a vertex on the nearest edge and right-clicking a vertex removes it. To draw a new polygon, press Esc, click each point, then click the first point to finish (no modifier key is needed). The Draw polygon action also starts a fresh polygon. Pan/Zoom mode and alternate-axis previews do not edit gates; switch back to Edit gate and the gating axes first.
Select a population and choose Rename population… below the population tree (or from the Analysis/right-click menu in the multi-sample viewer). Names are shared across samples: choose All samples before renaming. Children, Boolean references and sample-specific adjustments follow the new name; membership and review status are preserved. Undo/Redo includes renames. Save writes the new name to the recipe; previously exported results are unchanged until rerun.