Bevor Sie beginnen

Wenn Sie noch nie mit HTML oder JavaScript gearbeitet haben und nicht viel über Programmierung wissen, können Sie sich die Folien unseres ersten jsPsych-Workshops anschauen Teil 1, Teil 2, Gitlab repo. Die Folien enthalten einen kurzen Crashkurs zu JavaScript. Dieses Tutorial geht davon aus, dass Sie zumindest die grundlegendsten Kenntnisse haben, wie zum Beispiel die Definition von Variablen und die Arbeit mit Strings und Arrays.

Die Folien unserer beiden jsPsych-Workshops bieten eine Menge Informationen, nicht alles davon wird in diesem Tutorial enthalten sein. Wenn Sie also nach mehr Details suchen, finden Sie diese vielleicht dort.

Erste Schritte

Öffnen Sie Ihren gewünschten Code-Editor (z.B. Visual Studio Code), erstellen Sie eine HTML-Datei und fügen Sie Folgendes hinzu:


                                        <!DOCTYPE html> 

                                        <html> 

                                            <head>  

                                                <title>jsPsych experiment template</title>  

                                                <script src="https://unpkg.com/jspsych@8.2.1"></script>  

                                                <link href="https://unpkg.com/jspsych@8.2.1/css/jspsych.css" rel="stylesheet" type="text/css" /> 

                                                <!-- Add any plugins you want to use here --> 

                                            </head> 

                                            <body></body> 

                                            <script> 

                                                const jsPsych = initJsPsych(); 

                                                const timeline = [];  
 


                                                // Add your code here. 
 


                                                jsPsych.run(timeline); 

                                            </script> 

                                        </html>

Benutzen Sie gerne diese Vorlage.

Initialisierung von jsPsych

Das Erste, was in jedem jsPsych-Experiment gemacht werden muss, ist die Initialisierung von jsPsych. Dies geschieht, indem Sie `const jsPsych = initJsPsych();` als erste Zeile des `<script>`-Abschnitts hinzufügen. Dies ist bereits in der obigen Vorlage enthalten.

Innerhalb der Klammern von `initJsPsych()` können Sie auch allgemeinere Dinge definieren, wie zum Beispiel, wohin die Daten am Ende des Experiments gesendet werden sollen. Um anzugeben, was nach dem Experiment passieren soll, fügen Sie den Parameter `on_finish` hinzu. Um die gesammelten Daten nach dem Experiment anzuzeigen, verwenden Sie die Funktion `jsPsych.data.displayData()`. Die Daten werden direkt in Ihrem Browser angezeigt und sind standardmäßig im JSON-Format. Das ist großartig für Tests, da es ermöglicht, die gesammelten Daten ohne Speichern zu sehen, sollte jedoch im Allgemeinen vor der Bereitstellung des Experiments entfernt werden.


                                        // initialize jsPsych 

                                        const jsPsych = initJsPsych({ 

                                            on_finish: function() {  

                                                // display collected data after the experiment 

                                                jsPsych.data.displayData();  

                                            } 

                                        });

Die Zeitstrahl

Wie bei anderen Software zur Erstellung von Experimenten, verwendet jsPsych einen Zeitstrahl, um die Reihenfolge der Ereignisse im Experiment zu bestimmen. In jsPsych nimmt dieser Zeitstrahl die Form eines Arrays von Objekten an. Der Zeitstrahl wird üblicherweise 'timeline' genannt und direkt nach der Initialisierung von jsPsych durch `const timeline = [];` erstellt (ist auch in der obigen Vorlage enthalten).

Grundsätzlich sieht das Experiment an diesem Punkt so aus:

Trials

Was Sie bisher erstellt haben, ist im Grunde ein Experiment ohne Inhalt. Um es mit Inhalt zu füllen, müssen Sie 'Trials' erstellen. Ein Trial in jsPsych ist ein Block von Inhalt, sei es eine Reihe von Anweisungen, Feedback oder ein experimenteller Versuch. Diese Versuche bestehen aus einem Objekt, gekennzeichnet durch geschweifte Klammern, mit Parametern, die einer Variablen zugewiesen werden. In der Praxis kann ein Trial so aussehen:


                                        const instructions = { 

                                            type: jsPsychHtmlKeyboardResponse, 

                                            stimulus: 'Please press any key.' 

                                        };

Der genaue Name, der für den Parameter `type` benötigt wird, besteht normalerweise aus 'jsPsych' plus dem Namen des Plugins in Kamelnotation und kann in der Dokumentation

