soconnor/hristudio
1
0
Fork 0
mirror of https://github.com/soconnor0919/hristudio.git synced 2026-05-08 13:58:55 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

feat(tutorials): add comprehensive tutorials for HRIStudio including Getting Started, Your First Study, Designing Experiments, Running Trials, Wizard Interface, Robot Integration, Forms & Surveys, Data & Analysis, and Simulation Mode

Browse Source
This commit is contained in:
Sean O'Connor
2026-03-25 22:48:42 -04:00
parent 3959cf23f7
commit 1c7f0297a6
34 changed files with 6298 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tutorials/04-running-trials.md
+366
View File
@@ -0,0 +1,366 @@
# Tutorial 4: Running Trials
Learn how to execute experiments and manage participant trials.
## Objectives
- Schedule and start trials
- Monitor trial progress
- Handle trial interruptions
- Collect trial data
## What is a Trial?
A **Trial** is a single execution of an experiment with one participant:
```
Trial
├── Participant (who took part)
├── Experiment (which protocol)
├── Status (scheduled, in_progress, completed)
├── Events (timestamped actions)
└── Data (collected responses)
```
## Trial Lifecycle
```
Scheduled → In Progress → Completed
│ │ │
│ ▼ │
│ Aborted ◄────────┤
│ │ │
└────────► Failed ◄───────┘
```
| Status | Description |
|--------|-------------|
| Scheduled | Trial is planned but not started |
| In Progress | Trial is currently running |
| Completed | Trial finished successfully |
| Aborted | Trial stopped early by wizard |
| Failed | Trial failed due to error |
## Step 1: Schedule a Trial
### Create Trial for Participant
1. Go to your **Study**
2. Open **Trials** tab
3. Click **Schedule Trial**
4. Select:
- **Participant**: P001
- **Experiment**: The Interactive Storyteller
- **Scheduled Time**: Today, 2:00 PM
### Batch Scheduling
For multiple participants:
1. Click **Batch Schedule**
2. Select participants (P001-P020)
3. Select experiment
4. Set time slots
```
| Time | Participant |
|------------|-------------|
| 2:00 PM | P001 |
| 2:15 PM | P002 |
| 2:30 PM | P003 |
| ... | ... |
```
## Step 2: Prepare for Trial
Before starting:
1. **Verify Robot Connection**
- Check robot is powered on
- Verify network connection
- Test WebSocket connection
2. **Review Experiment**
- Ensure experiment is "Ready" status
- Check step count and timing
- Verify all actions are configured
3. **Prepare Environment**
- Ensure participant consent is obtained
- Set up recording equipment (if needed)
- Remove distractions
## Step 3: Start a Trial
### From Trials List
1. Find the scheduled trial
2. Click **Start Trial**
3. Confirm participant is ready
4. Click **Begin**
### From Wizard Interface
1. Open **Wizard Interface**
2. Select trial from queue
3. Click **Start**
## Step 4: During the Trial
### Wizard Interface Overview
```
┌──────────────────────────────────────────────────────────────┐
│ Trial: P001 - Interactive Storyteller [00:05:23]│
├──────────────────────────────────────────────────────────────┤
│ ┌──────────────┐ ┌────────────────────┐ ┌─────────────────┐ │
│ │ Trial │ │ Timeline │ │ Robot Control │ │
│ │ Controls │ │ │ │ │ │
│ │ │ │ ●───●───○───○ │ │ ┌─────────────┐ │ │
│ │ [▶ Play] │ │ Step 1 2 3 4 │ │ │ Connected ✓ │ │ │
│ │ [⏸ Pause] │ │ ↑ │ │ │ Battery: 85%│ │ │
│ │ [⏹ Stop] │ │ Current: Step 2 │ │ └─────────────┘ │ │
│ │ │ │ │ │ │ │
│ │ [📝 Notes] │ │ Progress: 40% │ │ [Say Text] │ │
│ │ [⚠ Alert] │ │ │ │ [Move Robot] │ │
│ └──────────────┘ └────────────────────┘ │ [Custom Action]│ │
│ └─────────────────┘ │
└──────────────────────────────────────────────────────────────┘
```
### Trial Controls
| Button | Action | Keyboard |
|--------|--------|----------|
| Play | Resume trial | Space |
| Pause | Pause trial | Space |
| Stop | End trial early | Escape |
| Notes | Add timestamped note | N |
| Alert | Send alert notification | A |
### Monitoring Progress
**Timeline View:**
- Visual step progression
- Current step highlighted
- Completed steps checked
- Estimated time remaining
**Event Log:**
- Timestamped events
- Action executions
- Wizard interventions
- Robot responses
## Step 5: Wizard Interventions
During Wizard-of-Oz studies, wizards can intervene:
### Add Intervention
1. Click **+ Intervention**
2. Select type:
- **Pause**: Temporarily stop trial
- **Resume**: Continue after pause
- **Note**: Add observation
- **Alert**: Notify researcher
### Branch Selection
When reaching a conditional step:
1. Observe participant response
2. Select appropriate branch:
- **Correct**: Proceed to positive path
- **Incorrect**: Proceed to correction path
3. Select is logged for analysis
### Manual Actions
Execute unplanned actions:
1. Click **+ Action**
2. Select from robot actions
3. Configure parameters
4. Execute immediately
## Step 6: Trial Completion
### Automatic Completion
When all steps complete:
1. Final step executes
2. Trial status → "Completed"
3. Data is saved automatically
4. Summary shown
### Manual Completion
To end early:
1. Click **Stop Trial**
2. Confirm completion
3. Select reason:
- Participant fatigue
- Technical issue
- Protocol complete
4. Save partial data
## Step 7: Post-Trial
### Automatic Prompts
After trial completion:
1. **Participant Debrief**
- Thank participant
- Answer questions
- Collect final feedback
2. **Survey Distribution**
- Send post-session survey
- Collect responses
3. **Data Export**
- Download trial data
- Export event log
### Trial Summary
View trial summary:
```
┌─────────────────────────────────────────────────────────────┐
│ Trial Summary - P001 │
├─────────────────────────────────────────────────────────────┤
│ Duration: 5:23 │
│ Steps Completed: 6/6 (100%) │
│ Interventions: 2 │
│ │
│ Actions: │
│ ✓ Say Text: "Hello..." (2.3s) │
│ ✓ Turn Head: yaw=1.5 (1.1s) │
│ ✓ Say Text: "What color..." (3.2s) │
│ ⚠ Intervention: Pause (10s) │
│ ✓ Branch: Correct selected │
│ ✓ Say Text: "Yes! It was red" (2.8s) │
│ │
│ Events: 18 logged │
└─────────────────────────────────────────────────────────────┘
```
## Managing Multiple Trials
### Trial Queue
View upcoming trials:
```
┌─────────────────────────────────────────────────────────────┐
│ Trial Queue [Refresh] │
├─────────────────────────────────────────────────────────────┤
│ 2:00 PM │ P001 │ Interactive Storyteller │ Scheduled │
│ 2:20 PM │ P002 │ Interactive Storyteller │ Scheduled │
│ 2:40 PM │ P003 │ Interactive Storyteller │ Scheduled │
│ 3:00 PM │ P004 │ Interactive Storyteller │ Scheduled │
└─────────────────────────────────────────────────────────────┘
```
### Trial History
View past trials:
| Participant | Started | Duration | Status | Interventions |
|-------------|---------|----------|--------|---------------|
| P001 | Today 2:00 PM | 5:23 | Completed | 2 |
| P002 | Today 2:20 PM | 4:58 | Completed | 1 |
| P003 | Today 2:45 PM | - | In Progress | 0 |
## Data Collection
### Automatic Data Capture
HRIStudio automatically logs:
- Timestamps for all events
- Action executions
- Robot responses
- Wizard interventions
- Participant responses
- Timing data
### Manual Data
Wizards can add:
- Timestamped notes
- Observation categories
- Participant behavior codes
- Custom annotations
### Export Formats
Download trial data:
| Format | Contents |
|--------|----------|
| CSV | Tabular data for spreadsheets |
| JSON | Full event log with metadata |
| Video | Screen recording (if enabled) |
## Troubleshooting
### Trial Won't Start
1. Check robot connection
2. Verify experiment is "Ready"
3. Check participant consent
4. Review error logs
### Trial Paused Unexpectedly
- Robot may have disconnected
- Check network connection
- Resume when connection restored
### Data Not Saved
- Ensure database connection
- Check disk space
- Export data manually
## Best Practices
### Before Trials
- [ ] Robot connected and tested
- [ ] Experiment verified
- [ ] Participant consent obtained
- [ ] Recording equipment ready
- [ ] Wizard briefed on protocol
### During Trials
- [ ] Monitor timeline progress
- [ ] Take timestamped notes
- [ ] Document interventions
- [ ] Watch for issues
### After Trials
- [ ] Review trial summary
- [ ] Export data promptly
- [ ] Send follow-up surveys
- [ ] Update participant status
## Next Steps
Now that you can run trials:
1. **[Wizard Interface](05-wizard-interface.md)** - Master real-time control
2. **[Data & Analysis](08-data-and-analysis.md)** - Analyze your results
3. **[Forms & Surveys](07-forms-and-surveys.md)** - Collect post-trial data
---
**Previous**: [Designing Experiments](03-designing-experiments.md) | **Next**: [Wizard Interface](05-wizard-interface.md)