oTree is an open-source, Python-based framework that lets you build Multiplayer strategy games, behavioral experiments, and surveys/quizzes. What I especially like is that entire projects can be saved in their raw code form, being easily shared, reproduced, and modified.

Despite its extreme versatility, picking up a new software platform for conducting studies can have a steep learning curve. I personally struggle quite a lot to get the pieces fitting together.

One of the many hurdles I have faced in my oTree journey is getting my project properly onto a server and getting it implemented in Prolific.

This guide is designed for people like me: those just getting into programming, with simple things being harder than they need to be. What follows is a step-by-step instruction to get you from only running your project in localhost to having it be accessible to participants on Prolific.

Some things (like updating participant payoffs based on in-study decisions), are beyond my current knowledge and not included here. My hope is to provide updates to this post as I become more knowledgeable.

Useful Resources

I am far from qualified in giving advice on topics of software. Better resources and smarter people can be found at the oTree docs, the oTree Google groups forum, or the oTree discord channel.

Special thanks to Chris Wickens for being active not just in the development of oTree, but in responding to the many questions posed by the community.

• I’d also recommend checking out oTree’s example code repository if you’re in the early stages of working out how to use oTree. You can see a lot of examples of functions in different contexts, which I find helpful for learning (and stealing)

I’m also indebted to those that have posted video tutorials on using oTree:

• oTree tutorials

• Accounting experiments

Assumptions

I don’t know whether these assumptions are a necessary part of being able to follow this workflow, but I do know I got it working in this environment

1. Have your project set up in PyCharm (free license available for students and academics)

2. Have a functioning, multi-app otree project

   • This guide might be limited to one-sided (i.e., non-partnered) studies, check accordingly