Die Dokumentation für jedes Plugin enthält auch eine Liste der verwendbaren Parameter. Im obigen Beispiel nimmt der Parameter `stimulus` Text auf, der als HTML auf dem Bildschirm im Experiment angezeigt wird.

>***WICHTIG!*** Jedes Mal, wenn Sie ein neues Plugin im Experiment verwenden, muss dieses Plugin im `<head>` enthalten sein. Andernfalls weiß jsPsych nicht, was es mit diesem Versuch anfangen soll und wenn Sie das Experiment ausführen, zeigt die Konsole des Browsers einen Fehler wie diesen an:

Was Sie schreiben müssen, um ein Plugin einzubeziehen, kann in der Dokumentation jedes Plugins unter 'Install' gefunden werden. Im Fall des HtmlKeyboardResponse-Plugins müssen Sie Folgendes hinzufügen:


                                        <script src="https://unpkg.com/@jspsych/plugin-html-keyboard-response@2.1.0"></script>

Mit den Ergänzungen sieht die Vorlage nun so aus:


                                        <!DOCTYPE html>

                                        <html>

                                            <head>

                                                <title>jsPsych experiment template</title>

                                                <script src="https://unpkg.com/jspsych@8.2.1"></script>

                                                <link href="https://unpkg.com/jspsych@8.2.1/css/jspsych.css" rel="stylesheet" type="text/css" />

                                                <!-- Add any plugins you want to use here -->

                                                <script src="https://unpkg.com/@jspsych/plugin-html-keyboard-response@2.1.0"></script>

                                            </head>

                                            <body></body>

                                            <script>

                                                const jsPsych = initJsPsych();

                                                const timeline = [];

                                                

                                                // Add your code here.

                                                const instructions = {

                                                    type: jsPsychHtmlKeyboardResponse,

                                                    stimulus: 'Please press any key.'

                                                };

                                                

                                                jsPsych.run(timeline);

                                            </script>

                                        </html>

Trials zur Timeline hinzufügen

Obwohl es nun ein Trial im Experiment gibt, erscheint es nicht, wenn Sie das Experiment ausführen. Das liegt daran, dass es noch nicht auf der Timeline ist. Um Trials auf der Timeline zu setzen, müssen sie mit der `.push()`-Methode darauf geschoben werden.

Um den 'Anweisungen'-Versuch von vorhin auf der Timeline zu setzen, würden Sie Folgendes schreiben:


                                        timeline.push(instructions)

Es spielt keine Rolle, wo Sie die Anweisung im Code platzieren, solange sie nach der Definition des Trials und vor der Ausführung des Trials steht. Was wichtig ist, ist die Reihenfolge der verschiedenen push-Anweisungen; ein Versuch wird immer am Ende der Timeline geschoben, daher müssen Sie sie in der richtigen Reihenfolge setzen. Es ist oft am einfachsten, zunächst alle Ihre Trials zu definieren und dann alle push-Anweisungen danach zu setzen; so können Sie sie leicht ordnen und neu ordnen und es ist einfacher, sie im Auge zu behalten.

Zeitstrahl ausführen

Um den Zeitstrahl tatsächlich auszuführen, wenn das Experiment geöffnet wird, muss am Ende Ihres `<script>` eine `jsPsych.run(timeline);`-Anweisung stehen. Dies ist bereits in der obigen Vorlage enthalten.

Versuchsschleifen

Wenn Sie ein Experiment erstellen, haben Sie normalerweise experimentelle Elemente, die alle auf die gleiche Weise präsentiert werden müssen. Es wäre ineffizient, für jedes Element einen separaten Versuch zu erstellen. Um die Dinge einfacher zu machen, können Sie eine einfache experimentelle Schleife erstellen, die über eine Liste Ihrer Elemente iteriert und jedes Element auf die gleiche Weise dem Teilnehmer präsentiert.

Um eine solche Schleife in jsPsych zu erstellen, erstellen Sie im Wesentlichen einen internen Zeitstrahl und geben Sie eine Liste von Zeitstrahlvariablen an, über die iteriert werden soll. In jsPsych könnte es so aussehen:

`timeline_variables` gibt die Liste der Stimuli an, über die iteriert werden soll.
`timeline` nimmt ein Array von Versuchen auf, die bei jeder Iteration ausgeführt werden.
`randomize_order` bestimmt, ob die Elemente in der Reihenfolge präsentiert werden, in der sie in der Liste erscheinen, oder zufällig.
`repetitions` bestimmt, wie oft die gesamte Liste von Elementen wiederholt wird.

