Read a studyflow

Open someone else’s studyflow file

When you receive a .studyflow file – from a collaborator, a paper supplement, or a previous version of your own work – there is a quick path to understanding it. This guide walks through that path.

0. SVG or .studyflow?

If you have an SVG, you can open it in any image viewer or browser. The SVG is a static snapshot of the studyflow, showing all the elements and their connections. If the studyflow is embedded in the SVG, you can inspect it with the Modeler app. If you have a .studyflow file, you can open it in the Modeler app (on any other BPMN tool) and inspect its attributes.

1. Open it and zoom out

Open the file in the Modeler app (File → Open). The first thing to do is zoom out until the whole diagram fits. Studyflows read top-to-bottom or left-to-right; the overall shape tells you the lifecycle the study covers.

A study that is mostly tasks and questionnaires is a data-collection study. A study with several data stores and a chain of data transformation markers is a pipeline. The overall shape gives you a mental model of the study before you dive into the details.

If you see datasets, click to inspect their schema – that usually tells you the data being collected or analyzed.

2. Find the boundaries

Locate:

  • The start event(s). What triggers the study? Is the start event annotated with requiresConsent or other gating?
  • The end event(s). Where does the flow terminate? Multiple end events usually indicate exception paths (e.g., dropouts).
  • Any sub-processes (rectangles with a +). These hide complexity. Click in to see the nested flow.

3. Identify the data structures

Datasets and data objects tell you the what of the study, not just the how. Look for:

  • Cylinder shapes (datasets) – what is being persisted over time?
  • Document shapes (data objects) – what is internally flowing between tasks?
  • Dataset or Table elements – what schemas are involved? Click them to see the inspector.

Some data flows reveal the experiment’s purpose faster than the process flow does. For example, if you see a dataset called “MemoryTestResults” being written by a cognitive task, you can infer that the study is about memory performance.

4. Read the activities in order

Walk the sequence flow from start to end. For each activity:

  • Type icon. Questionnaire, cognitive task, instruction, rest, script, manual – each looks different.
  • Inspector attributes. Click and read the right panel. This is where specific parameterization live (stimulus, duration, language, model parameters).
  • Function marker. If a data operation has an ƒ marker at its bottom edge, it declares a function to run (uses, e.g. python:// or docker://). The kind of operation (Map, Filter, Reduce, etc.) is conveyed by its type icon and the inspector.

5. Read the gateways

Each gateway is a decision: how does the flow branch?

  • Exclusive (X) – one path is taken based on a condition. Check the condition on each outgoing flow.
  • Parallel (+) – all paths run concurrently.
  • Inclusive (O) – multiple paths can be taken based on conditions.
  • Random (?) – stochastic gateway. Inspect each outgoing flow for its probability.
  • Stratified (S) – stratified random gateway. Each outgoing flow has a probability and a condition; the flow is randomly assigned to one of the paths that meet the condition.

If you can’t tell which branch will be taken, the labels on the outgoing sequence flows usually explain it. You can also use “Simulate” mode in the Modeler app to see how the flow would execute.

6. Check the temporal hints

If activities have start/end times, durations, or progress, the Timeline view renders them as a Gantt chart. For schedule-driven studies (longitudinal, clinical), the Timeline view is often more informative than the Study view.

Checklist

When reviewing a studyflow for a paper, this checklist catches most issues: