Merge pull request #2379 from jspsych/feature-seed-rng

Create a seedable random number generator

.changeset/rotten-worms-float.md

@@ -0,0 +1,5 @@
+---
+"jspsych": minor
+---
+
+Added `setSeed()` to `jsPsych.randomization` to allow for seeding the random number generator and generating predictable sequences of random numbers.

docs/reference/jspsych-randomization.md

@@ -467,6 +467,51 @@ var sample = jsPsych.randomization.sampleWithoutReplacement(myArray, 2);
 
 ---
 
+## jsPsych.randomization.setSeed
+
+```javascript
+jsPsych.randomization.setSeed(seed)
+```
+
+### Parameters
+
+| Parameter | Type  | Description                    |
+| --------- | ----- | ------------------------------ |
+| seed      | string | A seed for the random number generator |
+
+### Return value
+
+Returns the seed value.
+
+### Description
+
+This function will override the behavior of `Math.random()` to produce a seedable pseudo random number generator.
+It uses the [seedrandom package](https://www.npmjs.com/package/seedrandom). 
+Note that calling `setSeed()` will change how `Math.random()` behaves for the entire document. 
+If you have non-jsPsych components on the page that use `Math.random()` they will be affected.
+
+Using `setSeed()` without passing in a seed will generate a random 32-bit seed.
+The seed value will be returned from the function call, allowing you to save it in the data for the experiment if needed.
+
+### Examples
+
+#### Use a random 32-bit seed and save to data
+
+```javascript
+const seed = jsPsych.setSeed();
+jsPsych.data.addProperties({
+	rng_seed: seed
+});
+```
+
+#### Use your own seed
+
+```javascript
+jsPsych.setSeed("jspsych");
+```
+
+---
+
 ## jsPsych.randomization.shuffle
 
 ```javascript

package-lock.json

@@ -3080,6 +3080,12 @@
         "@types/node": "*"
       }
     },
+    "node_modules/@types/seedrandom": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@types/seedrandom/-/seedrandom-3.0.2.tgz",
+      "integrity": "sha512-YPLqEOo0/X8JU3rdiq+RgUKtQhQtrppE766y7vMTu8dGML7TVtZNiiiaC/hhU9Zqw9UYopXxhuWWENclMVBwKQ==",
+      "dev": true
+    },
     "node_modules/@types/semver": {
       "version": "6.2.3",
       "resolved": "https://registry.npmjs.org/@types/semver/-/semver-6.2.3.tgz",
@@ -12974,6 +12980,11 @@
         "node": ">=10"
       }
     },
+    "node_modules/seedrandom": {
+      "version": "3.0.5",
+      "resolved": "https://registry.npmjs.org/seedrandom/-/seedrandom-3.0.5.tgz",
+      "integrity": "sha512-8OwmbklUNzwezjGInmZ+2clQmExQPvomqjL7LFqOYqtmuxRgQYqOD3mHaU+MvZn5FLUeVxVfQjwLZW/n/JFuqg=="
+    },
     "node_modules/semver": {
       "version": "5.7.1",
       "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz",
@@ -15915,11 +15926,13 @@
       "license": "MIT",
       "dependencies": {
         "auto-bind": "^4.0.0",
-        "random-words": "^1.1.1"
+        "random-words": "^1.1.1",
+        "seedrandom": "^3.0.5"
       },
       "devDependencies": {
         "@jspsych/config": "^1.1.0",
-        "@types/dom-mediacapture-record": "^1.0.11"
+        "@types/dom-mediacapture-record": "^1.0.11",
+        "@types/seedrandom": "^3.0.1"
       }
     },
     "packages/plugin-animation": {
@@ -19123,6 +19136,12 @@
         "@types/node": "*"
       }
     },
+    "@types/seedrandom": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@types/seedrandom/-/seedrandom-3.0.2.tgz",
+      "integrity": "sha512-YPLqEOo0/X8JU3rdiq+RgUKtQhQtrppE766y7vMTu8dGML7TVtZNiiiaC/hhU9Zqw9UYopXxhuWWENclMVBwKQ==",
+      "dev": true
+    },
     "@types/semver": {
       "version": "6.2.3",
       "resolved": "https://registry.npmjs.org/@types/semver/-/semver-6.2.3.tgz",
@@ -24356,8 +24375,10 @@
       "requires": {
         "@jspsych/config": "^1.1.0",
         "@types/dom-mediacapture-record": "^1.0.11",
+        "@types/seedrandom": "^3.0.1",
         "auto-bind": "^4.0.0",
-        "random-words": "^1.1.1"
+        "random-words": "^1.1.1",
+        "seedrandom": "^3.0.5"
       }
     },
     "just-debounce": {
@@ -26698,6 +26719,11 @@
         "xmlchars": "^2.2.0"
       }
     },
+    "seedrandom": {
+      "version": "3.0.5",
+      "resolved": "https://registry.npmjs.org/seedrandom/-/seedrandom-3.0.5.tgz",
+      "integrity": "sha512-8OwmbklUNzwezjGInmZ+2clQmExQPvomqjL7LFqOYqtmuxRgQYqOD3mHaU+MvZn5FLUeVxVfQjwLZW/n/JFuqg=="
+    },
     "semver": {
       "version": "5.7.1",
       "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz",

packages/jspsych/package.json

@@ -40,10 +40,12 @@
   "homepage": "https://www.jspsych.org",
   "dependencies": {
     "auto-bind": "^4.0.0",
-    "random-words": "^1.1.1"
+    "random-words": "^1.1.1",
+    "seedrandom": "^3.0.5"
   },
   "devDependencies": {
     "@jspsych/config": "^1.1.0",
-    "@types/dom-mediacapture-record": "^1.0.11"
+    "@types/dom-mediacapture-record": "^1.0.11",
+    "@types/seedrandom": "^3.0.1"
   }
 }

packages/jspsych/src/modules/randomization.ts

@@ -1,4 +1,20 @@
 import rw from "random-words";
+import seedrandom from "seedrandom";
+
+/**
+ * Uses the `seedrandom` package to replace Math.random() with a seedable PRNG.
+ *
+ * @param seed An optional seed. If none is given, a random seed will be generated.
+ * @returns The seed value.
+ */
+export function setSeed(seed?: string) {
+  if (!seed) {
+    const prng = seedrandom();
+    seed = prng.int32().toString();
+  }
+  seedrandom(seed, { global: true });
+  return seed;
+}
 
 export function repeat(array, repetitions, unpack = false) {
   const arr_isArray = Array.isArray(array);

packages/jspsych/tests/randomization/randomziation.test.ts

@@ -3,6 +3,7 @@ import {
   randomID,
   randomInt,
   repeat,
+  setSeed,
   shuffle,
   shuffleAlternateGroups,
   shuffleNoRepeats,
@@ -12,7 +13,7 @@ afterEach(() => {
   jest.restoreAllMocks();
 });
 
-describe("#shuffle", () => {
+describe("shuffle", () => {
   test("should produce fixed order with mock RNG", () => {
     jest.spyOn(Math, "random").mockReturnValue(0.5);
     const arr = [1, 2, 3, 4, 5, 6];
@@ -31,7 +32,7 @@ describe("shuffleAlternateGroups", () => {
   });
 });
 
-describe("#randomID", () => {
+describe("randomID", () => {
   test("should produce ID based on mock RNG", () => {
     jest
       .spyOn(Math, "random")
@@ -165,3 +166,20 @@ describe("randomInt", () => {
     }).toThrowError();
   });
 });
+
+describe("setSeed", () => {
+  test("Replaces Math.random() with seedable RNG", () => {
+    setSeed("jspsych");
+
+    const r1_1 = Math.random();
+    const r1_2 = Math.random();
+
+    setSeed("jspsych");
+
+    const r2_1 = Math.random();
+    const r2_2 = Math.random();
+
+    expect(r1_1).toEqual(r2_1);
+    expect(r1_2).toEqual(r2_2);
+  });
+});

packages/jspsych/tests/randomization/setseed.test.ts

@@ -0,0 +1,93 @@
+// this file is to test that jsPsych.randomization.setSeed works in context
+
+import htmlKeyboardResponse from "@jspsych/plugin-html-keyboard-response";
+import { pressKey, startTimeline } from "@jspsych/test-utils";
+
+import { initJsPsych } from "../../src";
+
+describe("setSeed generates predictable randomization", () => {
+  test("timeline variable randomization is preserved", async () => {
+    const jsPsych = initJsPsych();
+
+    const seed = jsPsych.randomization.setSeed();
+
+    const { getData } = await startTimeline(
+      [
+        {
+          timeline: [
+            {
+              type: htmlKeyboardResponse,
+              stimulus: "this is html",
+              data: {
+                i: jsPsych.timelineVariable("i"),
+              },
+            },
+          ],
+          timeline_variables: [
+            { i: 0 },
+            { i: 1 },
+            { i: 2 },
+            { i: 3 },
+            { i: 4 },
+            { i: 5 },
+            { i: 6 },
+            { i: 7 },
+            { i: 8 },
+          ],
+          randomize_order: true,
+        },
+      ],
+      jsPsych
+    );
+
+    for (let i = 0; i < 9; i++) {
+      pressKey(" ");
+    }
+
+    const data_run_1 = getData().readOnly();
+
+    const jsPsych_run2 = initJsPsych();
+
+    jsPsych_run2.randomization.setSeed(seed);
+
+    const { getData: getData2 } = await startTimeline(
+      [
+        {
+          timeline: [
+            {
+              type: htmlKeyboardResponse,
+              stimulus: "this is html",
+              data: {
+                i: jsPsych_run2.timelineVariable("i"),
+              },
+            },
+          ],
+          timeline_variables: [
+            { i: 0 },
+            { i: 1 },
+            { i: 2 },
+            { i: 3 },
+            { i: 4 },
+            { i: 5 },
+            { i: 6 },
+            { i: 7 },
+            { i: 8 },
+          ],
+          randomize_order: true,
+        },
+      ],
+      jsPsych_run2
+    );
+
+    for (let i = 0; i < 9; i++) {
+      pressKey(" ");
+    }
+
+    const data_run_2 = getData2().readOnly();
+
+    console.log(data_run_1.values());
+    console.log(data_run_2.values());
+
+    expect(data_run_1.select("i").values).toEqual(data_run_2.select("i").values);
+  });
+});