# Plinko Pilot: oTree Setup Guide

## oTree vs z-tree: the key differences

If you're coming from z-tree, the mental model shift is:

**z-tree** runs as a desktop app. You install it, open the GUI, load your .ztt file,
start the server, and subjects connect via z-leaf on lab computers. Everything is
configured through the z-tree GUI (stages, programs, tables).

**oTree** is a Python web app. You write the experiment in Python files, run a web
server from the command line, and subjects connect via any web browser (phone, laptop,
anything). There's no GUI for building experiments; you edit code directly. But the
tradeoff is that you get full HTML/CSS/JavaScript control over what subjects see,
and deployment is much more flexible.

The rough mapping:
- z-tree "stages" → oTree "pages" (defined in page_sequence)
- z-tree "programs" → oTree Python logic in __init__.py
- z-tree "subjects table" → oTree Player class fields
- z-tree "globals table" → oTree Group/Subsession class fields
- z-tree .ztt file → oTree project folder (the whole plinko_pilot/ directory)
- z-leaf → any web browser


## Installation

You need Python 3.8+ installed. Then:

```bash
pip install otree
```

That's it. No other dependencies needed for this project.


## Project structure

```
plinko_pilot/
├── settings.py              # Session config, app list (like z-tree's session params)
├── __init__.py              # Root module (mostly empty)
├── plinko/
│   ├── __init__.py          # ALL the experiment logic lives here:
│   │                        #   - TRIALS: pre-selected trial parameters
│   │                        #   - Player fields (what gets recorded per subject)
│   │                        #   - Page classes (what subjects see, in order)
│   │                        #   - creating_session(): randomizes trial order
│   ├── Introduction.html    # Instructions + animated Plinko demo
│   ├── ComprehensionCheck.html
│   ├── Trial.html           # Main task page with board visualization
│   └── Results.html         # Performance summary
└── _static/                 # Static files (CSS, JS, images)
```


## Running locally (testing on your own machine)

```bash
cd plinko_pilot
otree devserver
```

This starts a local server at http://localhost:8000. You'll see the admin interface.

**To test as a subject:**
1. Go to http://localhost:8000/demo
2. Click "Plinko Pilot" 
3. Click one of the participant links
4. Walk through the experiment

**To reset and start over:**
- Just stop the server (Ctrl+C) and run `otree devserver` again
- Or go to http://localhost:8000/SessionStartLinks and create a new session

The `devserver` mode auto-reloads when you edit files, so you can tweak
the templates and see changes immediately.


## Running in Brian's classroom

**Option A: Your laptop as server (simplest)**

1. Connect your laptop to the same WiFi as the classroom
2. Find your local IP: `ifconfig` (Mac/Linux) or `ipconfig` (Windows)
   - Look for something like 192.168.1.XXX
3. Run: `otree devserver 0.0.0.0:8000`
4. Write on the board: "Go to http://192.168.1.XXX:8000"
5. In the admin panel, create a session with N participants
6. Share the session-wide link (subjects get assigned automatically)

**Option B: oTree Hub (most reliable, free tier available)**

1. Go to https://www.otreehub.com
2. Create an account
3. Upload your project as a .zip (I've included the zip)
4. Deploy and get a public URL
5. Share the URL with the class

Option B is more reliable because it doesn't depend on your laptop
staying connected, and subjects can use any internet connection.


## Creating a session and getting links

From the admin panel (http://localhost:8000):

1. Click "Sessions" → "Create new session"
2. Select "plinko_pilot"  
3. Set number of participants (however many students)
4. Click "Create"

You'll get either:
- **Individual links**: One URL per participant (like z-tree's subject IDs)
- **Session-wide link**: One URL that assigns the next available slot
  to whoever opens it (easier for a classroom)

The session-wide link is usually what you want. Write it on the board
or send it to the class chat.


## Monitoring while subjects play

The admin panel shows real-time progress:
- http://localhost:8000/SessionMonitor shows which page each subject is on
- http://localhost:8000/SessionData shows responses as they come in

This is like z-tree's "Clients' Tables" view.


## Getting the data out

After everyone finishes:

1. Admin panel → Sessions → your session → "Data" tab
2. Click "Download" to get a CSV
3. Each row is one player-round (so 8 rows per subject)

Key columns:
- `participant.code`: anonymous subject ID
- `player.treatment`: T1 or T2
- `player.n_i`, `player.n_j`: prior/signal strength
- `player.x_i`, `player.x_j`: signals shown
- `player.theta_hat`: subject's estimate
- `player.theta`: true value
- `player.squared_error`: (theta_hat - theta)^2

You can also export to a wider format (one row per subject) from the
"Custom Export" option.


## Modifying the experiment

Most things you'd want to change are in `plinko/__init__.py`:

- **Trial parameters**: Edit the TRIALS list directly. Each dict has
  theta, n_i, n_j, x_i, x_j, landings_i, landings_j, treatment.
- **Number of trials**: Change C.NUM_ROUNDS and add/remove from TRIALS.
- **Payment formula**: Edit the Results page vars_for_template.
- **Instructions text**: Edit Introduction.html directly.
- **Board visualization**: Edit the JavaScript in Trial.html.

After editing, the devserver auto-reloads. Refresh your browser to see changes.


## Comprehension checks

The current comprehension check has two questions that subjects must
answer correctly before proceeding (they get feedback and retry on errors).
You can add/remove questions in the ComprehensionCheck section of __init__.py.


## Common gotchas

1. **"Address already in use"**: Another server is running on port 8000.
   Kill it or use a different port: `otree devserver 0.0.0.0:8080`

2. **Subjects see old version**: Hard refresh (Ctrl+Shift+R) or clear cache.

3. **Database issues**: Delete db.sqlite3 and restart the server.

4. **Template errors**: oTree uses its own template syntax (similar to Django).
   - `{{ variable }}` to display values
   - `{{ if condition }}...{{ endif }}` for conditionals
   - `{{ for item in list }}...{{ endfor }}` for loops