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.

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.