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,90 @@
+Maze
+====
+
+A jsPsych plugin for running Maze (Forster et al., 2009) experiments, a version of self-paced
+reading that asks to chose 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.                                                                        |
+| `question`        | `{text: string, correct: str, wrong: str}?` | `null`                       | An optional question to ask at the end of the mazz to make sure the subject has read the sentence.                               |
+| `canvas_style`    | `string`                                    | `"border: 0px solid black;"` | Extra style to inject in the canvas element.                                                                                     |
+| `canvas_colour`   | `string`                                    | `"white"`                    | The canvas' background colour.                                                                                                   |
+| `canvas_size`     | `[number, number]`                          | `[1280, 960]`                | The dimensions of the canvas.                                                                                                    |
+| `font_colour`     | `str`                                       | `"black"`                    | The font colour for the text.                                                                                                    |
+| `font_style`      | `str`                                       | `"normal 24px monospace"`    | The font style for the text.                                                                                                     |
+| `halt_on_error`   | `bool`                                      | `false`                      | If true, any error ends the trial and sends the subject directly to the question (if any), then exit.                            |
+| `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. |
+| `tranlate_origin` | `bool`                                      | `true`                       | If true, the coordinates are transposed to have `(0, 0)` be the center of the canvas.                                            |
+| `waiting_time`    | `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: bool, foil: string, rt: number, word: string, word_number: number}>` | The parameters, choice and interaction time for each word of the sentence   |
+| `question` | `{question: {text: string, correct: str, wrong: str}, correct: bool, rt: number}>`    | The parameters, choice and interaction time for the final question (if any) |
+
+## 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,36 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <script src="https://unpkg.com/jspsych"></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" />
+  </head>
+
+  <body></body>
+  <script>
+    const jsPsych = initJsPsych();
+
+    const procedure = {
+      timeline : [
+        {
+          type: jsPsychMaze,
+          sentence: jsPsych.timelineVariable('sentence'),
+          question: jsPsych.timelineVariable('question'),
+          waiting_time: 200,
+          on_finish: () => {
+            jsPsych.data.displayData('json');
+          },
+        }
+      ],
+      timeline_variables: data,
+    };
+
+    jsPsych.run(procedure)
+  </script>
+</html>

packages/plugin-maze/examples/stimuli.js

@@ -0,0 +1,39 @@
+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?",
+      correct: "yes",
+      wrong: "no",
+    },
+  },
+  {
+    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?",
+      correct: "The model",
+      wrong: "The designer",
+    },
+  },
+];

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,77 @@
+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,
+      },
+    ]);
+
+    // Start
+    jest.advanceTimersByTime(100);
+    pressKey("f");
+
+    for (const [_word, _foil] of sentence) {
+      jest.advanceTimersByTime(100);
+      pressKey("f");
+    }
+
+    await expectFinished();
+  });
+  it("Asks questions", 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,
+        question: {
+          text: "Who was self-conscious?",
+          correct: "The model",
+          wrong: "The designer",
+        },
+      },
+    ]);
+
+    // Start
+    jest.advanceTimersByTime(100);
+    pressKey("f");
+
+    for (const [_word, _foil] of sentence) {
+      jest.advanceTimersByTime(100);
+      pressKey("f");
+    }
+
+    // Question
+    jest.advanceTimersByTime(100);
+    pressKey("f");
+
+    await expectFinished();
+  });
+});