Introductory Workshop on Programming Experiments with oTree

Gregory Chernov 2025

Workshop Overview

Duration: 16 Academic Hours
No programming experience required
Recommended: Basic Python knowledge and oTree tutorials

Useful Links for oTree and Tools

🕹️ Example Code

Guessing Game Code: github.com/gregory-ch/otree_workshop

🧪 Demos

oTree Hub Demo: public-class-demo.herokuapp.com
More Demos: otree-more-demos.herokuapp.com

🔧 oTree Tools and Projects

oTree3 tools: github.com/otree-tools/otree_tools
oTree HR: github.com/chkgk/otree-hr

📚 Guides and Tutorials

Git Guide
Why Use oTree Hub?
oTree Hub Deployment Tutorial
oTree Heroku Setup Guide
Platforms and Panels for Online Behavioral Research
oTree on Prolific

🌐 Other Resources
Heroku Developer Program
oTree Hub

Programming Experiments Overview

Popular Platforms for Experimentation

Platform	Launch	Core Components	Languages	Key Features
oTree	2013	Django, Starlette	Python, JS	N-players, real-time, custom UI
zTree	1998	Client-server	Pascal-like	Own simple exp language
Qualtrics	2002	Survey engine, js-friendly	No coding	Advanced surveys, branching logic, self-hosting
PsychoPy/jsPsych	2003/2012	Python/JS /assets/html/export/libs	Python/JavaScript	Precise timing, visual stimuli, online/offline experiments
G.Forms	2008	Google Cloud	No coding	Basic surveys, easy integration

Some others: Lioness; Sofi(PHP), etc.

Core Concepts of Coding Experiments

Any experiment consists of two basic actions:

1. Show something (stimulus) 2. Collect reaction (response)

  ┌──────────────┐     ┌──────────────┐
  │   STIMULUS   │     │   RESPONSE   │
  │  Show info   │ --> │   Collect    │
  │  Display UI  │     │   reaction   │
  └──────────────┘     └──────────────┘
          ▲                    │
          └────────────────────┘
          Next iteration
  

E.G. show kitten image and ask happiness level

Implementation methods:

Pen and paper (+engagement, -UI)
Web server (stimulus) ↔ Browser (response)
oTree = web framework for this cycle

Web Application Architecture

oTree overview (MVC Framework)

Models: Core logic and database (Starlette, SQLite/PostgreSQL)
Controller: Page logic, function call order, and event sequence (Starlette, called pages in Django).
Views/Templates: Front-end structure
- HTML
- CSS (Bootstrap)
- JavaScript

Platform Comparison

Feature	oTree	zTree	Qualtrics	jsPsych	g.forms
Games	✓	✓	✗	!	✗
N-players	✓	✓	✗	✗	✗
Online	✓	!	✓	✓	✓
Code Req.	✓	✓	!	✓	✗
Custom UI	✓	!	!	✓	✗
Free	✓	!	✗	✓	✓
Surveys	✓	!	✓	!	✓
Mobile	✓	✗	✓	✓	✓
Self-host	!	✗	✓	✓	✓
Active community	✓	✓	✗	✗	✗
Legend:	✓ Full	! Limited	✗ None

oTree: Conceptual Overview

oTree Admin Panel

Session Monitor: Real-time participant progress tracking
Data: Live data viewing and CSV/Excel export
Links: Participant access URLs (demo/study modes)
Payments: Payment calculations and reports
Sessions: Create and manage experiment sessions

Demo: https://otree-more-demos.herokuapp.com/demo

oTree: webapp (server) and template

About	Features & Options
Platform	• Standard web server (like Instagram) • Multiplayer strategy games • Can integrate what other web can
Development	• Standard: Python + text editor • No-code: oTree Studio • Rich documentation & demos
Technology	• Python, Django/Starlette backend • JS/Bootstrap frontend • SQLite/PostgreSQL
Deployment	• Local server for lab • Cloud hosting (Heroku) • oTree Hub integration

Sample experiment: Guessing Game

Simple game demonstrating core oTree concepts (models, pages, templates)

Repository structure:

otree_workshop/
  └── guessing_game/            # Example game
      ├── _static/              # Static files
      ├── _templates/           # Global templates
      ├── guessing_app/         # Game application
      │   ├── __init__.py      # Game logic
      │   ├── Instructions.html # Game pages
      │   ├── MyPage.html
      │   └── Results.html
      └── settings.py           # Project settings

Code: github.com/gregory-ch/otree_workshop

Guess Game: Description

A player has an endowment
Random number is generated within certain limits
A player has to guess. The closer is the guess to a real number the larger is the profit
Two fields:
- what is guessed
- a player's decision
Three screens:
- Intro: instructions
- Decision with instructions
- Results

Guessing Game: Instructions Page

Guessing Game: Decision Page

Main Game Page

Guessing Game: Results Page:

Results Page

Introduction to the Model-View-Controller (MVC) framework

oTree 3 vs oTree 5 (Lite)

oTree 3:
- Django-based
- Slower, more complex
- Better documented
- More examples available
- Some custom moduls available:
  - oTree tools (github.com/otree-tools/otree_tools)
  - oTree HR (github.com/chkgk/otree-hr)

oTree 5:
- Starlette-based (no-self)
- Faster, simpler (No redis, no second dynos)
- Better performance

oTree: Object Hierarchy

Session = Event where participants play games/tasks

Example: "Lab session with public goods game + questionnaire"
Includes payments, configurations, participant management

Session and Subsession Structure

Structure of oTree App

Pages (Display Logic)
- Page classes (Instructions, Game, Results)
- page_sequence (order of pages)
- Templates (HTML files)
Models (Data Processing)
- Constants: game parameters
- Player (individual); Group (interaction);
  Subsession (session-level data & methods)
- Functions (calculation of payoffs
  and other properties based on input)
Configuration
- App definition in settings.py
- Session configs

oTree: Initialization Sequence

Session Creation (by Admin)
- Admin creates session (room/demo/single-use link)
- Session configs applied
- Session variables initialized
- Participants slots created
- creating_session() runs:
  - Can initialize participant.vars
  - Can set participant.label
  - Can set initial participant.payoff
- Subsessions, Groups, Players created
Waiting for Participants
- Links generated and distributed
- Participants slots with pre-initialized vars wait

Participant Joins
- Participant opens link
- Gets assigned to pre-created slot
- Accesses their pre-initialized variables
- Starts first page in page_sequence

Page Flow

Pages execute in order from page_sequence

For each page:

BEFORE page is shown:

is_displayed() # (should return 
  # True if page is to be shown)
  vars_for_template()

AFTER page is shown:

before_next_page()
  app_after_this_page()

oTree: Models Object Hierarchy

Session
      └── Subsession
          └── Group
              └── Player

Access pattern (bottom-up):

player.participant  # Access participant from player
  player.group       # Access group from player
  player.subsession  # Access subsession from player
  group.subsession   # Access subsession from group

oTree: Players vs Participants