Damit der Versuchsblock funktioniert, benötigt das Experiment auch die Versuche `fixation` und `trial`:

`fixation` zeigt ein einfaches Fixationskreuz mit dem jsPsychHtmlKeyboardResponse-Plugin an.
`trial` verwendet ebenfalls das jsPsychHtmlKeyboardResponse-Plugin, um den aktuellen Stimulus anzuzeigen. Um auf die aktuelle Zeitstrahlvariable zuzugreifen, verwenden Sie `jsPsych.timelineVariable()`.

Sie können Folgendes zu Ihrem Template-Experiment hinzufügen:


                                        const fixation = {

                                            type: jsPsychHtmlKeyboardResponse,

                                            stimulus: '<tt style="font-size:4em";>+</tt>',

                                            choices: "NO_KEYS",

                                            trial_duration: 395,

                                            record_data: false

                                        };
                                        


                                        const trial = {

                                            type: jsPsychHtmlKeyboardResponse,

                                            stimulus: jsPsych.timelineVariable('target'),

                                            choices: ['f', 'j'],

                                            trial_duration: 1500,

                                            post_trial_gap: 395

                                        };
                                        


                                        const trial_block_1 = {

                                            timeline: [fixation, trial],

                                            timeline_variables: test_stimuli,

                                            randomize_order: false,

                                            repetitions: 1

                                        };

`fixation` und `trial` verwenden beide einige weitere Parameter:

