CytoWeave 0.8.1

CytoWeave 0.8.1 corrects its citations: the methods paragraph it writes for spectral unmixing, and the credits in the README, on the Science page and in the documentation.

Fixed

• Credit for per-cell autofluorescence matching. Per-event autofluorescence in the Spectral view is the per-cell autofluorescence matching of AutoSpectral (Burton OT et al., bioRxiv preprint 2025, doi:10.1101/2025.10.27.684855), which CytoWeave did not cite. It is now cited in the methods paragraph CytoWeave writes whenever per-event autofluorescence is used, in the README, on the Science page, in the spectral documentation and in the code. The AutoSpectral example data used by the validation suite are credited to their authors (Burton, Dooley and Liston, Mendeley Data, doi:10.17632/ch5dnspd79.1).
• The methods paragraph's sentence on spectral unmixing pasted the Spectral view's help text into the paragraph and cited Roet et al. whatever was done with autofluorescence, even when it was left out. It now names the method and how autofluorescence was unmixed, and cites Roet et al. (several signatures) and AutoSpectral (per-cell matching) only when they were used. An unmixing with one autofluorescence signature records only the signature it used.
• The README and the Science page said CytoWeave reimplements published methods; they now say methods from published papers and preprints, and their lists of methods add spectral unmixing (Novo et al.), several autofluorescence signatures (Roet et al.), per-cell autofluorescence matching (AutoSpectral) and compensation by robust regression (AutoSpill).
• The design notes (cytoweave-spec/research.md) no longer describe AutoSpectral's code, and give the preprint's authors correctly.

CytoWeave 0.8.0

CytoWeave 0.8 makes an analysis provable, explainable and teachable. A reproducibility certificate packs an analysis with its files and records every number it reported, so anyone can compute them again (in the window, with cytoweave verify or by an agent) and see each one confirmed; a review report is one HTML file a PI or reviewer opens without CytoWeave, every number traced to its source; the change log is hash-chained. Virtual FMO controls predict where a population's negative would end without a dye, and the panel optimizer chooses each marker's dye from the instrument's own noise model. A public agent benchmark grades AI agents working through CytoWeave's tools against the simulated truth. Teaching mode adds eighteen exercises that check a learner's answers against that truth, on examples that together now demonstrate every analysis, with files from FlowJo 11, FACSDiva and SpectroFlo to try the imports on.

Added

• Exercises (teaching mode). Eighteen exercises on the examples, from gating T cells to a mass cytometry cohort's differential abundance, open from the start page, the workspace menu or the command search (web/lib/exercises.js, web/ui/exercises.js). Each opens its example as a new workspace with new data (a different seed, and for many exercises another planted problem: the sample with the clog, the degraded tandem, the population that differs) and without the simulator's truth: no truth channel, no annotation naming a fault, a neutral name. A panel at the right of the window holds the question, hints that open one at a time, and answers chosen or typed there (one of your gates, a sample, a channel, a choice, a number); Check scores each part against the truth with partial credit (a gate by its F1 against the true events), and Reveal shows what was planted, adds the truth channel and colors the events a gate missed or took in wrongly. A class code gives a class the same data. The workspace keeps only the exercise, its seed, the answers and the checks: the answer key is computed again from the seed when needed, and only for the files that seed makes (SHA-256). Undo and redo leave an exercise's progress as it is. The panel appears only in a workspace an exercise made, and folds into a tab.
• The examples, together, demonstrate every analysis. The PBMC example gains a CD25 FMO tube, a tube of 8-peak rainbow beads with its datasheet (QC → Calibration fills in its MEF values), a second day for donors D04–D06 with other detector settings (shared gates need adjusting for them) and a CSV table of the donors' age, sex and CMV status. Two new examples: Absolute counts (lyse/no-wash whole blood from three patients in tubes of counting beads, every patient's cells per µL known) and Spectral panel, day 2 (the 25-color panel on the same cytometer with two faulty reference controls, for the unmixing doctor and the spectral library). Examples can come with files other programs would have written, offered when the example opens and from Files that came with this example… in the workspace menu: a FlowJo 11 workbench (FlowJo example), a FACSDiva experiment (index sort), a SpectroFlo experiment (25-color spectral), CSV events of a third culture (cell cycle) and the PBMC annotations. The index sort's presort file is written with a DATA offset one byte off, which the reader repairs and reports. The Example experiments dialog can make any example with ten times the events.
• QC → Live → Try it with an example replays an example as an acquisition (the QC showcase's wells, or thirty days of rainbow beads): its files land one every few seconds and are checked as they land, without an instrument or the program (it works in the browser).
• A bead sample can carry its lot's datasheet values (sample.beadDatasheet), which QC → Calibration fills in.
• An agent benchmark. Graded analysis tasks for AI agents working through CytoWeave's tools (benchmark/): gating, a compensation error, a paired comparison, acquisition QC, a spectral fault, a titration, a dose-response plate, a bead assay, calcium kinetics and a PDF report, each on an example with a seed of its own and graded by code against the simulated truth, with partial credit. The harness starts CytoWeave and prepares the task itself, then runs the agent as a separate program with CytoWeave's tools only (Claude Code with no files, shell or web, none of the user's settings); results go to benchmark/results/ and the website's Agent benchmark page. Version 2: every prompt starts by saying the data are already open (in version 1, two prompts echoed an example's description and agents opened that example instead of analyzing the task's data); runs record whether the agent replaced the data, and --transcripts keeps each session.
• check_compensation (agents): a compensation matrix checked against the single-stain controls, as Compensate → Check against the controls does; the entries that are off, largest first, with their suggested values.
• Panel optimizer. Spectral → Panel design → Optimize the assignment chooses the dye for each marker of a panel. Give each marker its expression (high, medium, low, or molecules per cell), tick the markers found on the same cells, and optionally fix a dye. Every marker's stain index is predicted from its dye's brightness, the unstained control's background carried through the unmixing, and the spread every co-expressed marker adds at its own brightness (photon noise and laser fluctuations of the spread model). The assignment with the least noise relative to signal is found: by trying every one for small panels, by a seeded local search for large ones. The design lists each marker's dye, stain index, what limits it and the next best dye, compares it with the experiment's own panel, and flags dyes on the same cells that can pass energy (a tandem with its donor, a donor emitting where another dye absorbs). A design can be kept in the instrument's spectral library; once the panel is run, its predicted spread is checked against the run's controls. It also works from the library alone, before any control is run (Keep for the instrument now keeps the unstained control's background with the noise), and for conventional panels from a compensation computed from single-stain controls (Compensate → Optimize the panel…). Agents: design_panel.
• A table of 50 common dyes (web/lib/dyes.js): relative brightness, absorption and emission maxima, and the dye a tandem is built on.
• Virtual FMO controls. Where a population's negative for a marker would end without its dye, predicted from the panel's spread model instead of stained as an FMO tube: each event's value without the dye is an unstained event of the population's scatter gates plus the spread every other dye adds at the event's own brightness (photon and laser noise), drawn with a fixed seed; the threshold is the 99.5th percentile. In a plot's menu (Virtual FMO), the plot draws the threshold and, on a plot of two channels, its curve along the other axis, beside the line of an FMO control in the workspace; the line under the plot gives the threshold, the FMO and unstained controls', the dyes the spread comes from, and Gate above it (a range gate from the threshold up). The spread model is now kept where it is fitted: with a compensation computed from single-stain controls, and in the spectral setup with the spreading matrix. Agents get virtual_fmo (optionally proposing the gate). It is a guide: compensation and unmixing errors, mismatched reference spectra and nonspecific binding are what a real FMO shows and a prediction of spread does not.
• The PBMC and spectral examples can generate FMO tubes of the first donor's cells (fmos: markers).
• Review reports. Report → Review report (also Workspace → Export) writes the analysis as one HTML file for a PI, collaborator or reviewer who opens it in any browser without CytoWeave: the samples with their files' SHA-256, annotations and compensation; the gating hierarchy, scales and every population's count in every sample; every sample's gates drawn on its own events with each gate's % of parent; the workspace's figures and tables; the saved comparisons (test, groups, effect sizes, post-hoc tests, each sample's value, a dot plot); the methods, MIFlowCyt and the change log with the state of its chain. Every number is traced: clicking it shows its exact value, the counts behind a percentage, the sample and its file's checksum, the compensation and each gate above the population. The numbers are computed from the files with the code certificates use. The file loads nothing from the network (inline styles, inline SVG plots with PNG data URIs) and follows the reader's light or dark theme. cytoweave run --review writes one (review.html), and agents and scripts get export_review_report.
• Reproducibility certificates. Report → Certificate packs the analysis with everything needed to compute its numbers again and records every number it reported: an ISAC ACS archive (<analysis>.certificate.acs) holding the workspace, the FCS files (or, when the data cannot be shared, only their checksums), the channels the analysis stored (clusters, embeddings, unmixed channels), the gates as Gating-ML, the methods, a README, and certificate.json with the CytoWeave version and the browser that computed the numbers, each input's SHA-256, the analyses with their parameters and seeds, the head of the change log's chain, the MIFlowCyt items filled in with what the workspace records, and every number: each population's count in each sample, every table cell with its detection-limit status, and every saved comparison of one measure (each sample's value, the test, group summaries, effect sizes, post-hoc tests). Its fingerprint, the SHA-256 of certificate.json, is quoted with the analysis. Opening a certificate verifies it: every file's checksum, the workspace, the change log and the fingerprint c...

