Maze plugin

packages/plugin-maze/README.md

@@ -0,0 +1,35 @@
+# Maze
+
+## Overview
+
+A jsPsych plugin for running Maze experiments
+
+## Loading
+
+### In browser
+
+```js
+<script src="https://unpkg.com/@jspsych-contrib/[email protected]"></script>
+```
+
+### Via NPM
+
+```
+npm install @jspsych-contrib/plugin-maze
+```
+
+```js
+import jsPsychMaze from '@jspsych-contrib/plugin-maze';
+```
+
+## Compatibility
+
+jsPsych 8.0.0
+
+## Documentation
+
+See [documentation](https://github.com/jspsych/jspsych-contrib/blob/main/packages/plugin-maze/docs/jspsych-maze.md)
+
+## Author / Citation
+
+[Morgan Grobol](https://lgrobol.bzh)

packages/plugin-maze/docs/maze.md

@@ -0,0 +1,91 @@
+Maze
+====
+
+A jsPsych plugin for running Maze (Forster et al., 2009) experiments, a version of self-paced
+reading that asks to choose between the correct next word and a distractor.
+
+## Parameters
+
+In addition to the [parameters available in all
+plugins](https://www.jspsych.org/latest/overview/plugins/#parameters-available-in-all-plugins), this
+plugin accepts the following parameters. Parameters with a default value of undefined must be
+specified. Other parameters can be left unspecified if the default value is acceptable.
+
+| Parameter             | Type                            | Default Value             | Description                                                                                                                      |
+|-----------------------|---------------------------------|---------------------------|----------------------------------------------------------------------------------------------------------------------------------|
+| `sentence`            | `Array<[string, string]>`       | `undefined`               | The sentence to use in the Maze, as `[word, foil]` pairs.                                                                        |
+| `canvas_size`         | `[string, string]`              | `["1280px", "960px"]`     | The dimensions of the canvas.                                                                                                    |
+| `halt_on_error`       | `boolean`                       | `false`                   | If true, any error ends the trial and sends the subject directly to the question (if any), then exit.                            |
+| `inter_word_interval` | `number`                        | `0`                       | How long to wait on a blank screen before displaying the next word.                                                              |
+| `keys`                | `{left: string, right: string}` | `{left: "f", right: "j"}` | The choice/navigation keys.                                                                                                      |
+| `position_left`       | `{x: number?, y: number?}`      | `{x: null, y: null}`      | The position of the left word. A null `x` is set to 1/3 of the canvas' width and null `y` is set to half of the canvas' height.  |
+| `position_right`      | `{x: number?, y: number?}`      | `{x: null, y: null}`      | The position of the right word. A null `x` is set to 2/3 of the canvas' width and null `y` is set to half of the canvas' height. |
+| `pre_answer_interval` | `number`                        | `0`                       | The minimum time (in ms) before the subject is allowed to chose a word.                                                          |                                            |
+
+## Data Generated
+
+In addition to the [default data collected by all
+plugins](https://www.jspsych.org/latest/overview/plugins/#data-collected-by-all-plugins), this
+plugin collects the following data for each trial.
+
+| Name       | Type                                                                                        | Value                                                                     |
+|------------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
+| `sentence` | `string`                                                                                    | The sentence used in the trial (joined with spaces)                       |
+| `events`   | `Array<{correct: boolean, foil: string, rt: number, side: "left" | "right", word: string}>` | The parameters, choice and interaction time for each word of the sentence |
+
+## Install
+
+Using the CDN-hosted JavaScript file:
+
+```js
+<script src="https://unpkg.com/@jspsych-contrib/plugin-maze"></script>
+```
+
+Using the JavaScript file downloaded from a GitHub release dist archive:
+
+```js
+<script src="jspsych/plugin-maze.js"></script>
+```
+
+Using NPM:
+
+```bash
+npm install @jspsych-contrib/plugin-maze
+```
+
+```js
+import Maze from '@jspsych-contrib/plugin-maze';
+```
+
+## Examples
+
+```javascript
+
+const trial = {
+  type: jsPsychMaze,
+  sentence: [
+      ["After", "x-x-x"],
+      ["a", "so"],
+      ["bit", "pot"],
+      ["of", "if"],
+      ["success", "singing"],
+      ["the", "ate"],
+      ["stocks", "winter"],
+      ["took", "walk"],
+      ["a", "we"],
+      ["dive", "toad"],
+    ],
+  question: {
+    text: "Did the stocks take a dive?",
+    correct: "yes",
+    wrong: "no",
+  },
+  waiting_time: 200,
+}
+```
+
+## Bibliography
+
+- Forster, Kenneth I., Christine Guerrera, and Lisa Elliot. 2009. ‘The Maze Task: Measuring Forced
+  Incremental Sentence Processing Time’. Behavior Research Methods 41 (1): 163–71.
+  <https://doi.org/10.3758/BRM.41.1.163>.

packages/plugin-maze/examples/index.html

@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <script src="https://unpkg.com/jspsych"></script>
+    <script src="https://unpkg.com/@jspsych/[email protected]"></script>
+    <!-- The plugin is loaded here -->
+    <script src="https://unpkg.com/@jspsych/plugin-maze"></script>
+    <script src="../dist/index.browser.js"></script>
+
+    <!-- Ugly trick to keep the data separate while not having to think of how to fetch it -->
+    <script src="stimuli.js"></script>
+
+    <link rel="stylesheet" href="https://unpkg.com/jspsych/css/jspsych.css" />
+    <style>
+      .jspsych-display-element {
+        font: normal 24px monospace;
+      }
+    </style>
+  </head>
+
+  <body></body>
+  <script>
+    const jsPsych = initJsPsych({
+      on_finish: () => {
+        jsPsych.data.displayData("json");
+      },
+    });
+
+    const procedure = {
+      timeline: [
+        {
+          type: jsPsychMaze,
+          sentence: jsPsych.timelineVariable("sentence"),
+          inter_word_interval: 100,
+          pre_answer_interval: 200,
+          halt_on_error: true,
+        },
+        {
+          type: jsPsychHtmlKeyboardResponse,
+          stimulus: () => jsPsych.evaluateTimelineVariable("question").text,
+          choices: ["f", "j"],
+          prompt: () => `
+            <span style="margin: 5em 8em 0 8em; display: inline-block;">${
+              jsPsych.evaluateTimelineVariable("question").left
+            }</span>
+            <span style="margin: 5em 8em 0 8em; display: inline-block;">${
+              jsPsych.evaluateTimelineVariable("question").right
+            }</span>`,
+          on_finish: (data) => {
+            success: jsPsych.pluginAPI.compareKeys(
+              data.response,
+              "left" === jsPsych.evaluateTimelineVariable("question").correct
+                ? "f"
+                : "j"
+            )
+          }
+        },
+      ],
+      timeline_variables: data,
+    };
+
+    jsPsych.run(procedure);
+  </script>
+</html>

packages/plugin-maze/examples/stimuli.js

@@ -0,0 +1,41 @@
+const data = [
+  {
+    sentence: [
+      ["After", "x-x-x"],
+      ["a", "so"],
+      ["bit", "pot"],
+      ["of", "if"],
+      ["success", "singing"],
+      ["the", "ate"],
+      ["stocks", "winter"],
+      ["took", "walk"],
+      ["a", "we"],
+      ["dive", "toad"],
+    ],
+    question: {
+      text: "Did the stocks take a dive?",
+      left: "yes",
+      right: "no",
+      correct: "left",
+    },
+  },
+  {
+    sentence: [
+      ["The", "x-x-x"],
+      ["fashion", "realize"],
+      ["model", "shirt"],
+      ["was", "see"],
+      ["very", "into"],
+      ["self-conscious", "professionally"],
+      ["of", "do"],
+      ["her", "why"],
+      ["appearance", "sandwiches"],
+    ],
+    question: {
+      text: "Who was self-conscious?",
+      left: "The designer",
+      right: "The model",
+      correct: "right",
+    },
+  },
+];

packages/plugin-maze/jest.config.cjs

@@ -0,0 +1 @@
+module.exports = require("@jspsych/config/jest").makePackageConfig(__dirname);

packages/plugin-maze/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@jspsych-contrib/plugin-maze",
+  "version": "0.0.1",
+  "description": "A jsPsych plugin for running Maze experiments",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "exports": {
+    "import": "./dist/index.js",
+    "require": "./dist/index.cjs"
+  },
+  "typings": "dist/index.d.ts",
+  "unpkg": "dist/index.browser.min.js",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "source": "src/index.ts",
+  "scripts": {
+    "test": "jest",
+    "test:watch": "npm test -- --watch",
+    "tsc": "tsc",
+    "build": "rollup --config",
+    "build:watch": "npm run build -- --watch",
+    "dev-serve": "concurrently \"npm run build -- --watch\" \"serve\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jspsych/jspsych-contrib.git",
+    "directory": "packages/plugin-maze"
+  },
+  "author": {
+    "name": "Morgan Grobol",
+    "url": "https://lgrobol.bzh"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jspsych/jspsych-contrib/issues"
+  },
+  "homepage": "https://github.com/jspsych/jspsych-contrib/tree/main/packages/plugin-maze",
+  "peerDependencies": {
+    "jspsych": ">=8.0.0"
+  },
+  "devDependencies": {
+    "@jspsych/config": "^3.2.2",
+    "@jspsych/test-utils": "^1.0.0",
+    "concurrently": "^9.1.2",
+    "jspsych": "^8.0.0",
+    "serve": "^14.2.4"
+  }
+}

packages/plugin-maze/rollup.config.mjs

@@ -0,0 +1,3 @@
+import { makeRollupConfig } from "@jspsych/config/rollup";
+
+export default makeRollupConfig("jsPsychMaze");

packages/plugin-maze/src/index.spec.ts

@@ -0,0 +1,59 @@
+import { pressKey, startTimeline } from "@jspsych/test-utils";
+
+import jsPsychMaze from ".";
+
+jest.useFakeTimers();
+
+describe("The maze jspsych plugin", () => {
+  it("Runs maze", async () => {
+    const sentence = [
+      ["The", "x-x-x"],
+      ["fashion", "realize"],
+      ["model", "shirt"],
+      ["was", "see"],
+      ["very", "into"],
+      ["self-conscious", "professionally"],
+      ["of", "do"],
+      ["her", "why"],
+      ["appearance", "sandwiches"],
+    ];
+    const { expectFinished, getHTML, getData, displayElement, jsPsych } = await startTimeline([
+      {
+        type: jsPsychMaze,
+        sentence: sentence,
+        inter_word_interval: 2,
+        end_interval: 50,
+        pre_answer_interval: 20,
+      },
+    ]);
+
+    // Start
+    jest.advanceTimersByTime(100);
+    pressKey("f");
+
+    // This one is too fast and should be ignored
+    jest.advanceTimersByTime(10);
+    pressKey("f");
+
+    for (const [_word, _foil] of sentence) {
+      jest.advanceTimersByTime(100);
+      pressKey("f");
+    }
+
+    await expectFinished();
+
+    // Unclear to me why the values are wrapped in length 1 array
+    for (const [i, [word, foil], r] of getData()
+      .select("events")
+      .values[0].map((r: Response, i: number) => [i, sentence[i], r])) {
+      expect(r.word).toBe(word);
+      expect(r.foil).toBe(foil);
+
+      // FIXME: make this better, probably with different rts.
+
+      // We first waited 10s before the first word and for the other words, the inter-word interval
+      // is substracted from the elapsed time
+      expect(r.rt).toBe(0 === i ? 110 : 98);
+    }
+  });
+});