Experiment Cookbook

A tutorial on running experiments with oTree


Ali Seyhun Saral


October 1, 2024



This book is a work in progress and its not complete. I am updating the pages at the moment and it will be published officially on the 1st of October, 2024.

You can refer to the slides of the course I gave recently.

What is this book about?

This book aims to guide you through programming experiments using oTree, a popular Python-based framework for behavioral experiments. It originated from lecture notes I prepared for a course at the Max Planck Institute for Research on Collective Goods in 2020. The material has since been updated to align with the latest version of oTree.

I designed this book with researchers in mind—those who may lack extensive programming experience but wish to code their own experiments. The text adopts a step-by-step methodology, breaking down potentially confusing concepts for those unfamiliar with programming. It also features chapters that delve into more advanced topics, along with a set of recipes (that’s where the cookbook name comes from 🙂 )for experienced users.

Who is the author?

I am a postdoctoral researcher at the Institute for Advanced Study in Toulouse, where I conduct research in fields such as behavioral and experimental economics. I am a self-taught programmer and have worked pretty much in every role related to behavioral experiments—including intern, research assistant, programmer, and lab manager—as well as research positions related to experiments. So I think myself as a person who has a good understanding of the needs of different people in the field. Hopefully this is the case.

How to use this book?

The book is structured to be as self-contained as possible. While it begins with an introduction to oTree, it assumes some prior knowledge of Python. However, for those new to Python or in need of a refresher, I’ve included an extensive crash course in Python as an appendix. You can start there and then circle back to the beginning if necessary.

The book is divided into three parts: - The first part features tutorial chapters with accompanying oTree concepts, indicated by a green icon 📗. These chapters are interconnected, and I recommend that beginners follow them in sequence. - The second part, symbolized by an orange icon 📙, serves as the “cookbook.” Here, I provide examples that address common issues or demonstrate frequently used features. - The final section, “the appendix” includes brief crash courses on related subjects, marked with a ledger icon 📒.

What is in the pipeline?

I have plans to expand this book further. Here’s a list of topics that readers have requested and are on the pipeline:

  • Chat functionality between the experimenter and participants
  • Using bots
  • Live pages
  • Online recruitment platforms
  • Dropout management
  • Outsourcing coding tasks
  • Version management

How to contribute?

Originally, I envisioned this book as a collaborative endeavor. However, time constraints have led me to keep it as a personal project. Despite this, I warmly welcome suggestions and feedback. To contribute, please open an issue or a pull request on the GitHub repository.

What are some other resources to learn oTree?


Creating this book wouldn’t have been possible without the encouragement and assistance from numerous individuals. While I can’t mention everyone, a few deserve special acknowledgment.

I am grateful to Christoph Engel for inspiring me to teach the oTree course at the Max Planck Institute for Research on Collective Goods, as well as a similar course at IMPRS Summer School. I would also like to thank course participants. I would like to thank Oliver Kirchkamp, who is a role model for teaching technical topics to researchers. I would also like to thank Matteo Ploner whom I learned a lot from his courses and from the discussions I had with him on best practices. Further, a big thank you goes to those who provided helpful feedback and suggestions: Sandro Ambuehl, Robert Böhm, Esra Dağlı, Özgür Gürerk, Ingar Haaland, Laura Hoenig, Konstantinos Ioannidis, Nathan Maddix, Stefan Schmidt, Filippo Toscano, and Tobias Werner.

While writing this book, I was inspired by two projects: Causal Inference: The Mixtape and The Turing Way. I would like to thank their authors/contributors of these projects as well.

Lastly, I’d like to express my gratitude to Chris Wickens, the creator of oTree, for his excellent framework and continuous support to the community, as well as to the oTree community at large for their ongoing support and feedback.