hristudio/docs/tutorials/03-designing-experiments.md

Tutorial 3: Designing Experiments

Learn how to create experiment protocols using the visual block designer.

Objectives

• Navigate the experiment designer
• Use core blocks (events, wizard actions, control flow)
• Build a branching experiment protocol

What is an Experiment?

An Experiment defines the protocol for your study:

Experiment
├── Steps (ordered sequence)
│   ├── Actions (robot behaviors)
│   ├── Wizard Blocks (human decisions)
│   └── Control Flow (loops, branches)
├── Robot Actions (from plugins)
└── Parameters (configurable values)

Step 1: Create an Experiment

1. Open your study
2. Go to Experiments tab
3. Click New Experiment

Experiment Settings

Field	Description
Name	Protocol title
Description	What the experiment measures
Robot	Which robot to use
Version	Track protocol versions

Step 2: The Experiment Designer Interface

The designer has three main areas:

┌──────────────────────────────────────────────────────────────┐
│  Experiment: Robot Trust Study v1                    [Save]  │
├────────────┬─────────────────────────────────────────────────┤
│            │                                                  │
│  Blocks    │           Canvas                                 │
│  Library   │                                                  │
│            │    ┌─────────┐    ┌─────────┐                   │
│  ┌──────┐  │    │ Step 1  │───▶│ Step 2  │                   │
│  │Events│  │    │ Hook    │    │ Story   │                   │
│  ├──────┤  │    └─────────┘    └────┬────┘                   │
│  │Wizard│  │                        │                        │
│  ├──────┤  │                   ┌────▼────┐                   │
│  │Control│  │                   │ Step 3  │                   │
│  ├──────┤  │                   │ Check   │                   │
│  │Robot │  │                   └────┬────┘                   │
│  └──────┘  │                   ┌────┴────┐                   │
│            │              ┌────┴───┐ ┌───┴────┐              │
│            │              │Step 4a │ │Step 4b │              │
│            │              │Correct │ │ Wrong  │              │
│            │              └───┬────┘ └───┬────┘              │
│            │                  └─────┬─────┘                   │
│            │                   ┌────▼────┐                    │
│            │                   │ Step 5  │                    │
│            │                   │Conclude │                    │
│            │                   └─────────┘                    │
├────────────┴─────────────────────────────────────────────────┤
│  Properties Panel                                           │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │ Step 1: The Hook                                       │ │
│  │ Duration: 25 seconds                                   │ │
│  │ Actions: 2 blocks                                      │ │
│  └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

Step 3: Understanding Block Categories

Events (Triggers)

Start your experiment with these blocks:

Block	Description
Trial Start	Triggers when trial begins
Wizard Button	Waits for wizard to press a button
Timer	Waits for a specified duration
Participant Response	Waits for participant input

Wizard Actions

Blocks the wizard can control:

Block	Description
Say Text	Robot speaks text
Play Animation	Play a predefined animation
Show Image	Display image on robot screen
Move Robot	Move robot to position

Control Flow

Control experiment progression:

Block	Description
Branch	Split into multiple paths
Loop	Repeat a sequence
Wait	Pause for duration
Converge	Merge multiple paths back

Robot Actions

Actions from your installed robot plugin:

Block	Description
say_text	Robot speaks
walk_forward	Robot walks forward
turn_left	Robot turns
wave	Robot waves

Step 4: Building "The Interactive Storyteller"

Let's build a simple storytelling experiment with branching:

Step 1: The Hook (Start)

1. Click + Add Step
2. Name it "The Hook"
3. Set type to Robot
4. Drag Say Text block:

   text: "Hello! I have a story to tell you. Are you ready?"
   

5. Drag Move Arm block:

   arm: right
   gesture: welcome
   

Step 2: The Narrative

1. Add new step "The Narrative"
2. Connect from Step 1
3. Add Say Text:

   text: "Once upon a time, a traveler flew to Mars..."
   

4. Add Turn Head for gaze behavior:

   yaw: 1.5
   pitch: 0.0
   

Step 3: Comprehension Check (Branching)

1. Add new step "Comprehension Check"
2. Set type to Conditional
3. Add Ask Question:

   question: "What color was the rock?"
   options:
     - Correct: "Red"
     - Incorrect: "Blue"
   

4. This creates two paths automatically

Step 4: Branch Paths

Branch A (Correct):

Say: "Yes! It was a glowing red rock."
Emotion: Happy

Branch B (Incorrect):

Say: "Actually, it was red."
Emotion: Sad

Step 5: Converge

1. Add new step "Story Continues"
2. Set type to Converge
3. Connect both branches to this step
4. Add concluding speech

Step 6: Conclusion

1. Add final step "Conclusion"
2. Add Say Text: "The End. Thank you for listening!"
3. Add Bow animation

Step 5: Block Properties

Each block has configurable properties:

Say Text Block

{
  "text": "Hello, how are you?",
  "language": "en-US",
  "speed": 1.0,
  "emotion": "neutral"
}

Branch Block

{
  "variable": "last_response",
  "options": [
    { "label": "Yes", "value": "yes", "nextStepId": "step_abc" },
    { "label": "No", "value": "no", "nextStepId": "step_xyz" }
  ]
}

Loop Block

{
  "iterations": 3,
  "maxDuration": 60,
  "children": [...]
}

Step 6: Testing Your Experiment

Preview Mode

Test your experiment without running a real trial:

1. Click Preview button
2. Step through each block
3. See timing and flow
4. Test branching decisions

Simulation Mode

Run with a simulated robot:

1. Enable NEXT_PUBLIC_SIMULATION_MODE=true
2. Start a trial
3. Robot actions are logged but not executed
4. Great for protocol testing

Advanced: Parallel Execution

Run multiple actions simultaneously:

Step: Greeting
├── Parallel Block
│   ├── Say: "Hello!"
│   ├── Move Arm: Wave
│   └── Move Head: Look at participant

Experiment Versioning

Track protocol changes:

1. Draft - Experiment being designed
2. Testing - Being tested with participants
3. Ready - Approved for data collection
4. Deprecated - Superseded by newer version

Common Patterns

Linear Protocol

Start → Step 1 → Step 2 → Step 3 → End

Branching Protocol

Start → Step 1
          ├── Condition A → Step 2a
          └── Condition B → Step 2b

Loop Protocol

Start → Step 1 → Loop (3x) → Step 2 → End
             ↑
             └── (back to Step 1)

Parallel Protocol

Start → Parallel
          ├── Action A
          ├── Action B
          └── Action C
        → Continue

Troubleshooting

Block Not Connecting

• Check step types are compatible
• Ensure no circular dependencies
• Verify conditions are complete

Robot Action Not Available

• Install the robot plugin
• Check plugin is enabled for study
• Verify robot is connected

Timing Issues

• Adjust duration estimates
• Use explicit wait blocks
• Test with real timing

Next Steps

Now that you've designed your experiment:

1. Running Trials - Execute your experiment
2. Wizard Interface - Learn real-time control
3. Robot Integration - Connect your robot

---

Previous: Your First Study | Next: Running Trials