psiTurk API

Everything in the psiTurk API is scoped under the psiturk namespace.

Creating the psiTurk object

To use the psiTurk library, a psiturk object must be created at the beginning of your experiment.

// Create the psiturk object
var psiturk = PsiTurk();

// Add some data and save
psiturk.addUnstructuredData('age', 24)
psiturk.saveData();

psiturk.taskdata

taskdata is a Backbone model used to store all data generated by a participant and to sync it to the database.

taskdata has the following fields with these default values:

condition: 0
counterbalance: 0
assignmentId: 0
workerId: 0
hitId: 0,
useragent: ""
currenttrial: 0
data: ""
questiondata: {}
eventdata: []

These variables are either set during initialization or using the methods of the psiturk object. However, since taskdata is a Backbone model, you can always access their values directly using the Backbone set and get methods, which may be useful for debugging. For example:

psiturk.taskdata.set('condition', 2)
psiturk.taskdata.get('condition')

psiturk.preloadPages(pagelist)

For each path in pagelist, this will request the html and store in the psiturk object. A given page can then be loaded later using psiturk.getPage(pagename).

Example:

// Preload a set of HTML files
psiturk.preLoadPages(['instructions.html', 'block1.html', 'block2.html'])

// Set the content of the body tag to one of the pages
$('body').html(psiturk.getPage('block1.html'))

psiturk.getPage(pagename)

Retrieve a stored HTML object that has been preloaded using psiturk.preLoadPages.

psiturk.showPage(pagename)

Set the BODY content using an HTML object that has been preloaded using psiturk.preloadPages.

Example:

psiturk.preloadPages(['instructions.html', 'block1.html', 'block2.html');

psiturk.showPage('instructions.html');

psiturk.preloadImages(imagelist)

Cache each image in imagelist for use later.

psiturk.recordTrialData(datalist)

Add a single line of data (a list with any number of entries and any type) to the psiturk object. Using this will not save this data to the server, for that you must still call psiturk.saveData().

Example:

// data comprised of some list of variables of varying types
data = ['output', condition, trialnumber, response, rt]
psiturk.recordTrialData(data)

psiturk.recordUnstructuredData(field, value)

Add a (field, value) pair to the list of unstructured data in the task data object.

Example:

psiturk.recordUnstructuredData('age', 24)

psiturk.savedata([callbacks])

Sync the current psiTurk task data to the database.

An optional argument callbacks can provide functions to run upon success or failure of the saving.

psiturk.saveData({
   success: function() { 
      // function to run if the data is saved
   },
   error: function() { 
      // function to run if there was an error
   }
});

psiturk.finishInstructions

finishInstructions is used to change the participant's status code to 2 in the database, indicating that they have begun the actual task.

In addition, this adds a beforeunload handler such that if people attempt to close (or reload) the page, they will get an alert asking them to confirm that they want to leave the experiment.

Example

psiturk = new PsiTurk()
...
psiturk.finishInstructions()

psiturk.teardownTask()

Removes the beforeunload handler that is set using psiturk.finishInstructions.