CytoWeave 0.7.0

CytoWeave 0.7 makes moving to it easier, explains poor unmixings, and takes on plate-based assays and automation. FlowJo 11 workbenches, FACSDiva experiments, FACSChorus gates and SpectroFlo reference controls import with a fidelity report, FlowJo 11's own counts reproduced for every population of twelve workbenches FlowJo 11.2 saved; the unmixing doctor names the likely cause of a poor unmixing (a missing or wrong reference, a degraded tandem, autofluorescence the controls lack) and tries its fix; kinetics measures a calcium flux over time; a Plates view lays out a plate, shows any statistic across it with Z′, fits dose-response curves and reads bead immunoassays (LEGENDplex, CBA) against their standard curves, checked against R's drc and beadplexr; and cytoweave run applies a template to a folder of files without a window, for nightly runs, pipelines and CI.

Added

• FlowJo 11 workbenches. A .flowjo file opens like a FlowJo 10 workspace, in the same import dialog and migration report: polygons, rectangles, ellipses, ranges and quadrant gates (a quadrant whose arm was moved off center becomes the rectangles each quadrant covers), Boolean populations (counted within their operands' parent, as FlowJo does), gates adjusted for one sample, compensation matrices, groups, and linear, log and biexponential scales. The report compares every population with the count FlowJo stored in the workbench. FlowJo 11 counts events on its display grid (an event is in a polygon when the grid point it falls on is, in an ellipse when the center of its grid cell is); evaluated that way, CytoWeave's reading gives FlowJo 11's own count for every population of twelve workbenches FlowJo 11.2 saved (quadrants drawn in FlowJo 11 within 3 events). The report explains the small differences of CytoWeave's exact geometry.

• FACSDiva experiments. An experiment exported from FACSDiva as XML opens in the same dialog: each tube becomes a sample matched to its FCS file, each specimen a group, with the experiment's compensation and its gates (rectangles, polygons, intervals, quadrant gates, Boolean and "rest of" populations) on the linear, log or biexponential axes they were drawn on; Diva's biexponential is read as the logicle it approximates. Tubes of a specimen with the same gate share it, each with its own position; when some tubes' FCS files are in the workspace, the others' gates are left out. On the experiment CytoML is tested with, every count equals CytoML's, and gates on linear axes reproduce Diva's own counts on its display grid.

• FACSChorus gates. FCS files from FACSChorus (FACSDiscover S8 and A8, FACSMelody) carry the gates of their recording; when such files open, CytoWeave offers to import them (also Workspace → Import → Gates FACSChorus recorded in the files), through the same dialog: polygons and rectangles, exact on linear and log axes and rectangles on any axis; a polygon on a biexponential axis is approximated (FACSChorus does not record the axis' width); FACSChorus's automatic saturation gates are reported, not imported. FACSChorus stores no counts in its files, so there are none to compare.

• SpectroFlo experiments. Opening a SpectroFlo experiment (.Expt) with its raw control files lists its reference controls (fluorochrome, marker, beads or cells, the detector SpectroFlo gated each on, the unstained control) matched to the files, and marks them for the Spectral view. CytoWeave computes each spectrum from its file: the spectra stored in the experiment do not match the controls' own events on public data, so they are not used.

• The import dialog and migration report name their source (FlowJo, FlowJo 11, FACSDiva or FACSChorus), and agents' open_files opens .flowjo workbenches, FACSDiva experiments and SpectroFlo experiments.

• The unmixing doctor. The Spectral view's Diagnose tab names the likely causes of a poor unmixing of the selected sample and population, most likely first, each with its evidence, a chart of the spectrum at fault and a fix that was tried on the same events (its effect is shown):

  • a dye in the sample without a reference: light no signature explains, its spectrum estimated from the events that carry it and named from the spectral library when it holds it;
  • a reference that does not match the dye in the sample: a control holding another dye or lot (the library's spectrum fits the sample), or a dye that emits differently on capture beads than on cells;
  • a tandem degraded in the samples or in its control: its donor's negative population rising in proportion to it;
  • a cell control whose positives carry autofluorescence (markers on myeloid cells, eosinophils or macrophages);
  • autofluorescence the unstained control does not describe: the sample's autofluorescent cells fitted worse than the control's own (fixation, another tissue), or cells the control lacks.

  One click applies a fix to the reference library (a library spectrum or the spectrum the sample shows, the control set aside, autofluorescence signatures added, every signature per event), as one undoable step; the samples are then unmixed again. Agents get it as diagnose_unmixing.

• Kinetics. A population's signal, or the ratio of two channels (Indo-1 violet/blue), against acquisition time, as in a calcium flux (population menu → Kinetics): the median (or mean) per time bin, smoothed, over the events' density; the stimulus found where acquisition paused to add it (or entered, or the response's onset); and the response measured against the baseline: peak, time to peak, half-max time, amplitude, fold, area under the curve, end level and the share of responding cells (above the baseline's 99th percentile, net of the baseline's share). Other samples' curves overlay at their stimulus, every sample can be measured at once, results are saved and written into the methods, and agents get it as kinetics.

• A calcium-flux example: Indo-1-loaded PBMC with buffer, two doses of anti-CD3, ionomycin and an injection without a pause, the simulator keeping every cell's calcium. The simulator gained pauses in acquisition and cell states that change during it (pauses, modulate).

• Plates. A Plates view places samples acquired from a plate in their wells, from their $WELLID or WELL ID keywords, their names (Plate1_A01.fcs) or a well annotation. The layout (compound, dose, control, standard, specimen, dilution) is kept as sample annotations: set on selected wells (rows, columns, blocks), filled in as a dilution series, or imported from CSV, either one row per well or plate maps as R's plater writes them (a layout dropped on the window is recognized). Any statistic of a population shows as a heat map across the plate, with the screen's Z′ from its positive and negative control wells (robust Z′ optional), wells with too few events hatched, and the values as CSV or a plate map.

• Dose-response curves. Four- and five-parameter log-logistic fits per compound, in R drc's parameterization: the EC50 or IC50 with its 95% confidence interval, Hill slope, bottom, top and R², on the raw statistic, % of controls or % inhibition (asymptotes fixed at 0 and 100 optionally), with weights 1/Y or 1/Y². Curves no better than a flat line, or with an EC50 beyond the doses or not determined, are flagged and drawn dashed. Results are saved and written into the methods; agents get plate, plate_layout (proposed for review) and dose_response.

• Bead immunoassays (LEGENDplex, CBA). Each bead group's analytes found by their level of the classification dye (once, from every well), each analyte's reporter MFI on the standards fitted with a standard curve (five-parameter by default, weighted 1/Y²), and every well's concentration read from it and multiplied by its dilution, with the quantifiable range from the standards' recovery and CV (FDA 2018) and the limit of detection from the blanks; replicates averaged with their CV. From the Plates view or a bead population's menu; agents get bead_assay.

• Headless runs. cytoweave run --template panel.cwt --output results/ FILES… applies an analysis template to FCS files without a window, for a core's nightly runs, pipelines and CI: it opens CytoWeave in a headless Chrome (or Chromium, Edge, Brave), applies the template with the window's own code, accepts what it applied as the user who started it, and writes the template's tables (an Excel workbook and a CSV per table), the batch report of its last figure, the workspace, the methods and run.json (each input's checksum, each step's outcome, every population's count in every sample, and what was written). --annotations adds sample annotations or a plate layout, --qc runs acquisition QC first, --flowjo adds a FlowJo workspace, and --steps runs any sequence of the agent actions from a JSON file. The exit status says whether every step succeeded (0), one failed (1) or the command line was wrong (2); outputs already in the folder are refused before anything runs unless --overwrite is given.

• Agents and scripts get export_workspace (the workspace as a .cwz file), apply_template takes a template file's contents (templateJSON), and export_table writes a Tables table as CSV or TSV exactly as the Tables view's CSV button does (table).

• Two examples: a drug screen on a 96-well plate (six compounds at ten doses inhibiting T-cell activation, with control wells, every IC50 known) and a LEGENDplex-like cytokine bead assay (8 analytes on two bead sizes, standards and 20 sera of known concentrations).

• The spectral example's simulator can plant these faults (options of generateExample: controlSubstitutes, beadShift, unstainedCells, and degradationIn for tandemDegradation), and knows Alexa Fluor 488, BB515 and Alexa Fluor 647.

Fixed

• Files that agents, scripts and runs export are created with the permissions any new file gets (the user's umask); they ...

CytoWeave 0.6.1

CytoWeave 0.6.1 fixes computing a compensation matrix from the controls of spectral files.

Fixed

• Compensate on spectral files. Compute spillover failed with "Cannot read properties of undefined" on spectral files, whose reference controls name their fluorochrome (for unmixing) rather than a detector. The Compensate view now says that spectral files are unmixed in the Spectral view, with a button to it; only controls assigned one of their file's detectors are used, so compensating chosen detectors of spectral files works; and an agent's propose_compensation gets the same explanation. The diagnostics buttons are disabled, with the reason, until there is a matrix to check (they did nothing), and the hint asks for a sample when none is selected.

CytoWeave 0.6.0

CytoWeave 0.6 brings a lab's routine bench work into one place, batch by batch. Samples are compared with a control (% positive by SED, Overton and probability binning) and rare populations reported with exact intervals and detection limits; formula channels, calibrated MEF units from beads and absolute counts add the numbers a core reports; a figure becomes a batch report for every sample or subject as a PDF or a PowerPoint deck, and tables go to Excel and Prism with every number traced; events come in from CSV files and go out concatenated, downsampled or as AnnData for scanpy; Compare tests differential state with diffcyt-DS-limma, giving diffcyt's numbers in R; and R and Python clients drive CytoWeave from scripts.

Added

• Comparing samples with a control. Tables gained statistics computed against a control sample's population on a channel, for when stained and unstained cells overlap too much for a gate: % positive by SED (Bagwell's enhanced normalized subtraction, as FlowJo calls it) and by Overton's cumulative subtraction, probability binning's T(χ) (above 4: the distributions differ, p < 0.01) and the share of events in excess of the control, and the Kolmogorov–Smirnov D. A column names its control sample and, if it differs, the control's population; Compare and agents use the same statistics. A histogram with other samples overlaid shows the plot's sample against each overlay under the plot, and its legend now names the plot's own sample.

• Rare events. The lower and upper 95% limits of a population's count (exact Poisson) and of its % of parent (exact binomial) and its counting CV are Tables statistics. For a population of fewer than 10,000 events the inspector shows the counting CV, the count's interval and the parent events a 10% CV would take; its frequency interval is now exact (Clopper–Pearson) rather than Wilson's.

• Detection limits. A count or frequency column can carry limits from chosen blank and low-level samples, as CLSI EP17 and Armbruster & Pry (2008) describe: the limit of blank (mean + 1.645 SD of the blanks, or their 95th percentile), the limit of detection (plus 1.645 × the low-level samples' pooled SD) and each sample's lower limit of quantification (the lowest level measured with the target CV, never below the events that give that CV by counting). Values are marked ND or < LLOQ, and CSV exports add each value's status.

• Formula channels. A channel computed for every event from others: a ratio, a sum, a logarithm ([CD4] / [CD8], log([CD25]), 2 * ([FITC-A] - 100) / ([PE-A] + 50)), with channels by marker or detector and the functions log, ln, exp, sqrt, abs, asinh, min and max. The dialog (an axis's channel menu, or Workspace → New formula channel) checks the expression as you type and previews it on the current sample; the channel is then plotted, gated and tabulated like any other, and Workspace → Computed channels lists them. Formula channels travel with templates, rebuilt from the matched channels; a ratio goes into Gating-ML exports as an fratio transformation.

• Calibrated units from beads. QC → Calibration converts channels to MEF or ERF units from a multi-level bead sample, as FlowCal does: the levels are found (together on chosen channels), each level's median matched to its datasheet value, levels near the ends of the range left out, and the bead model fitted with the beads' own fluorescence. The calibrated channels ("FITC-A MEFL") are added to the samples acquired with the beads' settings; calibrating again with other beads gives those samples their own curve.

• Absolute counts. A Tables statistic of cells per µL from counting beads (the bead population, beads in the tube, µL of sample), with a dilution factor that can come from a sample annotation; the $VOL concentration takes the dilution too.

• Computed channels (formulas, calibrations, ratios read from Gating-ML) are listed in plot axis menus and can be named in agent tools.

• Methods paragraphs describe and cite the comparisons, intervals and limits a workspace's tables use, formula channels, calibrations and absolute counts.

• Batch reports. Figures → Batch report repeats a figure page after page, for each sample or for each value of an annotation (each subject, each timepoint), as a multi-page PDF or a PowerPoint deck. By sample, the plots of the figure's main sample are redrawn on each sample, and plots of other samples (a control) stay on every page; by an annotation, each plot is redrawn on that value's sample matching it on the annotations that tell the figure's samples apart (each subject's stimulated tube where the figure shows the first subject's), and a missing tube or an undecided choice between replicates is reported before anything is written. Text such as {sample}, {subject} or {page} is filled on each page. Every number a report prints is recorded with where it comes from (each statistics cell's table and column, each gate label's gate) and the record goes into the file with the analysis behind the plots.

• Statistics in figures. A figure item that shows columns of a Tables table for the samples on the page (or all of the table's rows), with ND and < LLOQ where a column has detection limits; it shrinks its text to fit and counts the rows that still do not. In PowerPoint it is a native, editable table.

• Excel and Prism. Tables → Excel writes every table to one workbook, each value in full precision, with sheets that describe each column (population path, statistic, control, counting beads, limits found), the samples (files, SHA-256 checksums, events, compensation, instrument), the gating and the methods paragraph. Tables → Prism writes a GraphPad Prism project (.pzfx): the table as one data table and, grouped by an annotation, a column table per statistic with a column per group, as Prism's t tests and ANOVA take it.

• Agents have compare_distributions (every comparison of samples against a control, multivariate probability binning with several channels), rare_events (intervals, events needed and detection limits), add_formula_channel, calibrate_beads and export_report (a figure by sample or by an annotation as PDF or PowerPoint, with the pages and notes); export_table also writes Excel workbooks (a Tables table, a statistic, or every table) and Prism projects (grouped by an annotation); statistics_table, export_table and compare take a control sample for the comparison statistics, and statistics_table and export_table counting beads and a dilution.

• Events in CSV files. A CSV of events (FlowJo's Export CSV, FCS Express, R, Python) opens in a dialog that checks every column before import: the delimiter and decimal mark, FlowJo's Comp-PE-A :: CD25 headers (channel and marker), cells that are not numbers (with the row of the first), empty cells and short rows, constant columns, an event number column (left out) and label columns such as clusters or sample numbers, which can split a file into one sample per value. Each column's kind and scale are guessed (logicle for intensities, arcsinh for mass cytometry counts, linear for scatter, time and already-transformed values) and can be changed; each file becomes a sample stored as an FCS file. A CSV whose first column names samples still annotates them.

• Events out: concatenated, downsampled, AnnData. Workspace → Export → Events (or a population's menu) writes a population's events in chosen samples, every event or downsampled with a seed (up to a number per sample or a share; each sample drawn on its own, so its events do not depend on which others are exported): one concatenated FCS file with SampleID and SourceEvent channels (raw values with the shared spillover matrix, or compensated values; the samples named and checksummed in its keywords), one FCS file per sample, or an AnnData file (.h5ad) for scanpy, muon and R: X the chosen channels (arcsinh or compensated), obs the sample, annotations, populations (a True/False column per gate and the deepest as a category), clusters, QC, scatter and time, var the channels and markers, obsm the maps, uns the provenance. CytoWeave writes the HDF5 itself.

• Agents have export_events, and open_files opens CSV files of events with each column's kind, scale and checks reported.

• Differential state. Compare → Screen marker states tests whether markers change within clusters or populations between groups of samples, with diffcyt-DS-limma (Weber et al. 2019): each sample's median of arcsinh(x / cofactor) per cluster and marker (cofactor 5 for mass cytometry, 150 for fluorescence; compensated values), clusters with at least 3 cells in at least half the samples, a linear model per cluster and marker weighted by the cells in each sample with the design's pairing and covariates as fixed effects, and limma's moderated t-statistics with a mean–variance trend, adjusted across every cluster and marker. The markers a clustering was made from are left out by default (diffcyt's state markers). A volcano plot and table give each group's median, the difference, t, p and q; a population's row opens its marker's per-sample comparison. CytoWeave computes limma's statistics itself (equal to limma 3.68 in R). The methods paragraph describes the test and cites diffcyt and limma.

• R and Python clients (clients/): every CytoWeave action is an R function (cw_statistics_table(), cw_differential_analysis(), …) and a Python method (cw.statistics_table()), generated from the tools with their arguments and help, with results as data frames (R) or pandas DataFrames (Python), plots saved as PNG and refusals raised as errors with CytoWeave's reason. The clients find a running CytoWeave themselves: with --remote-control CytoWeave writes its address and token to remote.json in its data folder, readable by you only and removed when it stops. GET /api/remote/tools lists the actions. Install them from t...

CytoWeave 0.5.0

CytoWeave 0.5 is sturdier, more automatable and reusable. Its FCS reader was hardened with a fuzzer and checked on files from 42 more instrument models; an AI agent can run the whole pipeline, from QC and unmixing to clusters, figures and exports, with every change a proposal you review; an analysis becomes a template that applies to another experiment by marker, published OMIP gating strategies are placed on your own data, and every population gets a Cell Ontology term to confirm; and a new Titration view finds the amount of antibody and the detector voltage to use.

Added

• Agents across the whole pipeline. Eleven new MCP tools, so an agent can run an analysis from the files to the figures: annotate_samples (metadata, roles and stained channels), run_qc (acquisition QC, optionally with a "QC pass" gate at the top of the tree), unmix (reference spectra and autofluorescence from the controls, then unmixing), explore (clustering and maps, with the clusters as populations if asked), build_figure (a gating strategy, or plots across samples), watch_folder (QC as files are acquired, left over from 0.4), and export_flowjo, export_fcs, export_figure and export_table, which write files to the path the agent gives (in an existing folder, through a temporary file renamed into place, never replacing a file unless told to; scripts need the startup token).
• Analysis templates. Workspace → Save as a template keeps the gating tree (or one population and those under it) with its scales, plots, tables and figure layouts, and which compensation the samples used, in the library or as a .cwt file. Workspace → Apply a template matches its channels to another experiment by marker, not detector: the same marker on the same area/height/width suffix, scatter and time by name, and markers named only in a channel's label. A preview shows how each channel matched, lets you choose another, and says which populations will be left out and why (a marker the panel lacks); the gates can go under any population. Gates on computed channels are not kept; a "QC pass" gate is left out and the populations under it moved up, with a note. Agents have save_template, list_templates and apply_template, whose gates are proposed.
• Published gating strategies. OMIP-101 (major leukocyte populations: T cells with CD4 and CD8 and their naive, central memory, effector memory and TEMRA subsets; B and NK cells; classical, intermediate and non-classical monocytes) and OMIP-090 (regulatory T cells) are built in, in the Apply a template dialog and for agents. Each is written for CytoWeave from the article's gating hierarchy, with its citation and a list of where it departs from the article. Their gates are placed on the current sample's events, each in its parent population: lymphocytes and monocytes at their density peaks on scatter, positive cells above the negative population as all events show it, negative cells below the valley under the brightest mode, quadrants on one divider per axis, Tregs as CD25-high among CD127-low cells, and intermediate monocytes above the upper edge of the CD16-negative classical ones. Each gate says where it was placed and why, and is then shared by every sample like any other (adapt it to each sample where the data shift).
• Cell Ontology terms. The inspector suggests a Cell Ontology term for each population from the markers along its path (which side of each gate it lies on) and, for scatter gates, where it sits; never from its name. A suggestion is exact when every marker the term requires is gated, likely when only negative markers are not, and shows the markers it rests on and the term's definition; confirm it or choose another. 89 curated terms of the Cell Ontology release 2026-06-08 (CC BY 4.0), with the conventional phenotypes of Maecker et al. 2012 and the OMIPs; a specific term that fits on evidence its ancestor lacks comes first, and no term is suggested that contradicts its ancestors' phenotype. Confirmed terms go into FlowJo workspace exports (each population's annotation), Gating-ML, the methods (with the Cell Ontology reference) and the Tables view (under each column's name). Templates and strategies carry terms as suggestions to confirm on the new data. Agents have suggest_cell_types, which can propose terms for the user to confirm.
• Titration and voltage walks. QC → Titration analyzes a series of samples that differ in one setting, on one channel within a population. A titration's amounts are read from the file names ("CD4-PE 125 ng", "CD8 1-200", "2.5 uL") or an "amount" annotation; a voltage walk's voltages from each file's $PnV. At each step the positive and negative cells are found from the data, with their medians and rSD, the stain index (Maecker et al. 2004) and the separation index (Bigos 2007). A titration gets a saturation curve fitted to the stain index and a recommended amount: the first tested at or above twice the amount giving 90% of saturating staining (Bonilla et al. 2024), with notes when saturation is not reached or excess antibody raises the background. A voltage walk gets a voltage range: from the minimum, where the negative cells' rSD reaches 2.5 times the detector's electronic noise (BD's criterion; the noise from the cytometer's baseline report or estimated from the walk), to the maximum, where the positive cells' 99th percentile reaches the top of the linear range. Stacked histograms show every step; the result exports as a figure (SVG, PNG) and CSV for the panel's record and can be saved in the workspace, where the methods describe it. Agents have titration.
• A new example: antibody titration and a voltage walk. CD4-PE titrated on PBMC in ten two-fold steps from 1000 ng to 2 ng per test, with an unstained tube, and the PE detector walked from 300 V to 750 V; the binding constant, the detector's electronic noise and its gain at every voltage are known. The simulator now models PMT gain (the signal and its photon noise grow with the gain, the electronic noise does not).
• Samples keep each channel's voltage ($PnV) when they are added.
• More kinds of proposal. Computed results (QC, unmixed channels, clusters, maps) and figures an agent makes appear at once, marked as proposed, so their channels can be gated; sample annotations and a gate at the top of the tree wait for review. Rejecting removes the results, the populations on them and their channels; accepted QC of more samples joins the user's result. An agent never replaces a result the user made.

Fixed

• FCS files that hung or crashed the reader. A fuzzer that mutates FCS files (see Validation) found files that the reader looped on for hours or failed on with an internal error instead of a message. Each is now refused with a message that quotes the offending keyword, or read with what its data hold:
  • a bit width beyond 64 ($PnB of 10^15 in packed data looped through 10^15 bits per value);
  • a $PAR far larger than the TEXT segment could describe (10^15 parameters);
  • a negative $TOT (now ignored, with the count inferred from the data) or a negative or reversed $BEGINDATA/$ENDDATA (the HEADER's offsets are used instead);
  • ASCII and packed data whose $TOT is larger than the data can hold (2^31 events in a 1 KB file asked for 8 GB; now only the events present are read, with a warning);
  • negative supplemental TEXT offsets, which made the in-memory reader read the wrong bytes and the streaming reader fail with an internal error;
  • a missing $TOT together with a missing DATA end.
• Two instruments' files read at the wrong offset. BD Accuri C6 and Beckman Coulter CyAn files whose $BEGINDATA was written before their TEXT segment grew (pointing inside it, or 46 bytes past it) were read from there, so every event was shifted; FlowIO reads them the same wrong way. When the HEADER and the keywords disagree, a range that cannot hold the data is now set aside, and the HEADER is used when only it places DATA directly after the TEXT. The CyAn's event counter now reads 2, 3, 4 and the Accuri's time rises.
• Supplemental TEXT read with the wrong delimiter. It was split on its own first byte: a Bio-Rad S3 file, whose supplemental TEXT leaves out the leading delimiter, gained 192 junk keywords and lost its sort statistics and protocol. It is now read with the primary delimiter, and a supplemental segment that holds no keywords (Apogee's settings block, a CyFlow Cube's ZIP archive) is ignored with a note.
• Empty keyword values merged keywords. A NanoFCM file writes empty values as two delimiters in a row; they were read as an escaped delimiter, joining $PROJ and $FIL (and $OP and $SYS) into one keyword. A keyword name that contains the delimiter now counts against that reading.
• A broken later data set no longer hides the earlier ones. In a file with several data sets ($NEXTDATA), one that cannot be read is left out with a warning, and the data sets before it open.
• Long TEXT segments read 6× faster. The keyword parser copies text between delimiters in one piece instead of a character at a time.

Documentation

• A new page, Templates and cell types; the QC page covers titration and voltage walks, with a new screenshot; the AI agents page and the MCP guide list the 34 tools; the Tables docs say how CytoWeave's robust SD (BD FACSDiva's) differs from FlowJo's, which is 1.4826 × the median absolute deviation (the docs had said FlowJo used the same one); the Science page credits the Cell Ontology (CC BY 4.0). Every screenshot is retaken for 0.5.0.

Validation

• Fuzzing (new fuzz and fuzz-corpus suites; fuzz-cases.mjs, fuzz.mjs): 21 generated files in every layout the reader decodes hold exactly the values written; 20,000 seeded mutations of them (HEADER offsets, keyword values, deleted and duplicated keywords, delimiters, flipped bytes, the version line, truncatio...

CytoWeave 0.4.0

CytoWeave 0.4 covers an experiment before, during and after acquisition: it predicts a panel's spread from the instrument's own noise before the panel is run, checks each file as the instrument writes it, and tells you whether a comparison's conclusion would survive the choices another analyst might have made. It can show its colors for every kind of color vision, works from the keyboard and with screen readers, and its FlowJo workspaces now open in FlowJo 11.

Added

• Panel design: predicted spread. Spectral → Panel design predicts a panel's spreading matrix from its spectra and the instrument's noise, so you can try a change before running it. Leave a dye out or add one from the spectral library and the matrix, the complexity index and the spread each channel receives update at once; channels that receive the least spread suit dim markers. The noise has two parts, photon counting in every detector (1/Q) and intensity fluctuations of each laser, which make a dye excited by two lasers spread in proportion to its brightness. It comes from this experiment's controls (fitted when the spreading matrix is computed, with each control's spread predicted from the others as a check), from a model kept for the instrument in the library, or from its bead runs. With no files open, Spectral → Design a panel from the spectral library does the same from an instrument's library alone.
• QC as files are acquired. QC → Live (or cytoweave --watch <folder>) watches the folder an instrument exports to. Each FCS file is added to the workspace once the instrument has finished writing it (its size is steady and its header says all its data are there) and checked at once: acquisition QC for samples and controls, Q and B for bead files, added to the instrument's record and checked against the Levey–Jennings rules. A low score or a detector out of control raises a notice, the Live table lists every file with its result, and the status bar shows the watch from any view. The folder is only read; files already there are opened only on request.
• Faster acquisition QC of large files. PeacoQC's per-channel work, nearly all of its time, runs on up to four workers reading the events from shared memory, with exactly the serial result: 3.4 s instead of 10.5 s for two million events in 20 channels.
• Robustness to analysis choices. Compare → Robustness to analysis choices checks whether a two-group comparison's conclusion would change had the data been processed differently in ways another analyst might reasonably have chosen. It moves each gate on the population's path 1% and 2% of the axis, adapts the gates to each sample (one per subject when paired) or removes per-sample adjustments, takes acquisition QC away (or re-runs it stricter and looser), tries the files' and the workspace's other compensation matrices and the rank test, each alone and in random combinations (64 analyses). It says whether the conclusion holds (≥ 90%), mostly holds (≥ 70%) or is fragile, names the choices that change it and those that move the size of a difference found beyond its confidence interval, and draws the specification curve. The methods text and saved comparisons include a sentence on it, and agents have check_robustness.
• Color-vision-friendly colors. A setting in the new Appearance menu (the theme button) shows populations, groups and clusters in a palette that stays distinct with protanopia, deuteranopia and tritanopia, draws the rainbow heat maps (Classic, Turbo) as viridis, and turns the green, amber and red status colors into blue, orange and magenta. The workspace is not changed: its own colors return when the setting is off. In the default palette two of the first eight colors look the same with deuteranopia (CIEDE2000 0.8); in the friendly one any two differ by at least 11 in every kind of vision.
• Keyboard and screen readers. The population tree works from the keyboard (arrows, Home, End) and is announced as a tree with each population's frequency and count; the sample list is one stop with the arrow keys; dialogs keep the focus inside and give it back when they close; a focus ring shows where the keyboard is; scrolling regions can be focused; and every plot has a text description (type, axes, population, events and the gates on it with their frequencies). Icon buttons, menus and status dots have names. Docs: a new Accessibility page.

Changed

• New logo. Three emission spectra (violet, teal and coral) woven into a W, the middle one over its left neighbor and under its right: spectral overlap, the thing compensation untangles, and the weave in the name. It replaces the ring of waves, which read as a face and stayed recognizable only at large sizes. The mark is legible down to a 16-pixel browser tab, and it updates the app header, the start page and the website.
• FlowJo export scales. Logicle and arcsinh scales are written as FlowJo's biexponential, the closest FlowJo scale: FlowJo 11 misplaces gates on logicle and arcsinh channels (a Live gate read 4.6% instead of 94%, on FlowJo 10's own workspaces too) but reads the biexponential correctly. Rectangles, ranges, quadrants and splits stay exact; polygons and ellipses on those channels are traced to follow their outline (within 0.5%) and marked as traced in the export report. CytoML now counts exactly what CytoWeave counts on these gates.
• Contrast. Muted text, status text and the dark theme's primary buttons are slightly darker or lighter so that every text color reaches 4.5:1 on every surface it is used on (WCAG AA): muted gray #7b8496 → #636c7e (light) and #808a9d → #8a94a7 (dark); primary buttons in the dark theme #8d7dff → #6b5ae8; status text a shade darker in the light theme and red status text a shade lighter in the dark theme; heat-map cells in Tables switch to dark or white text where the shading would leave too little contrast; hidden entries in plot legends are struck through in muted gray instead of faded. The theme button opens an Appearance menu (light, dark, match the system, color-vision-friendly colors) instead of switching the theme in one click.

Fixed

• FlowJo workspace export in FlowJo 11. Opened in FlowJo 11.2.0 (build 11.2.0.210156) for the first time, CytoWeave's exports crashed it. Each node's plot is now written in full, as FlowJo writes it; rectangles carry both bounds (FlowJo 11 does not import one open on a side); ranges and splits are written as rectangles with an unbounded second dimension (FlowJo 11 counts one-dimensional gates as empty), and import back as ranges; a sample opens on its first gate's plot.
• A failed save stayed hidden. The red dot of a workspace that could not be saved turned back to "unsaved" at the next edit.
• Roles from file names with underscores. "Beads_2026-03-31", "Comp_FITC" and "Unstained_01" were not recognized as bead, single-stain and unstained files, because the underscore joined the words.
• Off-scale events in the compensation spreading matrix. Clipped events in a single-stain control looked like spread in every detector: on a real LSRFortessa control with a sixth of its positives off scale, one entry read 53 instead of 4. They are now left out, as they already were for the spillover values.
• BD FACSDiscover and FACSymphony spectral detectors. Detector names such as UV1 (375)-A are recognized, so these instruments' raw files open in the Spectral view.

Documentation

• The user guide covers the new features, with new screenshots of panel design, QC as files are acquired, robustness to analysis choices and color-vision-friendly colors, and a new Accessibility page; the FlowJo page describes what was tested in FlowJo 11.2.0 (build 11.2.0.210156). Every screenshot is retaken for 0.4.0, with the new logo.

Validation

• Predicted spread (new spread and fortessa suites):
  • On simulated controls with known photon noise and laser fluctuations, the fitted photon noise is within 1% of the truth (median over 64 detectors). Each control's spread predicted from the other 24 is within 2× of the observed value for 98% of the pairs measured to 4 standard errors. A 15-dye panel predicted with the noise of the 25-dye controls matches its own unmixed controls within 2× for every pair.
  • On the 15 bead controls of a BD LSRFortessa (Zenodo 22808501), each control's spread predicted from the other 14 is within 2× for 79% of the pairs measured to 4 standard errors (median ×1.32; with photon noise alone, 67% and ×1.47). The largest misses are BV711 and BV786 into their donor's channel, which a noise model should not absorb. No public spectral data set with single-stain reference controls was found for the same check on a spectral instrument.
• Folder watching (Go tests): a file stopped mid-write for several checks is not handed over until it is finished, also when the modification time does not change (network shares); hidden and temporary names are ignored until renamed; files already in the folder wait to be asked for; offsets kept in TEXT (large files) are read; only this computer may start or stop a watch.
• Parallel PeacoQC: each channel computed apart and combined removes exactly the events of the serial run, refined and classic, on the 6 simulated QC files and on PeacoQC's own 7 files (qc and bioconductor suites); the benchmark checks the same at 2 million events.
• Robustness to analysis choices (new multiverse and multiverse-ics suites), on comparisons with known answers in the PBMC example:
  • a real effect (CD25+ T cells after stimulation) holds in 64 of 64 analyses;
  • a detector gain in one batch, with a gate drawn close to the negative cells, makes a spurious difference: called fragile, with the adapted gates named as removing it;
  • clogs in one group: QC named as the choice the conclusion depends on, and stricter and looser QC agree;
  • one batch compensated with an under-compe...

CytoWeave 0.3.0

CytoWeave 0.3 works with the rest of the lab: it writes FlowJo workspaces and de-identified FCS files, its figures carry the analysis that made them, it adapts gates to each sample with a confidence for each, and it follows the instrument itself, from detector efficiency to the spectra of its dyes, across experiments.

Added

• FlowJo workspace export. Workspace → Export → FlowJo workspace writes a FlowJo 10 workspace: one gating tree per sample, with its own adjustments and group scopes, its compensation, the scales, the sample groups and, optionally, CytoWeave's population counts and the FCS files in a ZIP. A report lists every population as exact, traced (a gate drawn on another scale than the one written, with enough vertices to follow its outline) or not exported (category gates, gates on channels CytoWeave computed, gates of three or more dimensions).
• De-identified FCS files. Workspace → Export → De-identified FCS files writes the files (a ZIP, or an ACS archive with the workspace) keeping only technical keywords: operator, specimen and patient fields, free-text comments, file names, dates (unless kept), serial numbers and vendor keywords are removed and listed. The events are copied byte for byte. Population exports and the FlowJo export can de-identify too.
• Figures carry their analysis. Exported figures and plots (SVG, PNG and PDF) embed the samples (with their files' SHA-256 checksums), the gates, scales and compensation behind every plot, and each plot's event count. Opening an exported figure in CytoWeave (or cytoweave figure.svg) shows where it came from and, plot by plot, what has changed since; it can rebuild the figure in a new workspace from the same files (found in the library by checksum) or add it back to the open one. "Embed the analysis" in the Figures view turns it off.
• Adapt a gate to each sample. A gate's menu → Adapt to each sample… carries a shared gate from the samples it is known to be right on (where it was drawn, adjusted or confirmed) to every other sample, by registering the density landmarks of its parent population along its axes. Each sample gets a confidence and a status: the gate already fits, a confident adjustment (ticked, applied in one undoable step), or uncertain and listed first for review, with the reason.
  • A gate is moved only where it cuts into a population and the adaptation finds sparser events, since populations also move for biological reasons (a stimulation down-regulates CD3 and CD4).
  • "Keep one gate per" a metadata field (a donor, a subject) adapts each group's samples together, as assays with stimulated and unstimulated wells need; a sample unlike the rest of its group goes to review.
  • "Looks right" teaches CytoWeave a sample; per-event membership probabilities export as CLR files; the methods paragraph describes the adaptation.
  • Agents can adapt gates too (adapt_gate): confident adjustments wait in a proposal, and uncertain samples are listed for the user to check.
• Q, B and Levey–Jennings. QC → Instrument measures every fluorescence detector's efficiency Q, optical background B and the beads' intrinsic CV from multi-level beads or an LED pulser series, with Parks et al.'s weighted quadratic fit as flowQB computes it, with standard errors and a plot of peak variance against mean. Runs are saved to the instrument's record in the library and followed across experiments on Levey–Jennings charts flagged by the Westgard rules. The methods paragraph describes them.
• Spectral library. The Spectral view's Library tab keeps reference spectra across experiments, per instrument, flags a control whose spectrum differs from the library's (a degraded tandem, a new lot), and adds a library spectrum for a fluorochrome without a control. The methods paragraph says which spectra came from the library.
• A new example, Daily bead QC: 30 runs of 8-peak beads with every detector's true Q and B, a PMT that ages, a flow cell that gets dirty and a laser that weakens.
• The library keeps records besides workspaces and files (/api/library/records/{kind}/{id}; in the browser, IndexedDB).
• Scripts can generate examples with options (app.openExample(id, { seed, tandemDegradation, instrumentShift })): a degraded tandem in the spectral example, drifting detector gains in the PBMC example.

Fixed

• FlowJo import. FlowJo writes some characters of parameter names as "_" ("LIVE/DEAD Aqua-A" becomes "LIVE_DEAD Aqua-A"); such channels were not found and every population gated on them was missing. They are now mapped back to the file's names.

Documentation

• The user guide covers the new features, with new screenshots of adapting a gate, Q and B, Levey–Jennings charts, the spectral library, an exported figure opened again and the FlowJo export; every screenshot is retaken for 0.3.0.

Validation

• Against real experts' gates (new experts suite, external data als-ics): in four FlowJo workspaces of a real intracellular cytokine study (48 wells), adapting with one gate per donor leaves agreement with the expert's per-donor gates unchanged (F1 0.9876 → 0.9877) with no adjustment lowering it, and sends wells the expert gated differently to review three times as often as the others. These data changed the design: the first version followed populations that moved for biological reasons.
• Against flowQB (new flowqb suite, external data flowqbdata): on flowQB's own LSR II data (an LED series, 8-peak and 6-peak beads), CytoWeave finds the same peaks and the same Q, B and standard errors in all 36 detectors, within 6e-9.
• Autogating on a simulated cohort with instrument shifts (gains up to fivefold) raises every shifted gate's accuracy against the true cell types (T cells F1 0.954 → 0.994) without lowering any population's, sends the 4 least accurate of 66 gate-sample pairs to review, and sends nothing to review when nothing shifted (autogating suite).
• Q and B of 18 simulated detectors over 30 runs within 2% (Q) and 6% (B) of the truth; every planted instrument problem is flagged on the Levey–Jennings charts at once, and nothing in the baseline runs (new instrument suite).
• The spectral library flags a PE-Cy7 that lost 5% of its emission to PE and nothing else, matches a second experiment's independent controls, and a library spectrum unmixes as accurately as the dye's own control (spectral suite).
• A 60-plot figure is read back intact from SVG, PNG and PDF, rebuilt with every plot drawn from the same events, and a moved gate flags exactly the plots it affects (new figures suite).
• Each FlowJo export is imported back with every count unchanged: the bundled example, ten FlowKit test workspaces and a workspace built in CytoWeave. FlowKit reads every export and counts what CytoWeave counts, and its counts on an export equal those on the original workspace or come closer to FlowJo's saved counts.
• De-identified copies of every example and corpus FCS file hold the same events, bit for bit.
• The suite now has 191 checks in 23 suites; the public test data it downloads grew to about 450 MB.

Upgrading

Run the install command again (see the install guide); it replaces the program and keeps your library.

Known limitations

• FlowJo workspaces written by CytoWeave pass round-trip and FlowKit checks but have not yet been opened in FlowJo itself. Please report any that FlowJo rejects or counts differently.
• Adapting gates is deliberately conservative: a boundary in sparse events stays even when a large shift leaves it off-center.
• The spectral library's threshold for a changed spectrum (0.03) was calibrated on simulated controls; real controls vary more.

CytoWeave 0.2.0

CytoWeave is a free, open-source (Apache 2.0) workbench for flow cytometry analysis: conventional, spectral and mass cytometry. It runs on your own computer as one self-contained program, with no licence server, account, Python or R. Files are analyzed in the browser and never leave your machine.

This release lets AI agents work alongside you through proposals that you review, makes ten-million-event samples fast, and checks CytoWeave against the reference tools on public data. It also comes with a website and user guide: https://robert-mcdermott.github.io/cytoweave/

Highlights

• Proposals from AI agents. With cytoweave mcp, an agent such as Claude Code can gate, compute statistics and write the methods in the window you are watching. Its gates appear at once, marked as proposed, with real counts; its renames, deletions and compensation matrices wait. You review the proposal and accept or reject it as a whole, and the change log records which agent proposed what and what you decided. New agent tools: propose_compensation and proposals.

• Large samples. Samples of ten million events open in seconds and stay responsive:

  • files are read in parts and never held whole;
  • populations are kept as bitsets (20× less memory);
  • channels are compensated only when first used;
  • background analyses share the events instead of copying them.

  Moving the top gate of a ten-million-event sample re-evaluates every population in about 0.4 s, down from 1.6 s, and QC of such a sample now runs; before, it could not start.

• Boolean populations: the events in all of, any of or none of chosen populations, with a live count.

• Index-sort plate view. An index-sorted sample shows its plate below the plots, with each well coloured by its cell's population. Click a well to mark its cell on every plot, and export the wells as CSV.

• Explore adds Louvain and k-means clustering, and places samples left out of a UMAP on the finished map.

• Validated against reference tools and public data:

  • ISAC's Gating-ML 2.0 compliance suite: all 190 gates match on every event;
  • FlowKit and FlowIO, on FCS files from several instruments, including malformed ones;
  • FlowJo's saved counts in 14 workspaces: at least as close as FlowKit;
  • flowCore, PeacoQC, FlowSOM and CytoNorm, run in R: agreement to 1e-7–1e-5, and classic PeacoQC removes the same events;
  • BD FACSDiva's spillover matrix from 15 real single-stain controls: every entry within 0.015.

Fixed

• FlowJo import:
  • time gates were read in the wrong units;
  • linear axis gains were ignored;
  • ellipses were read in data rather than display units;
  • saturated events now fall inside gates drawn to the edge of the scale.
• Gating-ML import:
  • transformation bounds were ignored;
  • gates of three or more dimensions were skipped;
  • ratio dimensions were never computed;
  • polygon edges now count as inside.
• Gate boundaries are decided in double precision, so events within rounding distance of a boundary fall on the same side as in reference tools.
• Spillover from controls leaves saturated events out of the positives; on a real 15-colour panel, the matrix is now within 0.015 of FACSDiva's.
• Logicle width estimates follow flowCore's estimateLogicle.
• PeacoQC classic is now an exact port of PeacoQC 1.22.
• Guava Muse log channels are read correctly.

The changelog lists every change.

Upgrading

Run the installer again. Your workspace library is not touched.

CytoNorm now follows CytoNorm 2.x. It uses 99 quantiles from 1/100 to 99/100 by default, and leaves unchanged a batch with 50 or fewer cells in a cluster. Normalizations rerun in 0.2.0 therefore differ slightly from 0.1.0.

Install

macOS and Linux

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/robert-mcdermott/cytoweave/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/robert-mcdermott/cytoweave/main/install.ps1 | iex

The installers check the download against SHA256SUMS and verify its version before installing. They need no administrator rights. Then run cytoweave: it opens in its own window.

To download a file by hand instead:

Computer	File
Mac with Apple silicon (M1 or later)	cytoweave-darwin-arm64
Mac with Intel	cytoweave-darwin-amd64
Linux, x64 / ARM64	cytoweave-linux-amd64 / cytoweave-linux-arm64
Windows, x64 / ARM64	cytoweave-windows-amd64.exe / cytoweave-windows-arm64.exe

The binaries are not code-signed, so a file downloaded with a browser triggers a macOS Gatekeeper or Windows SmartScreen warning; the installers avoid this. See Installing CytoWeave for manual installation, checksums, upgrading and uninstalling.

Try it

Open Workspace → Example experiments and pick one of nine simulated experiments, each with the true identity of every event. To try the agent workflow with Claude Code:

claude mcp add cytoweave -- ~/.local/bin/cytoweave mcp

Then ask it to open the PBMC example and gate the T cells, and review its proposal. The user guide walks through every view.

CytoWeave is research software, not a medical device.

CytoWeave 0.1.0

CytoWeave is a free, open-source (Apache 2.0) workbench for flow cytometry analysis: conventional, spectral and mass cytometry. It runs on your own computer as one self-contained program, with no licence server, account, Python or R. Files are analyzed in the browser and never leave your machine.

This is the first release.

Install

macOS and Linux

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/robert-mcdermott/cytoweave/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/robert-mcdermott/cytoweave/main/install.ps1 | iex

The installers check the download against SHA256SUMS and verify its version before installing. They need no administrator rights. Then run cytoweave: it opens in its own window.

To download a file by hand instead:

Computer	File
Mac with Apple silicon (M1 or later)	cytoweave-darwin-arm64
Mac with Intel	cytoweave-darwin-amd64
Linux, x64 / ARM64	cytoweave-linux-amd64 / cytoweave-linux-arm64
Windows, x64 / ARM64	cytoweave-windows-amd64.exe / cytoweave-windows-arm64.exe

The binaries are not code-signed, so a file downloaded with a browser triggers a macOS Gatekeeper or Windows SmartScreen warning; the installers avoid this. See Installing CytoWeave for manual installation, checksums, upgrading and uninstalling.

Try it

Open Workspace → Example experiments and pick one of nine simulated experiments. Each is generated in the app with the true identity of every event, so you can check your results against the truth:

• PBMC immunophenotyping with a deliberate compensation error to find;
• a FlowJo workspace to migrate;
• a 25-colour spectral panel;
• cell cycle and proliferation;
• a two-batch mass cytometry cohort and a barcoded plate;
• an index sort and a QC plate.

Highlights

• Gating with shared gates and per-sample adjustments, a magic wand, backgating, and review of any gate across all samples, with how sensitive each result is to where the gate was drawn.
• Compensation computed from single-stain controls, and a check of any matrix against its controls that finds a wrong value and suggests the correction.
• Spectral unmixing with several autofluorescence signatures or per-event autofluorescence, panel quality metrics, and a side-by-side comparison of unmixing models on your own sample.
• Acquisition QC (PeacoQC with refinements that leave clean files alone, flow rate, margins, drift), CytoNorm batch normalization, bead normalization, and debarcoding with a split into one sample per barcode.
• Clustering and maps (FlowSOM, Leiden, UMAP, t-SNE, PCA) that report how faithful each map is.
• Statistics: batch tables, and group comparisons that choose the test from the design, with effect sizes, confidence intervals and multiple-testing correction.
• Cell cycle and proliferation models.
• Figures as SVG, PNG and PDF; a methods paragraph with references written from your analysis; a MIFlowCyt checklist; and checkpoints that show what changed between two versions of an analysis.
• Moving from FlowJo: imports FlowJo 10 workspaces, reports how faithfully each population converts, and compares every population count with FlowJo's. FlowJo's biexponential scale is reproduced exactly.
• Standards: FCS 2.0–3.2, Gating-ML 2.0 in and out, CLR and ACS.
• AI agents: cytoweave mcp lets agents such as Claude Code work in the window you are watching; every change can be undone. See Using CytoWeave with AI agents.
• Validated: the analyses are checked against known answers and against R on every change (validation).

Known limitations

• Validation so far uses simulated data with known answers and published reference values. Comparisons with reference tools on public datasets are planned.
• Developed and tested on macOS in Chrome, Edge and Brave. Linux and Windows builds are provided but have had less testing.
• FlowJo 9 workspaces and FlowJo 11's .flowjo format are not read; export a .wsp file from FlowJo 10 or 11.
• Spectral unmixing needs the raw detector channels.
• Imaging flow cytometry is not supported.

More detail is in the README.

CytoWeave is research software. It is not a medical device and must not be used for diagnosis.

Feedback

Please report problems and ideas in Issues. Problems reading an FCS file are especially useful, along with the instrument and software that wrote it.

The full list of changes is in CHANGELOG.md.