Run

From Lioness wiki
Jump to: navigation, search

Once you have completed testing your experiment, you can run your LIONESS experiment online. Here we describe the steps to collect data with participants recruited from Amazon Mechanical Turk. Before you run your experiment, it is useful to take a look at this paper discussing best practices and methodological details of conducting interactive experiments online.

Download your experiment

While testing your experiment, the software was built on the LIONESS Lab server. This server is for development purposes only. For conducting your online experiment, you need to put your LIONESS experiment on your own server. The first step to do this, is to download your experiment. In your LIONESS Lab page, click 'compile and test' and select 'download experiment'. Download experiment.png

The experimental pages will be downloaded as a .zip file. When you unzip this file, you will see a folder with mainly PHP files. These are the experimental pages (with names 'stage' followed by a number. Two files in this folder are of particular importance: credentials.php and sqlCode.sql. These files are for adding the credentials of your own server and setting up the tables underlying your experiment. We will get to these two files below.

Adjust your credentials

In the LIONESS experiment you downloaded from LIONESS Lab, located the file 'credentials.php'. In this file you have to set the username and password of your server. You also have to specify the name of the database you intend to use for your experiment (see below).

Credentials.png


Set up your server in a few simple steps

For running an interactive experiment it is a good idea to use a server with enough computational power to handle many connections and data traffic simultaneously. Such servers are widely available at low cost. Here we describe how to set up your own 'virtual server' using Google Cloud. You can use this service to rent a powerful server for the duration of your session, and take the server offline after the session is over. The costs of renting a virtual server for a typical session of around 2 hours will cost you only a tiny fraction of the amounts that participants will usually earn.

If you already have a server running and you know how to operate it, you can skip this section.

Virtual server

You do not need advanced technical skills to set up a virtual server. Bitnami has a user-friendly point-and-click interface to do this. Here we briefly run you through how to do this.

(1) Go to the bitnami website and create a free account.

(2) You receive an email from bitnami to confirm and activate your account.

(3) For your LIONESS experiment, you need to set up a so-called 'LAMP stack', which you can do here.

(4) Choose 'Launch in the cloud' by clicking the button.

Upload your LIONESS experiment to your server

Now your server has been set up, you can upload your LIONESS experiment to your server. To transfer the experiment to your server, you have to install an 'FTP application'. A decent (and free) option is FileZilla. Choose the FileZilla Client. When installing, stick to the default options.

Once FileZilla is installed, choose File... and then Site manager.

The screenshot below illustrates the settings you need: choose 'New site' and add the IP address of the virtual server in the Host field. You can find this IP address in bitnami. For Protocol, choose 'SFTP-SSH'.

FileZilla sm.png

Once you are logged in, create a new folder for your experiment (e.g. 'myExperiment'). Copy all LIONESS files into that folder.

Set up your database and LIONESS tables

  • On your server, log into your administrator environment (e.g. phpMyAdmin or adminer). The below example assumes you use adminer.php, but for phpMyAdmin it works very similarly.
  • Create a new database by clicking Create new database on the top of the page. Give it the name of your experiment and save (e.g. 'myExperiment'). The database name needs to correspond to the database name you set in 'credentials.php' (see above).

  • CreateDB.png

  • In 'credentials.php', the HOST should be set to 'localhost', and the ADMIN to 'root'. The DBNAME should correspond to the database you just created (e.g. 'myExperiment'). The PASSW (password) should match that of the server you created. You can find this password in the bitnami launchpad.

  • PasswordLaunchpad.png


  • Set up the tables by clicking Import and select the file sqlCode.sql.

  • ImportSQL.png

  • After selecting this file, click the Execute button to define the structure of the database. This structure ensures that the data produced by the participants in the experiment will be saved in the appropriate place. If all went well, you should now see the the following tables in your database: core, decisions, globals, logEvents, and session.
  • ResultSQL.png


    Your experiment is now ready to run. You can go to the Control Panel through the address http://[your server name]/[your experiment name]/_beginControl.php (so, for example http://myServer/myExperiment/_beginControl.php).

    Recruit participants

    If you have access to an established laboratory participant pool (e.g. through your research institute), you may be able to recruit your participants for your LIONESS experiment from there. Alternatively, there are several crowd-sourcing platforms available to recruit participants for online experiments. Here we describe how to recruit participants from Amazon Mechanical Turk (AMT). A description for Prolific Academic will be added soon.

    Setting up a HIT on Amazon Mechanical Turk

    Once you logged into your AMT account, click on the tab Create and then choose New project. Among the options displayed, you might want to use Survey Link. This type of project will allow you to request a code for the task to be paid. Hence, participants in your study will complete their task, see a unique code at the end of your LIONESS experiment and then enter it as a code in this type of survey.

    Select Create Project and fill in the required details for the tab Properties as you like (title, description, reward per assignment, etc). Select Design Layout (shown below). In this page edit the content that you want your participants to see, usually the title and description you already used in the previous tab will be enough.

    Once you are done with the edition, press Source and search for the two instances where “http://www.linktomysurvey.com” appears. Replace these with the link to your LIONESS experiment. You can find the link in the control panel under 'address for participants'. Press Source again, and finally click on Preview. If you are happy with the way your task looks, press Finish.

    General pointers for writing a HIT description can be found here. Make sure you have the control panel of your experiment open when you publish your HIT.

    Monitor your experiment

    During a session you can monitor your experiment using the Control panel. This allow you to track the session's progress, and browse through all data associated with the session (parameter settings, participants' decisions, etc).

    End of a session

    At the end of a session, you can download all data as an Excel file by clicking the button 'Export database'. This will download the database of the experiment in Excel format. The first five tabs correspond to the five tables underlying your experiment. The most informative table for the data analysis will often be the 'decisions' table.

    Pay your participants

    Participation fees can be paid by approving the HITs on MTurk. Typical experiments will have payments that depend on the performance of participants. You can assign bonuses to each participant using Amazon's Command Line Tools (CLT). Click here to get the CLT running on your system. To do this, follow these steps:

  • On MTurk, download and open ‘Batch results file’
  • Copy all its contents to the clipboard
  • Open the LIONESS results file in Excel and paste the data to cell A1 of the tab ‘batchResults’. The Excel file will automatically link the LIONESS code and its earnings to the MTurk worker ID of the participant.
  • The tab ‘paymentsMTurk’ then contains the ready-made codes you can use in MTurk Command Line Tools.
  • Double-check if the bonus amounts in the column ‘bonus’ are correct
  • Add a description explaining participants why they earned this bonus and copy that into all rows of that column
  • The column 'MTurkPaymentToolsCode' will contain a list of codes that can you can paste into CLT

  • CLT screenshot.png

    Tips and tricks

    The MTurk HIT will include a link to the LIONESS experiment. You can have the participants complete the experiment in a new window, in which you disable the navigation bar. You can add this piece of code to the link:

    function width() { return window.innerWidth || document.documentElement.clientWidth || document.body.clientWidth || 0; } function height() { return window.innerHeight || document.documentElement.clientHeight || document.body.clientHeight || 0; }

    var w = width() * 0.9; var h = height() * 0.9; window.open(url, 'LIONESSwindow', "resizable=no,location=no,toolbar=no,scrollbars=yes,menubar=no,status=no,directories=n o,width=" + w + ",height=" + h + ",left=" + w * 0.1 + ",top=" + h * 0.1 + "");