Admin

oTree’s admin interface lets you create, monitor, and export data from sessions.

Open your browser to http://localhost:8000/ or whatever you server’s URL is.

Password protection

When you first install oTree, The entire admin interface is accessible without a password. However, when you are ready to deploy to your audience, you should password protect the admin.

If you are launching an experiment and want visitors to only be able to play your app if you provided them with a start link, set the environment variable OTREE_AUTH_LEVEL to STUDY.

To put your site online in public demo mode where anybody can play a demo version of your game (but not access the full admin interface), set OTREE_AUTH_LEVEL to DEMO.

The normal admin username is “admin”. You should set your password in the OTREE_ADMIN_PASSWORD environment variable (on Heroku, log into your Heroku dashboard, and define it as a config var).

If you change the admin username or password, you need to reset the database.

Participant labels

Whether or not you’re using a room, you can append a participant_label parameter to each participant’s start URL to identify them, e.g. by name, ID number, or computer workstation. For example:

http://localhost:8000/room/my_room_name/?participant_label=John

oTree will record this participant label. It will be used to identify that participant in the oTree admin interface and the payments page, etc. You can also access it from your code as self.participant.label.

Another benefit of participant labels is that if the participant opens their start link twice, they will be assigned back to the same participant (if you are using a room-wide or session-wide URL). This reduces duplicate participation.

If you’re using Prolific, you can add participant_label={{%PROLIFIC_PID%}} to your study URL. When the user clicks the link, Prolific will replace that with the participant’s actual Prolific ID.

Arrival order

oTree will assign the first person who arrives to be P1, the second to be P2, etc., unless you are using single-use links.

Customizing the admin interface (admin reports)

You can add a custom tab to a session’s admin page with any content you want; for example:

  • A chart/graph with the game’s results
  • A custom payments page that is different from oTree’s built-in one

Here is a screenshot:

_images/admin-report.png

Here is a trivial example, where we add an admin report that displays a sorted list of payoffs for a given round.

First, define a method vars_for_admin_report on the Subsession. This works the same way as vars_for_template(). For example:

class Subsession(BaseSubsession):
    def vars_for_admin_report(self):
        payoffs = sorted([p.payoff for p in self.get_players()])
        return dict(payoffs=payoffs)

Then create an includable template admin_report.html in your app, and display whatever variables were passed in vars_for_admin_report:

{% load otree %}

<p>Here is the sorted list of payoffs in round {{ subsession.round_number }}</p>

<ul>
    {% for payoff in payoffs %}
        <li>{{ payoff }}</li>
    {% endfor %}
</ul>

Notes:

  • subsession, session, and Constants are passed to the template automatically.
  • admin_report.html does not need to use {% block %} or {% extends %} etc. The above example is valid as the full contents of admin_report.html.

If one or more apps in your session have an admin_report.html, your admin page will have a “Reports” tab. Use the menu to select the app and the round number, to see the report for that subsession.

Tip: if you are displaying the same chart in the admin report and participant pages, you can reuse admin_report.html in the participant template with an {% include %}, and pass the variables like this:

class Results(Page):

    def vars_for_template(self):
        return self.subsession.vars_for_admin_report()

Kiosk Mode

During a lab study you may want to restrict participants from doing things like:

  • Closing the browser window
  • Clicking the “back” button
  • Viewing the URL in the address bar

You can restrict these things with “kiosk mode”, a setting available in most web browsers. Consult your web browser’s documentation for information on how to enable kiosk mode.

Monitor sessions

The admin interface lets you monitor the live progress of your sessions.

Payments page

At the end of your session, you can open and print a page that lists all the participants and how much they should be paid.

Export Data

In the admin interface, click on “Data” to download your data as CSV or Excel.

There is also a data export for “page times”, which shows the exact time when users completed every page. Here is a Python script you can run that tabulates how much time is spent on each page. You can modify this script to calculate similar things, such as how much time each participant spends on wait pages in total.

Custom data exports

Note

New in oTree 3.0 (July 2020).

You can make your own custom data export for an app. In oTree Studio, go to the “Player” model and click on “custom_export” at the bottom. (If using a text editor, define the below function at the bottom of your models.py, not within a class.) The argument players is a queryset of all the players in the database. Use a yield for each row of data.

def custom_export(players):
    # header row
    yield ['session', 'participant_code', 'round_number', 'id_in_group', 'payoff']
    for p in players:
        yield [p.session.code, p.participant.code, p.round_number, p.id_in_group, p.payoff]

Once this function is defined, your custom data export will be available in the regular data export page.

If you are exporting some other data like an ExtraModel, do something like this:

def custom_export(players):
    for bid in Bid.objects.order_by('id'):
        player = bid.player
        participant = player.participant
        yield [participant.code, player.round_number, bid.amount]

Notes:

  • Since players is a QuerySet, you can call methods such as players.values_list(), players.filter(), etc.

Debug Info

When oTree runs in DEBUG mode (i.e. when the environment variable OTREE_PRODUCTION is not set), debug information is displayed on the bottom of all screens.