lab.js Experiment

lab.js (lab.js.org) is a JavaScript-based application used to conduct cognitive and behavioral science experiments through web browsers. The application allows for reaction time measurements, repetition of measurements, and randomization, among other features.

Experiments are built using the online platform lab.js builder (see lab.js documentation). The developer provides numerous examples in a repository, including among others a Balloon Analogue Risk Task, Flanker Task, N-Back Task, Paired Recall, Simon Task, Stroop Test, and Visual Search Task.

The finished experiment is exported as a ZIP file in the lab.js Builder (Export as integration → Generic survey tools) suitable for SoSci Survey. If you want to modify the experiment later, save the study as a JSON file via Save.

In SoSci Survey, create a new question of the “lab.js Experiment” type in a section of your choice. There, choose the ZIP file you downloaded before running “lab.js ZIP export”. Decide using the “Full Screen” parameter whether the experiment should be displayed within the questionnaire, whether the entire browser window, or the entire screen should be used.

Save the generated question () and drag it to a page in the questionnaire in Compose Questionnaire. In most cases, it is useful to not place any other elements (questions, texts) on the questionnaire page next to the lab.js question.

lab.js experiments yield extensive data in a tabular data format – essentially a dataset with variables and data rows for each experimental run. It is advisable to consider early on how to calculate the information needed from each specific particpant dataset.

Technically, SoSci Survey can store the data in two ways:

• As a text variable with the data encoded in JSON format. This option only works, if, after being JSON-encoded, the data size per experiment is less than 32 kB.
• The default is to download the data as separate files (one file per participant) using Collected Data → Download Uploaded Files.

Both options require substantial effort and knowledge in analysis of data. It is advisable to use advanced statistical software such as R to automate the reading and analysis of the experimental data.

There may be instances in which data from an interview needs to be passed to the lab.js experiment, such as the assignment to an experimental group or a participant identifier. This can be done by defining a corresponding JavaScript variable on the questionnaire page (JavaScript in the Questionnaire). These JavaScript variables can be accessed directly in the lab.js experiment.

Important: The HTML/JavaScript code should be inserted above the lab.js question on the same questionnaire page as the lab.js question.

The easiest way to define JavaScript variables is through the use of placeholders. In the following example, the predefined placeholders %caseNumber% and %caseSerial% are used, along with a third placeholder that is replaced with the contents of the variable “RG01”.

You can directly compose JavaScript code in Compose questionnaire by including an “HTML code” element. To define the additional placeholder an additional line of PHP code is required.

replace('%valRG01%', 'RG01', 'response');

Followed by an “HTML code” block with the following content.

<script type="text/javascript">
var caseNumber = %caseNumber%;
var caseSerial = "%caseSerial%";
var expGroup   = %valRG01%;
</script>

Note the quotation marks for caseSerial, which is a string, not an integer like in the other two cases.

If you are working with the PHP function html(), substrings can be concatenated using a dot (.). The PHP code would then look like this.

html(
  '<script type="text/javascript">
  var caseNumber = %caseNumber%;
  var caseSerial = "%caseSerial%";
  var expGroup   = '.value('RG01').';
  </script>'
);

The predefined placeholders operates in the same way as with “normal” HTML code. However, here the value of variable “RG01” is not inserted into the HTML code via a placeholder, but directly connected to the HTML code.

The HTML code can also be stored within a text in the questionnaire. To display the text as HTML code, choose “HTML-Code”. The content is identical to the first option above.

<script type="text/javascript">
var caseNumber = %caseNumber%;
var caseSerial = "%caseSerial%";
var expGroup   = %valRG01%;
</script>

The difference is that the placeholder is directly replaced by the parameter in the function show(). If the above text has the identifier “JS02”, it would be integrated as follows.

show('JS02', [
    '%valRG01%' => value('RG01')
]);