Home

LambdaExpt is a framework for running Psychology Experiments on Amazon Web Services Lambdas. These lambdas allow us to both run experiments cheaply and at scale. This framework has been developed by the Complex Human Data Hub at the University of Melbourne. It can be used to run individual experiments, experiments on Mechanical Turk, and Research For Experience (REP) experiments.

Getting the LambdaExpt code

To get started download the code from github. You can download the code as a zip file: https://github.com/complex-human-data-hub/LambdaExpt/archive/master.zip

Or install the git program (instructions here) and use it to download the LambdaExpt code: https://github.com/complex-human-data-hub/LambdaExpt.git

Setting up you computer to run the LambdaExpt code

To get the code running on your system will vary slight between different operating systems (Windows, Mac, Linux). In general these are the steps that you will need to follow:

In the LambdaExpt directory (folder) you will need to install a Python3 virtual environment:

On Windows, Mac or Linux:
```
 python3 -m venv venv
```

NOTE: You will need to have Python3 installed to complete this step, instructions here.

A virtual environment is just a copy of the Python 3 program and the files need to run it, that live a directory that you specify, in this case LambdaExpt/venv. Using a Python3 virtual environment means that we do not mess with your operating systems version of python (that other programs use too).

Next you need to activate the virtual environment.

On Windows:
```
 venv\Scripts\activate
```
On Mac or Linux:
```
 source venv/bin/activate
```
Install the extra python requirements (supporting code) that LambdaExpt needs. You can do this easily with Python's pip package installer. You should be in the LambdaExpt directory and have activated the python3 virtual environment (step 2 above). Then use pip to install the extra requirements:
```
 pip install -r requirements.txt
```

Running an experiment on your computer

When creating a LambdaExpt you can run it locally on your computer. This is means you can get things setup and running the way you want them to before publishing it online for the world to see.

LambdaExpt comes with a demo experiment loaded already. So, you should be able to run that straight away.

To run the demo (or any other experiment) locally do the following:

Make sure your Python3 virtual environment is active (as described above)
Issue the following command to run the experiment locally:
```
 FLASK_APP=experiment.py flask run
```
If this does not work, try:
```
 python experiment.py
```

You should now be able to access you experiment using the browser on this URL:

 [http://localhost:5000/unique-expt](http://localhost:5000/unique-expt)

On Mac you may need to use this URL in you browser:

 [http://127.0.0.1:5000/unique-expt](http://127.0.0.1:5000/unique-expt)

How to create your own experiment

LambdaExpt uses a python library called Flask to create a server that can run your experiment both locally on your computer and online. That is, Flask will serve your html and javascript (jsPsych) code to your browser. That is why we use this flask command to run your experiment locally:

FLASK_APP=experiment.py flask run

NOTE: After making any changes to the files below you will need to restart the server. This can be done by pressing CTRL-C to exit (Mac users may need to use "CTRL + ."), and then running the code above again to restart the server.

There are two main files that you can edit to get your own experiment up and running.

1. templates/exp.html

This is where you will put your jsPsych code.

Importing jsPsych plugins

jsPsych uses various plugins to create items on your experiments timeline. You need to link this to your experiment. At the top of templates/exp.html you'll see some jinja2 code that creates these links in your exp.html file. These files that contain these jsPsych plugins are stored in static files directory:

LambdaExpt/static/jspsych/plugins

If you need the jsPsych html-keyboard-response plugin, then you need to add it to the top of the templates/exp.html file:

<script src="{{url_for('static', filename='jspsych/plugins/jspsych-html-keyboard-response.js')}}" type="text/javascript"></script>

NOTE: The code between the curly brackets ({{ ... }}) is the jinja2 code. It is telling python to write the url for the static directory, and to add the filename 'jspsych/plugins/jspsych-html-keyboard-response.js' to that static directory, which will create the link: http://localhost:5000/static/jspsych/plugins/jspsych-html-keyboard-response.js

jsPsych code

Your jsPsych code will run the experiment in the browser. Add your jsPsych code between the script tags in the templates/exp.html code:

<script>
... 
</script>

2. expt_config.py

In this file you can define a function called get_data() to provide your javascript code with any experimental stimuli you might want to load. For example, in the demo experiment's expt_config.py file the get_data function creates and returns two word lists for a recognition memory study.

def get_data(opts):
    # Setup experiment tasks
    word_list = fetch_word_list()

    #Set document order
    study_document_order = list(range(3)) # 8 Documents (3 in lorem)
    shuffle(study_document_order)

    #Create Study List
    study_list = get_word_list(word_list, study_list_length)
    test_list = get_word_list(word_list, test_list_length, study_list)
    return {
        'study_list': study_list,
        'test_list': test_list,
        'study_document_order': study_document_order
    }

This data is passed as a dictionary to the "frontend" javascript code contained in templates/exp.html. In templates/exp.html we initialise that data here:

<script>
    var expt_data = {{data|safe}};

Passing Parameters from the browser to the get_data() function.

Sometime it is convenient to pass some values in the URL to the backend python code. For example, you might want to assign participants to a particular condition. We can pass this value to get_data in the experimental URL:

http://localhost:5000/unique-expt?condition=A

And then we can retrieve the condition variable from opts in get_data:

def get_data(opts):  
    condition = opts.get('condition')  # A

Static directory

The static directory contains resources (files) such as images, audio files and jsPsych plugins. As mentioned above you can access these file from templates/exp.html using jinja2 url_for function.

<script src="{{url_for('static', filename='images/logo.png')}}" type="text/javascript"></script>

Adding custom routes (url paths)

In config_expt.py we can add custom routes which are created using Flask's Blueprint function. For example, we may wish to send the participant to a debriefing page. To do this we had a custom route to the expt_config file like this:

@custom_code.route('/full-debrief', methods=['get'])
def full_debrief():
    return render_template(
        'debrief-long.html'
        )

We would also need to add the file debrief-long.html to the templates directory. Similar to templates/exp.html, the templates/debrief-long.html file you create can contain html, javascript and jinja2 code. Now when participant are sent to:

http://localhost:5000/full-debrief

The will be served the code contained in templates/debrief-long.html

Automatic crediting of SONA experiments

It is possible to automatically credit participants for completing experiments. When creating an study in the SONA console, choose Online External Study:

Choose Online External Study when creating an online SONA study

In the SONA study settings you need to:

Select "Yes" to allow survey participants to be indentified by a random, unique ID code.
Give the study URL with the %survey_code% template
Select "Yes" to the Study URL Display question

![SONA Settings]( Serverside Completion URL location in SONA study

Server-side completion URL location in SONA Study

After you have created your SONA experiment you will need to add the server-side completion URL to config.py, make sure to replace XXXX with "{}". We will use pythons format command to insert the participants survey_code into this completion URL when the time comes to automatically credit their participation.

On the SONA study page you can find the server-side completion URL here: