Read a studyflow

Learn the notation by reading a real diagram

This page walks you through a complete (but small) studyflow diagram so you learn the language by reading a real one. You don’t need to install or build anything; open the modeler later if you want to interact with it.

If you want to skip ahead:

The example study

Below is a deliberately generic study: it collects a small amount of demographic data, runs one cognitive task, saves the data, runs a short analysis script, and produces a report. It is small enough to fit on one screen and exercises every category of element you will encounter elsewhere.

NoteDiagram (TODO)

The canonical Get Started diagram (first.studyflow.svg) needs to be authored in the modeler and saved to docs/assets/first.studyflow.svg (a rendered SVG with the source XML embedded). Until then, this page references it by name only.

The flow reads top-to-bottom:

  1. Start event: the participant arrives. The start event carries a consentFormUri attribute; when it is set, the runtime gates entry on informed consent.
  2. Questionnaire activity: a short demographics form. Studyflow’s Questionnaire activity carries language and text attributes inspected in the right panel.
  3. Cognitive task activity: one block of a CognitiveTask. The icon distinguishes it from a generic BPMN task; the inspector shows task-specific parameters.
  4. Data store (Dataset): the dataset where trial data is persisted. The flow from the task to the dataset is a data association (a dashed line), not a sequence flow.
  5. Script activity: a Script activity (a Manual or external script) that reads the dataset and computes summary statistics. Its type icon identifies it as a Transform; when the task also declares a function to run (uses), an ƒ marker appears at its bottom edge.
  6. Data store (Report): the output of the analysis: a small report artifact.
  7. End event: the study terminates cleanly.

Why every element earns its place

Each element above maps to a real concern in either an experiment or a pipeline:

  • The start event and consent gate are how researchers express ethics requirements in the diagram itself, not in a separate document.
  • The questionnaire and cognitive task are the experiment.
  • The dataset and the data association are the bridge: the cognitive task produces trial data that flows into storage. A reader can tell, from the diagram alone, what the task generates.
  • The script and its Transform marker are the pipeline. A pipeline author sees a normal task with an explicit data semantics; an experimentalist sees a normal “do some analysis” step. Both are reading the same element.
  • The report is the publishable artifact.

This is what we mean by “one diagram, many audiences.” A reviewer reading the methods section, a participant running the study, and an analyst reproducing the figure are all looking at the same .studyflow file.

What’s next

  • Try it in the modeler. Open the Modeler app, choose File → Open, and load first.studyflow.svg. Click each element to see its attributes in the inspector.
  • Learn the UI. Modeler app walks through palette, inspector, save/export, and simulation.
  • Browse element types. Elements catalogs every supported element with its icon.
  • See the formal language. Specification has the grammar, formal definition, and serialization examples.
  • Browse the gallery. Examples covers domain-specific patterns: N-back trials, CONSORT, analysis pipelines, MLOps.