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

lab.js ([[https://lab.js.org/|lab.js.org]]) ist eine JavaScript-basierte Anwendung, um kognitive und verhaltenswissenschaftliche Experiment mittels Internetbrowser durchzuführen. Die Anwendung erlaubt u.a. Reaktionszeitmessungen, Messwiederholungen, Randomisierung.

Die Experimente werden mittels der Online-Plattform [[https://labjs.felixhenninger.com/|lab.js Builder]] gebaut (siehe [[https://labjs.readthedocs.io/en/latest/|lab.js Dokumentation]]). Der Entwickler stellt in einem [[https://github.com/FelixHenninger/lab.js/tree/main/tasks|Repository]] zahlreiche Beispiele zur Verfügung, u.a. eine Balloon Analogue Risk Aufgabe, Flanker Aufgabe, N-back Aufgabe, Paired recall, Simon Aufgabe, Stroop-Test, Visuelle Suchaufgabe.


===== Verwendung in SoSci Survey =====

Das fertige Experiment wird im //lab.js Builder// als ZIP-Datei für SoSci Survey exportiert (//Export as integration// -> //Generic survey tools//). Vergessen Sie nicht, die Studie auch via //Save// als JSON-Datei zu speichern, damit Sie später noch Änderungen vornehmen können.

In SoSci Survey erstellen Sie in einer Rubrik Ihrer Wahl eine neue Frage vom Typ "lab.js Experiment". Dort wählen Sie bei "lab.js ZIP-Export" zunächst die ZIP-Datei, die Sie vorher heruntergeladen haben. Entscheiden Sie außerdem mit dem "Vollbild" Parameter, ob das Experiment optisch innerhalb des Fragebogens angezeigt werden soll, ob das gesamte Browserfenster oder der gesamte Bildschirm genutzt werden soll.

Speichern Sie die Frage ({{:button.save.png?nolink|Einstellungen speichern}}) und ziehen Sie sie anschließend unter **Fragebogen zusammenstellen** auf eine Seite im Fragebogen. In den meisten Fällen ist es sinnvoll, neben der lab.js Frage keine anderen Elemente (Fragen, Texte) auf der Fragebogen-Seite zu platzieren.


===== Datenformat =====

lab.js Experimente liefern umfangreiche Daten in einem tabellarischen Datenformat -- also gewissermaßen ein Datensatz mit Variablen und Datenzeilen für jede Versuchsdurchführung. Es ist sinnvoll, sich frühzeitig damit auseinanderzusetzen, wie man aus diesem Datensatz-pro-Teilnehmer:in am Ende die Kennwerte berechnet, die man pro Teilnehmer:in benötigt.

Technisch kann SoSci Survey die Daten des Experiments auf zwei Arten abspeichern:

  * Entweder als Textvariable innerhalb des regulären Datensatzes, wobei die Daten im JSON-Format kodiert werden. Diese Variante funktioniert __nur__, wenn die JSON-kodierte Datenmenge pro Experiment geringer als 32 kB liegt.
  * Oder als separate Dateien (eine Datei pro Teilnehmer:in), welche dann unter **Erhobene Daten** -> **Hochgeladene Dateien** heruntergeladen werden können. Dies ist die Standard-Einstellung.

Beide Varianten erfordern in der Auswertung einigen Aufwand. Es ist sinnvoll, eine fortgeschrittene Statistiksoftwore wie z.B. //R// zu verwenden, um das Einlesen und die Auswertung der Experimentaldaten zu automatisieren.


===== Daten übergeben =====

Es kommt vor, dass Daten aus dem Interview an das lab.js Experiment übergeben werden müssen. Zum Beispiel die Zuordnung zu einer Experimentalgruppe oder eine Personenkennung. Dies funktioniert, indem man auf der Fragebogen-Seite eine entsprechende JavaScript-Variable definiert ([[:de:create:javascript]]). Im lab.js Experiment kann man auf diese JavaScript-Variablen direkt zugreifen.

**Wichtig:** Der HTML-/JavaScript-Code sollte über der lab.js-Frage auf derselben Fragebogen-Seite wie die lab.js-Frage eingefügt werden.

Am einfachsten ist die Definition der JavaScript-Variablen mittels [[:de:create:placeholders|Platzhaltern]] möglich. Im folgenden Beispiel werden die vordefinierten Platzhalter ''%caseNumber%'' und ''%caseSerial%'' verwendet und ein dritter Platzhalter, welcher durch den Inhalt der Variable "RG01" ersetzt wird.

==== Variante: direkt ====

Sie können JavaScript-Code direkt unter **Fragebogen zusammenstellen** über ein Element "HTML-Code" einbinden. Für die Definition des zusätzlichen Platzhalters ist darüber noch eine Zeile PHP-Code erforderlich.

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

Darunter folgt ein "HTML-Code" Baustein mit folgendem Inhalt.

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

Beachten Sie die Anführungszeichen für ''caseSerial'', weil es sich dabei um einen String handelt, nicht um eine Zahl wie in den anderen beiden Fällen.


==== Variante: html() ====

Wenn man mit der PHP-Funktion ''[[:de:create:functions:html]]'' arbeitet, kann man die Teilstrings durch einen Punk (''.'') verknüpfen. Der PHP-Code würde dann wie folgt aussehen.

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

Die vordefinierten Platzhalter funktionieren genauso wie im "normalen" HTML-Code. Aber hier wird der Wert ver Variable "RG01" nichts mittels Platzhlater in den HTML-Code eingefügt, sondern direkt mit dem HTML-Code verbunden.


==== Variante: Textbaustein ====

Der HTML-Code kann auch in einem Text innerhalb des Fragenkatalogs gespeichert werden. Als //Darstellung// für den Text muss "HTML-Code" gewählt werden. Der Inhalt ist identisch mit der ersten Variante oben.

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

Der Unterschied besteht darin, dass der Platzhalter direkt mittels Parameter in der Funktion ''[[:de:create:functions:show|show()]]'' ersetzt wird. Wenn er obige Text die Kennung "JS02" trägt, würde er wie folgt eingebunden.

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