Figures, methods and certificates

Leave with what a paper needs: figures that stay true to the analysis until you export them, a methods paragraph written from what you actually did, a record of every change, and a certificate that lets anyone confirm every number.

Publication figures

The Figures view: a page holding the gating strategy of T cells, five plots from all events to T cells joined by arrows, with the page properties and buttons to add text, plots and arrows — The gating strategy of T cells, built in one click.

The Figures view lays out pages of plots. Build one of three ways:

Gating strategy of the selected population: one plot per step of its gating path, joined by arrows. Select the population in the Gate view first.
The current plots across samples: the selected population's plots from the Gate view, one row per sample (the samples of the group shown in the sample list, up to 24).
Blank page: add Text, a Plot of the current population, Arrows and Statistics yourself.

A Statistics item shows columns of a Tables table: for the samples whose plots are on the page, or for all of the table's rows (as it does on a page without plots). Choose the table, its columns and the text size in the item's properties. Values are those Tables computes, with ND and < LLOQ where a column has detection limits; the text shrinks to fit the box, and rows that still do not fit are counted below the table.

Text can hold placeholders, filled from the figure's samples and, in a batch report, on every page: {sample}, {page}, {pages}, {group}, {date}, {workspace}, and any annotation, such as {subject} or {condition}.

Any plot's ⋯ menu in the Gate view also has Add to figure. Click an item to edit it, drag it to move it (it snaps to 5 px), drag its corner to resize it, and press Delete to remove it. Pages come in slide (16:9), Letter and A4 portrait, Letter landscape and square sizes, or any width and height.

Plots in a figure stay live: they follow gate edits and compensation changes until you export. Export the page as SVG (to edit in Illustrator or Inkscape), PNG or PDF. PDFs are vector: text, axes, gates and labels are PDF text and lines, sharp at any zoom and searchable, and only the events are images. They use Helvetica, which every PDF reader has; a character outside its character set is written as its nearest ASCII (− as -, ≥ as >=).

Batch reports

The batch report dialog over the Figures view: the T-cell gating strategy repeated for each subject, from the samples (not controls), as a PDF, with its six pages listed, subject D01 to D06 — The T-cell gating strategy repeated for each subject: the pages are listed before anything is written.

A batch report repeats a figure page after page, the layout FlowJo users know from batch processing in the layout editor. Click Batch report… at the top of the Figures view and choose:

Repeat for each sample. The plots of the figure's main sample (the one most of its plots are on, or the one you choose) are redrawn on each sample in turn. Plots of other samples stay on every page, so an FMO or an unstained control can sit beside each sample.
Repeat for each value of an annotation, such as each subject or timepoint. A plot of a sample with that annotation is redrawn on the page's sample that matches it on the annotations that tell the figure's samples apart. Lay out subject 1's unstimulated and stimulated tubes, and each page shows that subject's unstimulated and stimulated tubes. When several samples could take a plot's place, the one sharing most of its annotations is drawn.
From the experiment's samples (not controls) or a group's.
PDF or PowerPoint. In PowerPoint, plots are pictures and statistics items are native tables, editable in PowerPoint, Keynote and LibreOffice.

The dialog lists the pages before anything is written, with a note for each gap: a subject without a stimulated tube (its plot is left empty, saying why), or two samples the annotations do not tell apart (the first is drawn; annotate what differs to choose). The choices are kept with the figure and travel with it in templates.

Every number a report prints is recorded with where it comes from: each statistics cell with its table and column, each gate label on a plot with its gate. The record goes into the file (a PDF attachment named cytoweave-report.json, or a part of the PowerPoint package) beside the analysis behind the plots. The validation suite recomputes every recorded number and reads the files back with openpyxl, python-pptx, pypdf and R's pzfx (see Science).

Figures that carry their analysis

A figure in a paper or a slide is usually cut off from the analysis that made it. CytoWeave's exports are not: every figure and plot exported as SVG, PNG or PDF carries a record of what it shows.

The samples, by name and by the SHA-256 checksum of each FCS file.
Every gate the plots depend on: each population's ancestors, the gates drawn on the plot and Boolean operands, with their per-sample adjustments.
The scales of the channels and the compensation each sample was drawn with.
Each plot's population, axes and event count, and the page layout.