3. Have otree up-to-date to your preferences

   • pip install otree

     • to install otree lite (aka. Otree 5 – not dependent on Django)

   • If you would like to guarantee that you stay on version 3.x, use this command next time you upgrade:

     • pip3 install -U "otree\<5" (https://groups.google.com/g/otree/c/D5TZseoELN0/m/eLLw1gTFBAAJ)

4. You wish to connect heroku through github (instead of using otreehub)

Otree Side

How to integrate Prolific IDs in study

Identifying and storing Prolific IDs are necessary for making sure that participants are paid properly (e.g., making sure an ID isn’t seen twice in the study, or being able to confirm whether an ID provided valid responses)

Working with Prolific IDs in oTree is accomplished through configuring a room and the study url

1. Go to your settings.py and set ROOMS with your desired name (used in url) and display_name

For example:

ROOMS = [
    dict(
        name='your_study',
        display_name='your_study',
        # participant_label_file='_rooms/your_study.txt',
        # use_secure_urls=True,
    ),
    dict(
        name='your_prolific_study',
        display_name='your_prolific_study',
        # participant_label_file='_rooms/your_study.txt',
        # use_secure_urls=True,
    ),
]

2. As seen below, on one of your early apps, assign the location (player), and method (before_next_page) for extracting participant.label

   • Try one page after consent so you don’t extract unnecessary info

class Player(BasePlayer):
    prolific_id = models.StringField(default=str(" "))


class Demographics(Page):
    form_model = 'player'
    form_fields = ['age', 'gender', 'education', "income"]

    @staticmethod
    def before_next_page(self, timeout_happened):
        self.prolific_id = self.participant.label
pass

3. Remove/comment out the participant label file (if you haven’t already)

The participant.label value (which will be functionally the same as participant_label) will be populated from the participant’s Prolific ID, which will be explained in section 4 – Prolific Side.

Before this step, you’ll need to change the link from local host to wherever you’re hosting the link (e.g., Heroku – explained below)

Linking to completion page

Recommended practice in prolific seems to be re-directing participants back to the Prolific website for their completion code. This can be specified in the session configs like so:

4. Update completionlink field in session_configs with a link to a prolific “completed submission” site with your custom completion code (use a placeholder link, and replace once you have a study created in prolific)

SESSION_CONFIGS = [
dict(name='your_prolific_study', 
     app_sequence=['consent', 'intro', 'your_experiment',
     'questionnaires', 'payment_info'], 
     num_demo_participants=1, 
     completionlink=
       'https://app.prolific.co/submissions/complete?cc=11111111',
),
]

For better generality, I’d recommend assigning your completionlink variable to a javascript variable, as below:

5. In init for your last app, configure a completion link for your very last page

class PaymentInfo(Page):
    form_model = 'player'

    def is_displayed(player):
        participant = player.participant
        return participant.consent == True

    @staticmethod              
    def js_vars(player):
        return dict(
            completionlink=
              player.subsession.session.config['completionlink']
        )
    pass

6. In your targeted payment html page, pass submission link to participants with a JavaScript automatic redirect

<script>
    let completionlink = js_vars.completionlink;

    window.onload = function(){
        window.location.href=completionlink;
    }
</script>

The is_display statement in 5 is useful so that only participants who consent will end up seeing your payment page. This is especially useful if you configure your consent app like below:

    @staticmethod       # populates a participant 
#variable with the respondent's consent status (for use across apps)
    def before_next_page(player: Player, timeout_happened):
        participant = player.participant
        participant.consent = player.consent

    @staticmethod       
        # sends nonconsenting participants to the last app
    def app_after_this_page(player, upcoming_apps):
        if not player.consent:
            return upcoming_apps[-1]

PARTICIPANT_FIELDS =['consent']

Heroku Side

Useful resource here

Heroku is the major platform for getting your study online.

There are a few ways to connect to heroku – otreehub, github (through Heroku), and the command shell (uses git). Through my personal learning, I became most familiar with the command shell method and GitHub, but I’d also try checking out oTree Hub, which is the recommended method for holding your hand through deployment.

Command shell method

Heroku login
# Press any key to open browser

Git init
#makes folder
Git add.
#add files into folder

Git commit
#Put in email and name if prompted

Heroku <git:remote> -a name_of_your_heroku_app

Git push Heroku main

# uploads to Heroku

Heroku run "otree resetdb"

#prepares database to work in otree *needs to be done everytime changes are made to models.py*)

Git commit -am "your commit message"

Git push Heroku main

Heroku run "otree resetdb"

Heroku config:set OTREE_AUTH_LEVEL=DEMO
#Controls what a user without password can do, In this case, demo

Heroku config:set OTREE_ADMIN_PASSWORD=mypassword
#When accessing admin interface -- require mypassword

OTREE_PRODUCTION=0
#Takes value 1 or 0; If an error, toggles whether participants will see a brief (1) or detailed error message
# left 0 because a full-page error is thrown otherwise

GitHub method

Your resulting link will look like: https://your_heroku_app.herokuapp.com/room/your_prolific_study

Further testing of Heroku app

1. Navigate to Heroku

• Click open app

2. Enter rooms tab again, create session with target config

• Double check that you’ve removed the participant label file – otherwise you hit a label input page

• If you want to test how the participant label is handled, keep a participant label file, and add some participant labels

  • Then, you can use a url that specifies a valid participant label using the ?participant_label= argument

    • E.g. https://your_heroku_app.herokuapp.com/room/your_prolific_study?participant_label=id_prolific_test

      • Or anything, so long as it’s in your participant label file

Prolific Side

After the past two sections, you should have the means to track Prolific URLs, administer completion links, and host your study outside of your local server. The next major step is to make this hosted URL available and compatible for administration on Prolific.

If you open a new study in Prolific, their interface is very user-friendly in this respect

1. In the section “How to record Prolific IDs,” paste in your Heroku room url

2. Select I'll use URL parameters

3. Change the url parameters in prolific from PROLIFIC_PID to participant_label accordingly if following this guide verbatim.

   • I kept participant_label because it passes in otree by default to participant.label, and I can’t be bothered to work out the translation

link provided through Prolific by default (do not use): https://your_heroku_app.herokuapp.com/room/your_prolific_study?PROLIFIC_PID={{%PROLIFIC_PID%}}

link used in this outline:

https://your_heroku_app.herokuapp.com/room/your_prolific_study?participant_label={{%PROLIFIC_PID%}}

If you are using a URL redirect for study completion, prolific will generate a new one for you.

4. Copy the generated URL and replace the input for completionlink in session_config

• E.g. https://app.prolific.co/submissions/complete?cc=1A1A1111

Testing prolific URL

After configuring your URL (assuming functioning and open Heroku app),

1. Save the draft study,

2. Preview it

3. Click on open study link

4. Click through until the page that records participant_label

5. In the admin page, check back on the room, and you should see in the recorded data (in this case, PROLIFIC_PID in prolific was passed to participant_label, which was then assigned to player.prolific_id)

Final Implementation

After you first deploy an otree app on Heroku, it will remain on the original oTree version upon deployment, even after redeploying, or restarting dynos, redis, and postgres.

Double checks

1. Password protect the admin. (prevents participants from accessing sensitive data) https://otree.readthedocs.io/en/latest/server/heroku.html#server-performance

2. Disable debug (set OTREE_PRODUCTION server-side).

Voila! you should be good to go; please use your new-found computer powers for good.

This started as a personal guide for my own quality assurance, so likely is missing information. Don’t hesitate to reach out or comment with any contributions.

Other Info

Other resources

• https://learnxinyminutes.com/docs/python/

• https://github.com/TiesdeKok/LearnPythonforResearch

• https://djangobook.com/course/introduction/