# Pavlovia Export Guide

## Overview

PRISM can export survey/questionnaire data to PsychoPy/Pavlovia format, enabling you to run your validated questionnaires as online experiments on Pavlovia.org.

## Why Export to Pavlovia?

- **Online Data Collection**: Host questionnaires on Pavlovia for remote participants
- **Integration with Experiments**: Combine surveys with cognitive tasks in PsychoPy
- **Advanced Features**: Reaction times, randomization, conditional logic
- **Data Management**: Automatic data saving to Pavlovia servers or OSF

## Architecture

### From PRISM to Pavlovia

```
PRISM Survey JSON
    ↓
pavlovia.py converter
    ↓
PsychoPy .psyexp + conditions.csv
    ↓
PsychoPy Builder/Pavlovia
    ↓
Online Experiment
```

### What Gets Converted

| PRISM Feature | Pavlovia Component |
|--------------|-------------------|
| Questions | Form components or Text + Slider |
| Levels (answer options) | Choice lists / Scale parameters |
| Items (array subquestions) | Loop + spreadsheet conditions |
| Condition (relevance) | Code components with if-statements |
| Position.GroupOrder | Routines in Flow |
| Mandatory | Validation in code component |

## Usage

### Basic Conversion

```bash
# Convert single questionnaire
python src/converters/pavlovia.py task-bdi_beh.json

# Output: task-bdi/task-bdi.psyexp
```

### With Customization

```bash
# Specify output directory and experiment name
python src/converters/pavlovia.py \
    task-bdi_beh.json \
    --output ./experiments/bdi_online \
    --experiment-name "BDI-II Online"
```

## Generated Structure

```
task-bdi/
├── task-bdi.psyexp          # PsychoPy experiment definition
├── task-bdi.py              # Python version (for local testing)
├── task-bdi.js              # JavaScript version (auto-generated by PsychoPy)
├── index.html               # Web hosting wrapper (auto-generated)
├── conditions.csv           # Trial/question parameters
└── README.md                # Instructions for uploading to Pavlovia
```

## Question Type Mapping

### Single Choice (Radio Buttons)

**PRISM:**
```json
{
  "BDI01": {
    "Description": "Sadness",
    "Levels": {
      "0": "I do not feel sad",
      "1": "I feel sad much of the time",
      "2": "I am sad all the time",
      "3": "I am so sad or unhappy that I can't stand it"
    }
  }
}
```

**Pavlovia:** Creates a Form component with radio buttons or a Slider component with labeled ticks.

### Array Questions (Multiple Items)

**PRISM:**
```json
{
  "STAI": {
    "Description": "State Anxiety",
    "Items": {
      "01": {"Description": "I feel calm", "Order": 1},
      "02": {"Description": "I feel secure", "Order": 2}
    },
    "Levels": {
      "1": "Not at all",
      "2": "Somewhat", 
      "3": "Moderately so",
      "4": "Very much so"
    }
  }
}
```

**Pavlovia:** Creates a loop with conditions spreadsheet where each row = one item.

### Free Text

**PRISM:**
```json
{
  "COMMENTS": {
    "Description": "Any additional comments?",
    "QuestionType": "Long Free Text"
  }
}
```

**Pavlovia:** Creates a Form component with textbox.

## Advanced Features

### Conditional Display

**PRISM:**
```json
{
  "PHQ9_10": {
    "Description": "Suicide ideation follow-up",
    "Condition": "PHQ9_09 > 0"
  }
}
```

**Pavlovia:** Generates code component that checks previous response and conditionally shows question.

### Randomization

Use PRISM groups with randomization:

**PRISM:**
```json
{
  "Position": {
    "Group": "BlockA",
    "RandomizeGroup": true
  }
}
```

**Pavlovia:** Creates separate loops that can be randomized in the Flow.

## Limitations

### Not Currently Supported

- **Complex Logic**: Nested conditions (e.g., "(Q1=1 OR Q2=2) AND Q3>5")
- **Piping**: Inserting previous answers into question text
- **Question Arrays with Multiple Scales**: Dual-scale arrays
- **File Uploads**: Not typical in surveys

### Workarounds

1. **Complex Logic**: Manually edit the generated code component
2. **Piping**: Use PsychoPy's variable substitution (`$variableName`)
3. **Dual Scales**: Create as two separate questions

## Testing Before Upload

1. **Open in PsychoPy Builder**: 
   ```bash
   psychopy task-bdi.psyexp
   ```

2. **Test Locally**: Click the green "Run" button

3. **Export HTML**: File → Export HTML → Check "Export to Pavlovia"

4. **Upload to Pavlovia**: 
   - Create project on Pavlovia.org
   - Use git or Pavlovia sync to upload files

## Integration with PRISM Workflow

### Typical Workflow

1. **Design in LimeSurvey or JSON Editor**
2. **Convert to PRISM**: `python helpers/surveys/limesurvey_to_prism.py`
3. **Validate**: `python prism.py --validate task-bdi_beh.json`
4. **Export to Pavlovia**: `python src/converters/pavlovia.py task-bdi_beh.json`
5. **Upload to Pavlovia**: Via PsychoPy or git
6. **Collect Data**: Participants complete online
7. **Download Data**: From Pavlovia.org
8. **Convert Back to PRISM**: `python src/converters/pavlovia.py --import data.csv task-bdi_beh.json`

### Data Round-Trip

```
PRISM TSV/JSON → Pavlovia → Online Data → CSV Download → PRISM TSV/JSON
```

## See Also

- [LimeSurvey Integration](LIMESURVEY_INTEGRATION.md)
- [Survey Library](SURVEY_LIBRARY.md)
- [PsychoPy Documentation](https://psychopy.org/builder/)
- [Pavlovia Documentation](https://pavlovia.org/docs)