The record goes in the SVG's metadata, a PNG text chunk, or a PDF attachment named cytoweave-provenance.json, which PDF readers list among the document's attachments; batch reports carry it for every page's plots. It holds no keywords and no event data. Untick Embed the analysis at the top of the Figures view to leave it out.

Opening an exported figure

An exported T-cell gating strategy opened again: exported by CytoWeave from this workspace, four of its five plots unchanged and the lymphocyte plot changed because the T cells gate moved, with buttons to add it to this workspace or rebuild it in a new one — A figure opened after a gate moved: the one plot it affects is marked.

Drop an exported SVG, PNG or PDF on CytoWeave (or open it like any file). The dialog says when and by which CytoWeave it was exported, from which workspace, and, plot by plot, whether it would look the same today: "Live changed; 84,450 events now, 84,284 in the figure", "the scale of APC-A changed (logicle → arcsinh)", "the compensation matrix changed". In another workspace, plots are matched by file checksum and population path. Then:

Rebuild in a new workspace recreates the samples, gates, scales, matrices and the figure itself, exactly as they were, from the same files. The library finds them by checksum; files it does not have can be added, whatever their names now.
Add to this workspace places the figure back in the open workspace, on its matching samples and populations.

The validation suite exports a 60-plot figure of 12 samples, reads its record back intact from all three formats, rebuilds it with every plot drawn from the same events, and checks that moving one gate flags exactly the plots it affects.

The methods paragraph

The Report view: a methods paragraph written from the PBMC workspace, describing the instrument, compensation, scales, gating hierarchy and analyses, with numbered references — A methods paragraph written from the workspace, with numbered references.

The Report view writes the methods from what the workspace contains, not from a template:

the instrument and files, from the files' keywords;
the compensation, and where it came from;
the scales of the channels;
the gating hierarchy;
every recorded analysis with its parameters and seed: QC, unmixing, normalization, clustering, embeddings, model fits;
the statistical comparisons you saved for the report.

References are numbered, with DOIs. Copy the paragraph, or download it as Markdown and the references as BibTeX. Edit it to taste before publishing. Gates proposed by an AI agent and accepted by you are described as such.

MIFlowCyt

The MIFlowCyt checklist (Lee et al. 2008) shows which items of the minimum information for a flow experiment the workspace documents and which are missing. CytoWeave fills what the files and the analysis record. The rest (the purpose of the experiment, specimen details, reagent clones and lots, instrument settings not in the files) belongs in the Workspace notes below it, which are saved with the workspace.

Checkpoints

A checkpoint keeps the gates, compensation and scales as they are, to compare with or return to later. Create one before you change an analysis, for example before adjusting gates for a revision:

In Report → Checkpoints, click Create checkpoint and name it.
Change the analysis.
Select the checkpoint. CytoWeave lists what changed in words, such as "the Live gate moved by 3% of the axis" or "the compensation of 12 samples changed", and the effect on every population's frequency in the loaded samples.
Restore returns to the checkpoint; the current analysis stays available through undo.

Review reports

A review report opened in a browser: every sample's gates drawn on its own events with each gate's percentage of its parent, and a clicked percentage traced to the counts behind it, the sample, its file's SHA-256, the compensation and the gates above it — A review report: every sample's gates, and where a number comes from.

A review report is the analysis as one HTML file, for a PI, a collaborator or a reviewer who does not have CytoWeave. It opens in any browser and holds:

the samples, with their files' SHA-256 checksums, annotations and compensation;
the gating hierarchy, the scales, and every population's event count in every sample;
every sample's gates, each drawn on its parent population's events, with each gate's % of parent;
the workspace's figures and tables, and the comparisons saved for the report, with their tests, effect sizes and every sample's value;
the methods with their references, MIFlowCyt, and the change log with the state of its chain.

Every underlined number is traced: click it to see where it comes from: its exact value, the counts behind a percentage ("100 × 89,654 / 93,452 events"), the sample and its file's checksum, the compensation, and each gate above the population. The numbers are computed from the FCS files as the report is made, with the code certificates use, so a report and a certificate of the same analysis print the same numbers.

