Study Builder

Overview

The Study Builder is the core tool in the Open Lab platform for designing the flow of your online experiments. It provides a drag-and-drop interface to arrange components such as landing pages, consent forms, lab.js tasks, ending pages, and branching logic for between-subjects designs. This allows researchers to create customizable study sequences, integrate experiments built with lab.js, and manage randomization easily.

Access the Study Builder from the study dashboard by clicking the "Study Builder" button. The builder ensures the participant landing page is always first and validates the flow before saving. For more on lab.js integration, see the lab.js Integration section.

Building the Study Flow

The Study Builder interface consists of a horizontal flow where you can add, rearrange, and edit components. Components represent steps in the participant's journey through the study.

Available Components

• Participant Landing Page: The obligatory first component. Displays study information to participants before they start.
• Informed Consent: A form for obtaining participant consent, with customizable text.
• Lab.js Task: Integrates an experiment or survey built with lab.js. Upload or select from your existing tasks.
• Ending Page: The final page, often used for debriefing or thank-you messages.
• Between-Subjects Branching: Randomizes participants into different paths (branches) for experimental conditions.

Adding Components

To add a component:

1. Click the "+" button at the end of the flow.
2. Select the component type from the dropdown menu.
3. The new component will appear in the flow; click it to edit details in the editor panel below.

Note: The landing page cannot be removed and must remain first. Attempting invalid changes will trigger an alert.

Rearranging Components

Use drag-and-drop to reorder components:

1. Click and hold a component card.
2. Drag it to a new position in the flow.
3. Release to drop; the flow will update automatically.

Keyboard navigation is also supported for accessibility.

Editing Components

Select a component in the flow to open its editor panel. Each type has specific fields:

• Landing Page: Edit title and description shown to participants.
• Consent: Customize consent text; it's required by default.
• Lab.js Task: Select an existing task or upload a new lab.js JSON file. Preview the task directly.
• Ending Page: Add debriefing text.
• Branching: Define branches for randomization. Each branch is a sub-flow where you can add nested components.

Changes are tracked, and an "Unsaved Changes" indicator appears until you save.

Uploading New Lab.js Tasks

When adding a lab.js component:

1. Click "Add New Task" to open the upload modal.
2. Enter name, description, and upload a valid lab.js JSON file.
3. The file is processed and assembled; once uploaded, select it for the component.

Troubleshooting: Ensure the JSON is valid lab.js format. Errors will be displayed if processing fails.

Branching and Randomization

The branching component allows for between-subjects designs:

1. Add a branching component to the flow.
2. In the editor, add or remove branches (starts with two).
3. Each branch is a sub-flow; add components recursively within branches.

Participants are randomly assigned to one branch upon reaching it.

Previewing Tasks

For lab.js components, click the preview button in the editor to open a modal running the task. Data is not saved in previews. Close the modal to return to the builder.

Note: Previews require the lab.js library; ensure your browser allows scripts.

Test Run: Check Your Task Before You Launch

A test run auto-plays one of your lab.js tasks from start to finish — with no human input — and then shows a pass/fail report. It's a quick way to catch mechanical problems (a task that fails to load, throws a JavaScript error, dead-ends, never finishes, or records no data) before spending on participants. A test run is a preflight check, not a check of your study's scientific design.

On each lab.js task card in the study flow, a beaker icon sits next to the eye (Preview) icon — the beaker is the Test run button, and it appears once a task has been selected for the component. The task's editor panel also has a labeled Test run button beside Preview task.

Starting a Test Run

1. Click the beaker (Test run) button on a lab.js task. A window opens with a guidance card titled "Test run — before you invite participants." It explains what the test checks, how it works (every screen is answered automatically — a valid response is chosen, or timed screens are waited out), and reminds you that no data is saved.
2. Optionally tick "Run it 5 times to cover more branches." A single run follows one random path; running several times with randomized responses exercises more conditions and branches — slower, but more thorough.
3. Click "Start test run" (it shows "Preparing…" with a spinner while the task loads). The task then plays itself in the window behind an "Auto-testing your task … · no data saved" banner. Choose Cancel to close without running.

Reading the Report

When the run finishes, a card shows an overall verdict — "Test run passed" or "Issues found" — and a checklist:

• Study loaded and started
• Reached the end and would save data
• No JavaScript errors
• Images & media loaded
• Produced data
• No dead-end screens

The report also surfaces any advisory warnings (which do not fail the run) and, in coverage mode, a summary of how many runs passed and how many distinct paths were explored. From the card you can Download test data (CSV), Run again, or Close. The downloaded data comes from the automated run and is only useful for inspecting the shape of the task's output.

What It Catches — and What It Doesn't

A test run catches mechanical problems only: the task fails to load, a JavaScript error, a dead-end screen, a task that never finishes (for example an infinite loop, or a final screen with no ending, so a participant's data would never be saved), missing images or media, and screens that record no data. It does not check your study's scientific validity — it says nothing about condition balance, confounds, wording, or whether your reaction times are meaningful. Because responses are chosen automatically and instantly, the reaction times and accuracy in the report are artefacts, not real measurements. A single run follows one random path; the coverage option exercises more branches but still isn't exhaustive. Treat a green result as "the task runs," not "the study is correct."

Free-Plan Limit

Free accounts include 10 test runs in total across all tasks; Basic and above are unlimited. A run is counted only when you click "Start test run" — opening the guidance card and cancelling does not use one. On the free plan, the Test run button shows a small "N left" badge; when you run out, an upgrade prompt ("You've used all your free test runs") appears instead of a test starting. Manual previews are always free — the limit applies only to automated test runs.

Saving the Study

Click "Save Study" in the top-right to persist changes. The button pulses red if there are unsaved changes. After saving, return to the study dashboard to publish.

Troubleshooting: If saving fails, check for validation errors like missing required fields.

Next Steps

With your study flow designed, explore the following sections to continue managing your research on the Open Lab platform:

• Study Setup

  • Invitation Management: Manage invitations for participants to join studies.
  • Participant Management: Manage participant enrollment and study settings.
  • Settings: Manage study settings.

• Collaboration

  • Projects: Create and manage project cards to describe your research needs.
  • Collaborators: Find, invite, and collaborate with other researchers.

• Data

  • Data Analysis: Build visualizations to analyze study data.
  • Data Reports: Generate comprehensive reports from study data.