Lab

The Lab is the flowss studio for research figures whose numbers have to add up. You write a short, typed text document in FlowScript (the Lab's own language), and the Lab draws it as a figure: a CONSORT flow, a Kaplan–Meier curve, a forest plot, a Table 1, a Gantt chart, a cap table and dozens more. Because the document is typed, the Lab can check it while you type. A cohort that loses more people than its exclusions account for, two arms that do not sum to the number randomised, a rate that does not match its counts, a p-value that does not match its test, a reference to a block that does not exist: each one is underlined in the source and counted on the status badge before the figure reaches a manuscript. One document can carry several views of the same model, so a forest plot and a funnel plot can never be drawn from two different copies of the numbers. This page is a tour of the whole studio: the screen, documents, the source editor, the canvas, every menu and pane, AI help, sharing, exporting, shortcuts, limits and the messages you may see. The language itself is documented in The FlowScript language.

At a glance

On Windows and Linux, read ⌘ as Ctrl, ⌥ as Alt and ⇧ as Shift.

What the Lab is for

Most diagram tools draw what you tell them to draw. The Lab also checks that what you have told it is consistent, and shows you every place where it is not, while it draws. Four ideas make that possible.

• Typed blocks. Every block has a kind, and each kind knows which attributes it takes. A cohort has an n, a from and excluded counts; an estimate has a measure, a value with its interval, and a scale. The Lab knows 125 block kinds across 22 fields, from clinical trials and evidence synthesis to project management, finance, security, reliability, supply chains, education and law. You can also invent your own kinds; the Lab treats them as plain data.
• Numbers that reconcile. Counts flow from block to block (from:), and the Lab checks the arithmetic: screened minus exclusions equals eligible, the arms sum to the randomised cohort, events divided by participants equals the stated rate. You can also derive a number instead of typing it (n: = randomised.n - excluded.withdrew), so it cannot go stale.
• Units and uncertainty. A number can carry a unit (5 mg/kg/day, 14 months, 3.2 per 100000) and an interval (0.68 [0.51, 0.90]). The Lab refuses to add milligrams to millilitres, keeps a risk ratio's interval on the log scale, and flags an interval that does not contain its own point estimate.
• Many views, one model. A view line names a renderer and the blocks it draws. Every view of a document is drawn from the same model, so every figure agrees with every other.

The Lab is also where the platform's reporting-standards checks live (CONSORT, PRISMA, STROBE, TRIPOD, GRADE and 28 more), along with provenance tracking and journal-ready publishing. Those are covered on their own pages: Reporting standards, Lab views and renderers, The Data and Statistics benches and Publishing, provenance and compliance in Lab.

Opening the Lab

1. Sign in. The Lab asks every visitor to sign in first; if you follow a Lab link while signed out, you come back to the same link afterwards.
2. Go to /lab, or pick Lab in the studio switcher.
3. The Lab opens the document you last had open. On your very first visit it opens the Clinical — RCT / CONSORT 2010 starter so you have something to explore.

If your plan does not include the Lab, you land on the pricing page instead, with a note at the top saying the Lab is part of Starter.

Links that open something specific

The Lab removes these parameters from the address once it has acted on them, so reloading the page does not load the template again.

A tour of the screen

The Lab uses the same island layout as the other studios: the figure fills the page and every control floats over it in one of five places.

Everything else appears when you need it: the workbench sheet slides out beside the rail when you open a shelf, a small toolbar floats over a selected block, the Block properties drawer opens on the right when you ask for it, and one side pane at a time can open on the right.

The tool rail

A shelf button toggles: clicking the shelf that is already open closes the workbench sheet.

The workbench sheet

The sheet holds the source editor and the four benches, with a tab strip across the top (Source, Data, Statistics, Figures, Standards). Use the arrow keys, Home and End to move between the tabs.

• Drag the sheet's edge to resize it, between 360 and 720 pixels wide. Double-click the edge to reset it. With the edge focused, ← and → resize it in small steps (hold Shift for bigger ones), and Home and End jump to the narrowest and widest. The sheet always leaves room for the figure beside it, and the Lab remembers the width in this browser.
• When the sheet is narrower than 560 pixels, the tabs that are not open fold to icons (their names stay in the tooltips).
• Close workbench (⌘\) puts it away. On a phone the sheet closes any open side pane, because the screen has room for one.
• On the Source tab a wide sheet's header shows the line count ("56 lines"); on a narrow one the count is in the status popover instead.

The Lab remembers, per browser, which shelf and bench you had open and which side pane was open, and puts them back next time.

The view controls

On a phone the view controls show undo and redo only; zoom and the view list move into the ⋮ menu under Zoom.

Documents

Every Lab document is a named figure in your library, alongside the work from the other studios. You can keep as many as you like on Starter and above.

The document list

Click the title at the top left to open the list of your Lab documents. The open one is checked.

How a document is named

Until you rename a document yourself, the Lab names it from its content and keeps the name in step as you edit: the first title: in the document, otherwise its leading comment, otherwise its first block, otherwise "Untitled figure". As soon as you rename it, the Lab never renames it again. Names are kept to one line of at most 80 characters; a longer name is shortened with "…".

Saving

The Lab saves the open document about 0.6 seconds after you stop typing, and again when you leave the page. While a save is pending the status badge shows a small spinner; once written it shows as saved. If a save fails, the badge turns red ("Not saved"), the popover's Save section shows the reason, and Retry the save tries again. The commonest reason is "Local storage is full — the document could not be saved." (see Troubleshooting).

Documents follow you to other devices through cloud sync; see Cloud sync, offline work and devices.

Revision history

The Lab keeps up to 50 snapshots of each document. Open them from the ⋮ menu (Revision history) or ⌘K. What changed on a snapshot lists the change as blocks (for example arm arm_b: n 240 → 235), or "No block changed — formatting or comments only." Restore asks "Replace the editor’s source with this snapshot?" with Restore and Cancel, and restoring goes through undo: the message "Snapshot restored" has an Undo button, and ⌘Z brings your current source back. Clear revision history (the button in the pane's header) asks "Delete all N saved snapshots for this document? This can’t be undone."; Delete history empties the history for this document only ("Revision history cleared for this document"), and Cancel keeps it. There is deliberately no keyboard shortcut for the timeline, because every sensible chord is taken by the browser. See Version history and undo.

Writing FlowScript in the Source editor

Open the Source shelf (⌘\) to edit the document as text. The editor is the same one used by code editors, set up for FlowScript.

The editor keeps its own undo, find and other commands while your cursor is in it. The Lab compiles the document on every keystroke; the canvas redraws once you pause.

Tip: You never have to type a whole block. Insert a block or view writes a block with its required attributes filled with placeholders, and the Block properties drawer adds any attribute the kind accepts with one click.

The canvas

The canvas draws the current view.

The figure re-fits itself when you switch view. The canvas follows the app's light or dark theme.

The block toolbar

When a block is selected, a toolbar floats above it with Edit source (jumps to the block's first line), Insert a block, Duplicate (⌘D), Delete (Del) and Block properties (⌘.). The toolbar steps out of the way while you pan or drag.

Deleting a block shows "Deleted cohort 'eligible'" (for example) with an Undo button. Duplicating gives the copy a fresh id and selects it. Renaming from the block menu updates every reference and tells you how many it changed: "Renamed to 'arm_c' — 3 references updated".

Block properties

Block properties (⌘., the toolbar button, or ⌘K) opens a drawer on the right titled with the block's kind and id, for example "Trial arm · arm_b". It edits the selected block as a form.

• Each attribute that can be safely edited in place (text, numbers, words) is a field. Your change is written into the source when you leave the field.
• Values that cannot be edited safely in a form are shown read-only with their real text and the reason: objects, lists, true/false, null, intervals ("interval — edit in source") and derived values ("derived — edit in source").
• Available attributes lists every attribute the kind accepts. Ones already present are shown filled; missing ones are buttons (+ key) that add the attribute with a placeholder. A * marks a required attribute.
• If the block has no { } body (a one-line view declaration, for example), the buttons are disabled and the drawer says why and how to rewrite the block so they work.
• When an edit cannot be made safely, an amber notice in the drawer says so, and the source is left unchanged.

The drawer can be pinned open and resized. With nothing selected it says "Select a block to edit its properties."

Adding blocks and views

The Insert flyout

Click Insert a block or view on the rail, Insert a block on the block toolbar, or ⌘K Insert block…. The flyout lists every block kind under its field (the fields your document already uses come first), then Add view with every renderer. Type in Search blocks & views… to filter.

• Clicking a block kind appends it to the end of the document with a unique id (the kind's name, then cohort2, cohort3 and so on), fills its required attributes and its title or label with placeholders, selects it, and says "Inserted cohort 'cohort2'".
• A reference placeholder points at the newest block whose kind matches the attribute (an inserted eval points its model: at your latest model); a from: points at the newest block of the same kind. Where there is no candidate the reference is left out, and the missing-attribute check tells you to add it. Other text placeholders read "TODO", numbers 100 and percentages 50.
• An inserted check comes with a real condition to edit, never that: true.
• Clicking a renderer under Add view appends view <id>: <renderer> with a unique id, switches the canvas to it, and says "Added view '…'".

Templates

Open Browse templates… from the ⋮ menu or ⌘K. The flyout lists the Lab's 60 starters, each with its field and a one-line description; type in Search templates — CONSORT, roadmap, FMEA… to filter, and the starter you last loaded is ticked.

Loading a template replaces the open document's content. The message "Template loaded — …" has an Undo button, and ⌘Z works too. If rows were bound on the Data bench, they are released, because they described the study that was there before; the Data bench says so. For a full catalogue across all studios, see The template gallery.

Example data

Some starters use values from a fictional study: the research-figure templates and every reporting-standard starter open with a notice that begins "EXAMPLE text from a fictional…". While that notice is in the source:

• an amber banner at the bottom of the canvas reads "Example data — not real. This starter uses values from a fictional study — replace them with yours, then delete its “EXAMPLE text” notice to remove this mark from the figure and its exports." Got it folds it to a small Example data chip; click the chip to read it again;
• the figure, every export and the submission bundle are stamped Example data — not real.

Delete the notice once the numbers are yours and the stamp goes with it.

Views and figures

A view is one figure drawn from the document, declared with one line such as view flow: consort(trial). One document can declare as many as you like.

The Lab remembers, per document, which view you were looking at and which block was selected. Full details of every renderer, its arguments and its messages are on Lab views and renderers.

When nothing is drawn

Checking: the status badge

The badge beside the title answers two questions at once: is this document saved, and is anything wrong with it. It counts errors, warnings and notes. Click it for the popover.

The save line in the popover also shows the line and block counts ("42 lines · 9 blocks"), or "The last save failed". When the document binds to data the Lab has not been given, the column checks cannot run; the badge counts that as a warning and the Validation section says which checks did not run, so a figure nobody checked never wears a clean tick.

What exactly is checked, and every message, is documented in The FlowScript language.

The side panes

The right side holds one pane at a time; opening one closes whichever was there. Each pane has its own header and close button.

The Lab remembers which pane was open and reopens it next time.

AI in the Lab

AI is optional. Writing, checking, every bench, every view, the Advisor, Provenance, Reporting standards and Publish all work without it. AI features use your plan's AI points (Plus and above) or your own key (Starter and above); see AI points and limits and Bring your own AI key.

The prompt

The prompt at the bottom of the canvas has two modes.

Suggestion chips appear when the document is empty or the prompt has focus: "Add a second arm with placebo intervention", "Convert the cohort into a CONSORT view" and "Add a power calculation block". With a block selected, the chips are that block's refines instead: Add more detail, Rewrite labels and Sanity-check.

When neither the platform's AI nor a key of your own is available, the prompt says "AI is off — set up key" and links to the setup guide instead of taking a request.

Reviewing an AI change

Nothing the flowss Lab Agent (Quick or multi-step) or auto-fix produces lands in your document unseen. Each result waits in a review bar above the prompt.

• The bar names the source of the change ("flowss Lab Agent", "AI auto-fix", "flowss Lab Agent — Lab methodologist") and leads with what changed as blocks, for example arm arm_b: n 240 → 235. If no block changed it says "No block changed — formatting or comments only."
• Show text diff shows the line-by-line diff, with unchanged runs collapsed.
• Accept applies it (for example "flowss Lab Agent applied", with Undo). Reject, or Escape, discards it ("AI change discarded").
• An AI result is pinned to the document it was asked about. If you have switched documents since, Accept refuses and tells you which document it belongs to; the result is kept so you can switch back and accept it there.

AI auto-fix

When the document has errors, AI auto-fix in the status popover (or ⌘K AI auto-fix validation errors) sends the errors to the flowss Lab Agent and returns a minimal repair for review. After one attempt the button is disabled, with the tooltip "Already tried — edit the source and try again", until you change the source.

Photo → FlowScript

Photo → FlowScript… in the ⋮ menu's Import (or ⌘K) turns a photo of a real-world artefact (a whiteboard flow, a printed diagram) into source. Take a picture with your camera or upload a PNG, JPEG, WebP or GIF (HEIC photos from an iPhone, and some AVIF and TIFF files, cannot be decoded by most browsers; convert them to PNG or JPEG first), then recognise it. A FlowScript result can be loaded straight into the open document ("Recognised FlowScript loaded", with Undo); unlike a change from the flowss Lab Agent, it does not wait in the review bar, so check it against the photo. See Importing and converting for how photo recognition works across the studios.

The ⋮ menu

The ⋮ beside the title holds the document's verbs. Every row except the Send to targets and Language: FlowScript is also a ⌘K command.

Send to another studio

A studio that renders FlowScript receives it as it is. Evidence extracts it into an evidence scaffold. A studio that needs a different engine converts it first; the message "Converted to … " has an Open button, so a conversion never navigates you away from your work before you have seen it. An empty document cannot be sent ("There is nothing to send yet — write or insert a block first"). See Moving work between studios.

Exporting

PNGs are drawn on white in the light theme and on the dark canvas colour in the dark theme. All exports are stamped Example data — not real while a fictional starter's notice is in the source. See Exporting your work for how these compare with the other studios.

Sharing and working together

Share at the top right opens the share menu.

A share link has a size limit of about 8 KB, because the document travels inside the address. A larger document says "This document is too large for a share link (… KB — the limit is about 8 KB). Export it instead."

Live sessions

In a live session one person at a time holds the pen and edits while everyone else watches; their changes reach the others after a short pause in typing. A banner over the canvas says who has the pen. Take or request the pen in ⌘K asks for it. A session belongs to one document: if you switch to another document in the same tab, a banner says "The live session is on … — this document is not being shared, and live edits are not landing here." with Back to the session. Plus allows live sessions for up to three people; Ultra and Enterprise have no seat limit and add voice and screen sharing. See Live collaboration.

Comments

Comments in the Lab are threads anchored to a line of the source. Open Comments at the top right, click into the source to pick a line (the composer shows "line N"), and write. Click a thread's line to jump to it. Threads are kept in this browser, next to each document, stay out of the FlowScript source, and sync to everyone during a live session. Because the anchor is a line number, editing above a comment moves the text under it without moving the comment. See Comments and review.

The command palette

⌘K reaches every Lab command and every screen. Under Go to you will find Source, Data, Statistics, Figures, Standards, Block properties, flowss Lab Agent (puts the caret in the prompt), flowss Lab Agent — Lab methodologist, Advisor, Comments, Revision history, Reporting standards, Provenance, Publish, and one entry per view. The Lab's own commands are:

Keyboard shortcuts

The shortcut sheet (?) is generated from the keys the Lab actually binds, so it always matches. See Keyboard shortcuts for every studio.

Tips

• Derive, do not retype. Write n: = randomised.n - excluded.withdrew or rate: = events / n * 100 instead of a number you calculated by hand. A derived number cannot go stale when the counts change in revision three.
• Write source "…" beside numbers you copied (n: 1502 source "Screening log, May 2024"). The Provenance pane and the submission bundle then say where each number came from.
• State your own rules with check. A cap table that must total 100, an FMEA whose RPN must be S×O×D: one check block turns the rule into an error or warning on the badge.
• Let the badge be your to-do list. Click an issue to jump to its line; fix errors before warnings.
• Use one document, many views. Add a forest and a funnel_plot view to the same meta rather than two documents.
• Check the example stamp before you submit. If you started from a fictional starter, delete its "EXAMPLE text" notice once the values are yours.
• Rename with F2, not find-and-replace. It changes every reference and nothing inside strings or comments.

Limits and known constraints

• The Lab is part of Starter and above. Live sessions need Plus; voice and screen sharing need Ultra or Enterprise.
• Documents, comment threads and revision snapshots are stored in your browser first. Browser storage is finite, and a full store stops saves (see Troubleshooting). Comment threads stay in the browser they were written in.
• Revision history keeps up to 50 snapshots per document.
• Share links carry the whole document and stop at about 8 KB.
• Document names are at most 80 characters.
• Comment anchors are line numbers, not tracked ranges.
• Only one side pane is open at a time.
• The print-size PNG needs a view that declares a drawn size; otherwise you see "This view does not declare a drawn size, so it cannot be exported at a print width".
• Rows bound on the Data bench are kept in this browser, up to 400,000 characters per document; larger rows are kept for the session only. See The Data and Statistics benches.
• The flowss Lab Agent (Quick and multi-step), auto-fix and photo import need AI; nothing else does.

Troubleshooting

For every compiler message, see The FlowScript language. For general problems, see Troubleshooting and FAQ.

Related pages

• The FlowScript language
• Lab views and renderers
• Reporting standards
• The Data and Statistics benches
• Publishing, provenance and compliance in Lab
• Figure, for dataset-first journal figures
• Evidence, for evidence graphs from real papers
• Live collaboration and Comments and review
• AI in flowss
• Plans and what they include
• Keyboard shortcuts