To make one, go to Report → Review report (or Workspace → Export → Review report) and click Make a review report. Untick Draw every sample's gates for a smaller file, or tick Draw the controls' gates too. The file loads nothing from the network: its styles, plots and images are inside it, so it opens offline, in an email attachment or on a journal's review site. Runs write one with cytoweave run --review, and agents with export_review_report.

Reproducibility certificates

A certificate lets anyone confirm the numbers of an analysis, years later, from its files. It packs the analysis with everything needed to compute them again and records every number it reported; verifying computes each one again and compares.

In Report → Certificate, leave Include the FCS files ticked. Untick it when the data cannot be shared: the certificate then names each file by its SHA-256 checksum, and whoever verifies it supplies the files.
Click Make a certificate. CytoWeave computes every number from the files and downloads <analysis>.certificate.acs.
Quote its fingerprint with the analysis, for example in the methods or the data availability statement, and deposit the file with the paper, for example on Zenodo. The fingerprint is the SHA-256 of what was certified: any change to the certificate changes it.

The certificate is an ISAC Archival Cytometry Standard (ACS) archive, a ZIP file whose table of contents lists every file with its SHA-256. It holds:

the workspace, the gates as Gating-ML 2.0, and the methods paragraph;
the FCS files, and the channels the analysis stored, such as clusters, embeddings and unmixed channels;
certificate.json: the CytoWeave version and the browser that computed the numbers, each file's checksum, the analyses with their parameters and seeds, the head of the change log's chain, the MIFlowCyt items with what the workspace records for each, and every number reported: each population's count in each sample, each cell of each table with its detection-limit status, and each saved comparison (every sample's value, the test, the group summaries, effect sizes and post-hoc tests);
a README saying how to verify it.

Clustering, embeddings and other analyses whose results are stored as channels are not run again: the channels are checked by their checksums, and every number computed from them is checked. Screens of many populations, clusters or marker states are recorded but not yet computed again. The certificate lists what it does not compute again. When a comparison you saved no longer matches the analysis, because a gate moved after you saved it, making the certificate says so: save the comparison again in Compare. Each certificate made is recorded in the change log with its fingerprint.

Verifying a certificate

A certificate verified: confirmed, all numbers of the PBMC analysis computed again from the 27 files and identical, with what was checked: certificate.json unchanged, the workspace unchanged, 27 of 27 files matching their SHA-256, the change log's chain intact, and the MIFlowCyt items — A certificate verified: every number computed again from its files.

Open the certificate in CytoWeave, by dropping it on the window or with Workspace → Import, or click Verify a certificate… in Report → Certificate. CytoWeave checks every file's checksum, the workspace, the change log's chain and the fingerprint, computes every number again from the files, and compares. The result is one of:

Confirmed: every number computed again agrees with the certified one.
Incomplete: files are missing, as in a certificate made without its data. Click Supply the FCS files…: they are recognized by their checksums, whatever their names now.
Not confirmed: what differs is named, such as a file whose checksum changed, an edited certificate.json, a change log altered at a given entry, or numbers that differ, each with the certified value and the value now.

Verifying does not change the open workspace. Open the analysis opens the certified analysis with its files, and Report (JSON) saves the result. Scripts and pipelines verify with cytoweave verify, and AI agents with verify_certificate.

Identical, or equal to 12 digits

Verified in the same browser version, every number is identical, bit for bit. Numbers computed with logarithms, exponentials or probability distributions, such as confidence intervals, can differ in their last digit in another browser version or in Node.js, whose versions compute these functions slightly differently. Such numbers are confirmed when they agree to 12 significant digits, and the result says how many there were and which browsers computed them. In the validation suite, counts, frequencies and test statistics were identical across Node.js and Chrome; two confidence limits differed in the 16th digit.

The change log

Every change to the analysis is recorded, newest first, and saved with the workspace: who made it (you, or which agent proposed it and what you decided), when, and what changed. Download it as JSON for an audit trail.

The log is hash-chained: each entry carries a SHA-256 that covers the entry before it, so an entry changed, removed or reordered afterward is detected. Report → Change log shows whether the chain is intact, and certificates record its head and check it. Workspaces saved by CytoWeave 0.7 and earlier are chained when next changed, and the log says how many earlier entries were chained then. Undoing a change removes its entry, as the log records how the current analysis was made.