From Lioness wiki
Jump to: navigation, search

There are two basic ways to develop your LIONESS experiment. You can either start from scratch, or build on an existing experiment. The repository contains a range of different LIONESS experiments for you to use and adjust to accommodate your requirements.

Develop your LIONESS experiment from scratch

Here we describe how to develop your LIONESS experiment from scratch. We describe how to create a new game and define your screens. Based on experience with conducting interactive experiments online, we also make suggestions for structuring your experiment.

Create experiment

On the LIONESS Lab landing page, you can create a new LIONESS experiment by clicking 'new experiment' in the top horizontal bar.

Create experiment.png

In the next screen you can define basic settings of your experiment by filling out the appropriate screens.

New game.png

With the drop-down menu under 'availability' you can choose to keep your experiment private, or to share it with other LIONESS Lab users by making it 'public'. Other users will be able to copy public experiments from the Repository to their LIONESS Lab accounts and edit these for their own purposes. Experiments' settings can be adjusted at any time.

With the input fields on the right you can give additional information on your experiment (e.g. you can use the comments section to list the number of sessions run with this experiment, or add any caveats you might have).

Defining your screens

As described in the tutorial, your screens consist of three sections: settings, an 'active screen' and a 'waiting screen'.

Stage settings (top panel)

In the top horizontal bar, you can give the stage a name, and define its type: (Standard, Quiz or Lobby). Also, you can add an optional timer.

Active screen (left panel)

The active screen is the main screen of a stage. Typically, this section will be used for displaying information (e.g. instructions, results from previous periods) and recording participants' responses.

You can build up these screens step-by-step using elements. You can add these elements by clicking the button 'add new element' and paste it in the place you want. On the participant screens, elements will in principle be placed below each other, in the order you define them in your LIONESS Lab screen. Typically, the final element of an active screen is a button, that submits any responses of the participant in that screen, and directs them to the next screen. In this button, you can also define whether the participants can move on to the next screen as soon as they have finished, or whether they have to wait for their groups mates to also finish this screen. In the latter case, participants will be directed to the Waiting screen of this stage (see below).

Waiting screen (right panel)

In case you allow participants to move to the next stage only when all group members have completed the stage (by setting the 'proceed' condition in the active screen button to 'wait for others'), participants will be directed to the Waiting screen of the stage.

You can add elements to the Waiting screen in the same way as you add them to the Active screen. If you do not define any element there, the Waiting screen will show a default text indicating that participants should wait for all group mates to complete.

Structuring your experiment

Based on running numerous experiments online, we suggest that LIONESS experiments follow a basic structure with the components in the order listed below. Each component may be one stage (as is the case in the tutorial), but can of course be expanded to include multiple stages. A methodological discussion of running interactive experiments online can be found in this paper.

Introduction / instructions

At the beginning of your experimental task, you have to tell the participants what is expected from them. Apart from explaining the task they are about to complete, this is a good place to inform them about the duration of the experiment, as well as the earnings they may expect. In addition, it is often useful to inform participants that they will only get paid if they complete the task until the end.


One big difference between online sessions and sessions in the laboratory is that you, as an experimenter, are not physically present. This means that participants cannot ask any questions. To ensure that participants understand their instructions, it is useful to introduce a set of compulsory comprehension questions, before they proceed to the lobby. You can make responses to input elements compulsory by clicking the 'required' switch inside the element. You can set a target value for an input element in the parameter field 'correct value'.

For each participant, LIONESS experiments will automatically record the number of attempts for each quiz item. This is stored in the 'session' table.


To reduce waiting times as much as possible, you can place the lobby after the comprehension questions. This ensures that participants in the lobby understand the game and are matched as soon as sufficient participants are ready to start interacting. By default, the lobby will display the number of participants are necessary to form a group.

Experimenters can choose 3 types of matching:

  1. First come, first serve. As soon as sufficiently many participants are in the lobby, a group will be formed.
  2. Before the lobby, experimenters can assign different 'roles' to players (using the variable 'role' in the 'core' table). The other two available types of matching make use of this variable 'role' to form groups.

  3. Groups with unique roles. As soon as at least 1 participant with each role 1...n is present (where n is the group size), a group will be formed.
  4. Group with the same role. Groups are formed of participants with the same role. This is useful when you have different treatments in the same session, and participants from the same treatment need to be grouped together.


As soon as participants are matched, the first period begins. Typically, participants progress through the experiment at the speed of the slowest member of a group. In many cases it will be useful use countdown timers to make sure that the participants do not have to wait too long, and that non-responsive participants are booted out of the session.


Once all group members have made their decisions in a period, you typically want to show results. You can retrieve decisions from the database with JavaScript and display these in text boxes. If this is the last stage of a peirod, participants will be directed to a waiting screen and pushed on to the next period once all group members are finished viewing the results. Also for stages displaying results, it is often useful to add countdown timers to keep up the pace of a session.


Once the periods of interaction are over, you may want to record some information about the participants. Common items include age, gender and questions on social and economic status. It can also be useful to ask participants about their prior experience with tasks similar to yours.

Final earnings

Once participants have finalized the experiment, you can show them their final earnings. In a typical experiment, you can store a participant's earnings for each period in a variable in the decisions table. For example, you may store them in a variable called 'payoffThisPeriod'. In the final earnings screen, you can then sum the participant's earnings with the following code:

 totalEarnings = 0;
 for (var i=1; i<=numberPeriods; i+){
   totalEarnings += getFloat('decisions', 'playerNr=' + playerNr + ' and period=' + i, 'payoffThisPeriod');

Note that JavaScript is evaluated in the participants' browsers. This means that you have to make sure that payoffs are calculated in a way that is 'refresh-safe' (that is, if participants refresh their page, payoffs should not change). It is therefore advisable to calculate payoffs anew from a 'final earnings' page (i.e. sum up over all rounds starting from 0). With the function 'setBonus()', the bonus earnings of the participant is written to the 'session' table. It is then used for automatic payment later.

For linking participants' earnings to their IDs in crowdsourcing platforms (where participants are typically recruited from), the final stage of your experiment should also have a random ID. LIONESS Lab has available a unique random code for each participant in the session table. In the JS code, you can retrieve this random code with the following line:

 randomID = getInt('session', 'playerNr='+playerNr, 'randomid');

Subsequently, you can display this ID to the participant screen in the usual way by using the dollar signs. You can prompt the participants to fill out this code on the crowdsourcing website to arrange their payment.

Setting parameters

For testing (and running) your experiment, you need to set the experiment parameters. Make sure that the loopStart and loopEnd parameters are set to the stages that mark the beginning and end of a period, respectively.

Build on an existing experiment

Go to the Repository and import an existing experiment. Any experiment that was made public can is shared with, and can be imported by, other experimenters. After importing an experiment it will be visible in your landing page with the overview of your experiments. If you want to the imported experiment, you have to make a copy of it. To do this, click 'View' next to the experiment on your landing page. In the experiment's page, you will see you cannot edit the experiment as it was created by another user. Click 'experiment' in the top bar, and then 'copy experiment'. An editable copy of the experiment will be created in your account.