`choices` bestimmt, welche Tastendrücke als Antwort akzeptiert werden; alle anderen Tastendrücke werden ignoriert. Es nimmt einen einzelnen Tastennamen oder ein Array von Tastennamen auf (eine Liste von Namen finden Sie hier . Wenn es weggelassen wird, werden alle Tasten akzeptiert. 'NO_KEYS' bedeutet, dass es keine gültigen Tastendrücke gibt und der Versuch bis zum Ende der Versuchsdauer dauert.
`trial_duration` definiert, wie lange ein Versuch in Millisekunden dauert. Wenn nichts anderes angegeben ist, endet ein Versuch auch, wenn eine gültige Taste gedrückt wird.
`post_trial_gap` bestimmt, wie lange in Millisekunden gewartet wird, bevor der nächste Versuch beginnt.
`record_data` bestimmt, ob Daten aufgezeichnet werden sollen. Dieser Parameter ist standardmäßig `true` und muss nur für Versuche angegeben werden, von denen Sie keine Daten benötigen. Dieser Parameter wurde in jsPsych Version 8 hinzugefügt und funktioniert nicht in älteren Versionen.

Vergessen Sie nicht, `trial_block_1` auf den Zeitstrahl zu setzen:


                                        timeline.push(trial_block_1)

>***WICHTIG!*** In jsPsych Version 8 hat sich die Art und Weise, wie Sie Zeitstrahlvariablen aufrufen, ein wenig von älteren Versionen geändert. Wenn sie direkt in einem Versuch aufgerufen werden, wie im obigen Code, ändert sich nichts und Sie verwenden weiterhin `jsPsych.timelineVariable()`. Wenn Sie sie innerhalb einer Funktion aufrufen möchten (z. B. Sie verwenden eine Funktion, um Ihren Stimulus innerhalb des Parameters `stimulus` zu generieren), müssen Sie `jsPsych.evaluateTimelineVariable()` verwenden.

Elemente

Jetzt haben Sie eine experimentelle Schleife für Ihr Experiment, aber Sie fehlen noch Elemente, über die iteriert werden soll. Eine Elementliste in jsPsych ist ein Array von Objekten, das so aussehen kann:


                                        const test_stimuli = [

                                            { target: 'ORDAN', condition: 'pw', correct_response: 'j' },

                                            { target: 'NEFFE', condition: 'word', correct_response: 'f' },

                                            { target: 'KERZE', condition: 'word', correct_response: 'f' },

                                            { target: 'AMBIS', condition: 'pw', correct_response: 'j' }

                                        ];

Jedes Objekt in geschweiften Klammern stellt ein Element dar, das mehrere Eigenschaften haben kann (in diesem Fall `target`, `condition` und `correct_response`). Indem Sie `jsPsych.timelineVariable()` oder `jsPsych.evaluateTimelineVariable()` mit einer bestimmten Eigenschaft verwenden, kann der entsprechende Wert aufgerufen werden. Im vorherigen Beispiel wird die Eigenschaft `target` als Stimulus angezeigt, wodurch Ihnen 'ORDAN' in der ersten Iteration, 'NEFFE' in der zweiten usw. angezeigt wird. Setzen Sie `test_stimuli` vor den Versuchen in der Template-Experiment.

Daten

Wenn Sie das Experiment in einem Browser öffnen, sollte es nun ausgeführt werden und Sie werden aufgefordert, eine beliebige Taste zu drücken, bevor die vier Elemente angezeigt werden und mit der Anzeige der aufgezeichneten Daten im JSON-Format endet:

Die Reaktionszeit wird unter 'rt', der Stimulus unter 'stimulus' und die gedrückte Taste unter 'response' aufgezeichnet. Es gibt auch einige Informationen über das verwendete Plugin usw. Was nicht aufgezeichnet wird, sind die anderen Eigenschaften aus der Elementliste: 'condition' und 'correct_response'. Seit jsPsych Version 8 gibt es den Parameter `save_timeline_variables`: Wenn er auf true gesetzt wird, werden alle Zeitstrahlvariablen aufgezeichnet. Allerdings wird das gesamte Objekt gespeichert, was bedeutet, dass in einer CSV-Datei alles in den geschweiften Klammern als Objekt in der gleichen Spalte erscheint und in einer JSON-Datei wie folgt:

Je nachdem, wie Sie Ihre Daten analysieren möchten, mag dieses Format nicht ideal sein. Eine andere Möglichkeit, Daten aus Ihren Zeitstrahlvariablen zu speichern, ist die Verwendung des Parameters `data`:


                                        const trial = {

                                            type: jsPsychHtmlKeyboardResponse,

                                            stimulus: jsPsych.timelineVariable('target'),

                                            choices: ['f', 'j'],

                                            trial_duration: 1500,

                                            post_trial_gap: 395,

                                            data: {

                                                task: 'trial',

                                                target: jsPsych.timelineVariable('target'),

                                                condition: jsPsych.timelineVariable('condition'),

                                                correct_response: jsPsych.timelineVariable('correct_response')

                                            }

                                        };

Sie können entweder direkt Daten aufzeichnen, die Sie aufzeichnen möchten (`task: 'trial'`) oder Zeitstrahlvariablen aufrufen, um Daten aufzuzeichnen.

Der on_finish Parameter

Sie kennen `on_finish` bereits von Initialisierung von jsPsych , aber er kann auch zu normalen Versuchen hinzugefügt werden. Dies ist nützlich, wenn Sie beispielsweise die gesammelten Daten vor dem Weitergehen analysieren möchten. In der Praxis wird dies oft verwendet, um zu überprüfen, ob ein Teilnehmer korrekt geantwortet hat und das Ergebnis zu speichern:


                                        const trial = {

                                            type: jsPsychHtmlKeyboardResponse,

                                            stimulus: jsPsych.timelineVariable('target'),

                                            choices: ['f', 'j'],

                                            trial_duration: 1500,

                                            post_trial_gap: 395,

                                            data: {

                                                task: 'trial',

                                                target: jsPsych.timelineVariable('target'),

                                                condition: jsPsych.timelineVariable('condition'),

                                                correct_response: jsPsych.timelineVariable('correct_response')

                                            },

                                            on_finish: function(data){

                                                data.correct = jsPsych.pluginAPI.compareKeys(data.response, data.correct_response);

                                            }

                                        };

Hier erhält die Funktion in `on_finish` die während des Versuchs gesammelten Daten als Argument und Sie können darauf zugreifen, um Daten zu lesen oder zu schreiben. Der Vergleich der relevanten Schlüssel könnte auch mit JavaScript erreicht werden, aber da diese Aufgabe häufig vorkommt, gibt es die spezielle jsPsych-Funktion `jsPsych.pluginAPI.compareKeys()`, die Sie verwenden können. Wenn Sie das Experiment mit der neuen Ergänzung erneut ausführen, enthalten die Daten, ob der Teilnehmer korrekt geantwortet hat:

Weitere Informationen

Sie können das fertige Experiment aus diesem Tutorial hier herunterladen:

Dieses Tutorial bietet nur die Grundlagen von jsPsych. Wenn Sie mehr erfahren möchten, schauen Sie sich bitte die offizielle Dokumentation oder unsere Workshop-Folien und unsere Gitlab repo