====== lab.js Experiment ======

lab.js ([[https://lab.js.org/|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 [[https://labjs.felixhenninger.com/|lab.js builder]] (see [[https://labjs.readthedocs.io/en/latest/|lab.js documentation]]). The developer provides numerous examples in a [[https://github.com/FelixHenninger/lab.js/tree/main/tasks|repository]], including among others a Balloon Analogue Risk Task, Flanker Task, N-Back Task, Paired Recall, Simon Task, Stroop Test, and Visual Search Task.


===== Application in SoSci Survey =====

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 ({{:button.save.png?nolink|Einstellungen speichern}}) 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.


===== Data Format =====

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.


===== Data transmission =====

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 ([[:en:create:javascript]]). 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 [[:en:create:placeholders|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".

==== Option: direct ====

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.

<code php>
replace('%valRG01%', 'RG01', 'response');
</code>

Followed by an "HTML code" block with the following content.

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

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


==== Option: html() ====

If you are working with the PHP function ''[[:en:create:functions:html]]'', substrings can be concatenated using a dot (''.''). The PHP code would then look like this.

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

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.


==== Option: Text block ====

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.

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

The difference is that the placeholder is directly replaced by the parameter in the function ''[[:en:create:functions:show|show()]]''. If the above text has the identifier "JS02", it would be integrated as follows.

<code php>
show('JS02', [
    '%valRG01%' => value('RG01')
]);
</code>