jspsych 6.2.0 → 7.1.0

package/src/modules/plugin-api/index.ts

@@ -0,0 +1,28 @@
+import autoBind from "auto-bind";
+
+import { JsPsych } from "../../JsPsych";
+import { HardwareAPI } from "./HardwareAPI";
+import { KeyboardListenerAPI } from "./KeyboardListenerAPI";
+import { MediaAPI } from "./MediaAPI";
+import { SimulationAPI } from "./SimulationAPI";
+import { TimeoutAPI } from "./TimeoutAPI";
+
+export function createJointPluginAPIObject(jsPsych: JsPsych) {
+  const settings = jsPsych.getInitSettings();
+  return Object.assign(
+    {},
+    ...[
+      new KeyboardListenerAPI(
+        jsPsych.getDisplayContainerElement,
+        settings.case_sensitive_responses,
+        settings.minimum_valid_rt
+      ),
+      new TimeoutAPI(),
+      new MediaAPI(settings.use_webaudio, jsPsych.webaudio_context),
+      new HardwareAPI(),
+      new SimulationAPI(),
+    ].map((object) => autoBind(object))
+  ) as KeyboardListenerAPI & TimeoutAPI & MediaAPI & HardwareAPI & SimulationAPI;
+}
+
+export type PluginAPI = ReturnType<typeof createJointPluginAPIObject>;

package/src/modules/plugins.ts

@@ -0,0 +1,158 @@
+/**
+Flatten the type output to improve type hints shown in editors.
+Borrowed from type-fest
+*/
+type Simplify<T> = { [KeyType in keyof T]: T[KeyType] };
+
+/**
+Create a type that makes the given keys required. The remaining keys are kept as is.
+Borrowed from type-fest
+*/
+type SetRequired<BaseType, Keys extends keyof BaseType> = Simplify<
+  Omit<BaseType, Keys> & Required<Pick<BaseType, Keys>>
+>;
+
+/**
+ * Parameter types for plugins
+ */
+export enum ParameterType {
+  BOOL,
+  STRING,
+  INT,
+  FLOAT,
+  FUNCTION,
+  KEY,
+  KEYS,
+  SELECT,
+  HTML_STRING,
+  IMAGE,
+  AUDIO,
+  VIDEO,
+  OBJECT,
+  COMPLEX,
+  TIMELINE,
+}
+
+type ParameterTypeMap = {
+  [ParameterType.BOOL]: boolean;
+  [ParameterType.STRING]: string;
+  [ParameterType.INT]: number;
+  [ParameterType.FLOAT]: number;
+  [ParameterType.FUNCTION]: (...args: any[]) => any;
+  [ParameterType.KEY]: string;
+  [ParameterType.KEYS]: string[] | "ALL_KEYS" | "NO_KEYS";
+  [ParameterType.SELECT]: any;
+  [ParameterType.HTML_STRING]: string;
+  [ParameterType.IMAGE]: string;
+  [ParameterType.AUDIO]: string;
+  [ParameterType.VIDEO]: string;
+  [ParameterType.OBJECT]: object;
+  [ParameterType.COMPLEX]: any;
+  [ParameterType.TIMELINE]: any;
+};
+
+export interface ParameterInfo {
+  type: ParameterType;
+  array?: boolean;
+  pretty_name?: string;
+  default?: any;
+  preload?: boolean;
+}
+
+export interface ParameterInfos {
+  [key: string]: ParameterInfo;
+}
+
+type InferredParameter<I extends ParameterInfo> = I["array"] extends true
+  ? Array<ParameterTypeMap[I["type"]]>
+  : ParameterTypeMap[I["type"]];
+
+type RequiredParameterNames<I extends ParameterInfos> = {
+  [K in keyof I]: I[K]["default"] extends undefined ? K : never;
+}[keyof I];
+
+type InferredParameters<I extends ParameterInfos> = SetRequired<
+  {
+    [Property in keyof I]?: InferredParameter<I[Property]>;
+  },
+  RequiredParameterNames<I>
+>;
+
+export const universalPluginParameters = <const>{
+  /**
+   * Data to add to this trial (key-value pairs)
+   */
+  data: {
+    type: ParameterType.OBJECT,
+    pretty_name: "Data",
+    default: {},
+  },
+  /**
+   * Function to execute when trial begins
+   */
+  on_start: {
+    type: ParameterType.FUNCTION,
+    pretty_name: "On start",
+    default: function () {
+      return;
+    },
+  },
+  /**
+   * Function to execute when trial is finished
+   */
+  on_finish: {
+    type: ParameterType.FUNCTION,
+    pretty_name: "On finish",
+    default: function () {
+      return;
+    },
+  },
+  /**
+   * Function to execute after the trial has loaded
+   */
+  on_load: {
+    type: ParameterType.FUNCTION,
+    pretty_name: "On load",
+    default: function () {
+      return;
+    },
+  },
+  /**
+   * Length of gap between the end of this trial and the start of the next trial
+   */
+  post_trial_gap: {
+    type: ParameterType.INT,
+    pretty_name: "Post trial gap",
+    default: null,
+  },
+  /**
+   * A list of CSS classes to add to the jsPsych display element for the duration of this trial
+   */
+  css_classes: {
+    type: ParameterType.STRING,
+    pretty_name: "Custom CSS classes",
+    default: null,
+  },
+};
+
+export type UniversalPluginParameters = InferredParameters<typeof universalPluginParameters>;
+
+export interface PluginInfo {
+  name: string;
+  parameters: {
+    [key: string]: ParameterInfo;
+  };
+}
+
+export interface JsPsychPlugin<I extends PluginInfo> {
+  trial(
+    display_element: HTMLElement,
+    trial: TrialType<I>,
+    on_load?: () => void
+  ): void | Promise<any>;
+}
+
+export type TrialType<I extends PluginInfo> = InferredParameters<I["parameters"]> &
+  UniversalPluginParameters;
+
+export type PluginParameters<I extends PluginInfo> = InferredParameters<I["parameters"]>;

package/src/modules/randomization.ts

@@ -0,0 +1,327 @@
+import rw from "random-words";
+
+export function repeat(array, repetitions, unpack = false) {
+  const arr_isArray = Array.isArray(array);
+  const rep_isArray = Array.isArray(repetitions);
+
+  // if array is not an array, then we just repeat the item
+  if (!arr_isArray) {
+    if (!rep_isArray) {
+      array = [array];
+      repetitions = [repetitions];
+    } else {
+      repetitions = [repetitions[0]];
+      console.log(
+        "Unclear parameters given to randomization.repeat. Multiple set sizes specified, but only one item exists to sample. Proceeding using the first set size."
+      );
+    }
+  } else {
+    // if repetitions is not an array, but array is, then we
+    // repeat repetitions for each entry in array
+    if (!rep_isArray) {
+      let reps = [];
+      for (let i = 0; i < array.length; i++) {
+        reps.push(repetitions);
+      }
+      repetitions = reps;
+    } else {
+      if (array.length != repetitions.length) {
+        console.warn(
+          "Unclear parameters given to randomization.repeat. Items and repetitions are unequal lengths. Behavior may not be as expected."
+        );
+        // throw warning if repetitions is too short, use first rep ONLY.
+        if (repetitions.length < array.length) {
+          let reps = [];
+          for (let i = 0; i < array.length; i++) {
+            reps.push(repetitions);
+          }
+          repetitions = reps;
+        } else {
+          // throw warning if too long, and then use the first N
+          repetitions = repetitions.slice(0, array.length);
+        }
+      }
+    }
+  }
+
+  // should be clear at this point to assume that array and repetitions are arrays with == length
+  let allsamples = [];
+  for (let i = 0; i < array.length; i++) {
+    for (let j = 0; j < repetitions[i]; j++) {
+      if (array[i] == null || typeof array[i] != "object") {
+        allsamples.push(array[i]);
+      } else {
+        allsamples.push(Object.assign({}, array[i]));
+      }
+    }
+  }
+
+  let out: any = shuffle(allsamples);
+
+  if (unpack) {
+    out = unpackArray(out);
+  }
+
+  return out;
+}
+
+export function shuffle(array: Array<any>) {
+  if (!Array.isArray(array)) {
+    console.error("Argument to shuffle() must be an array.");
+  }
+
+  const copy_array = array.slice(0);
+  let m = copy_array.length,
+    t,
+    i;
+
+  // While there remain elements to shuffle…
+  while (m) {
+    // Pick a remaining element…
+    i = Math.floor(Math.random() * m--);
+
+    // And swap it with the current element.
+    t = copy_array[m];
+    copy_array[m] = copy_array[i];
+    copy_array[i] = t;
+  }
+
+  return copy_array;
+}
+
+export function shuffleNoRepeats(arr: Array<any>, equalityTest: (a: any, b: any) => boolean) {
+  if (!Array.isArray(arr)) {
+    console.error("First argument to shuffleNoRepeats() must be an array.");
+  }
+  if (typeof equalityTest !== "undefined" && typeof equalityTest !== "function") {
+    console.error("Second argument to shuffleNoRepeats() must be a function.");
+  }
+  // define a default equalityTest
+  if (typeof equalityTest == "undefined") {
+    equalityTest = function (a, b) {
+      if (a === b) {
+        return true;
+      } else {
+        return false;
+      }
+    };
+  }
+
+  const random_shuffle = shuffle(arr);
+  for (let i = 0; i < random_shuffle.length - 1; i++) {
+    if (equalityTest(random_shuffle[i], random_shuffle[i + 1])) {
+      // neighbors are equal, pick a new random neighbor to swap (not the first or last element, to avoid edge cases)
+      let random_pick = Math.floor(Math.random() * (random_shuffle.length - 2)) + 1;
+      // test to make sure the new neighbor isn't equal to the old one
+      while (
+        equalityTest(random_shuffle[i + 1], random_shuffle[random_pick]) ||
+        equalityTest(random_shuffle[i + 1], random_shuffle[random_pick + 1]) ||
+        equalityTest(random_shuffle[i + 1], random_shuffle[random_pick - 1])
+      ) {
+        random_pick = Math.floor(Math.random() * (random_shuffle.length - 2)) + 1;
+      }
+      const new_neighbor = random_shuffle[random_pick];
+      random_shuffle[random_pick] = random_shuffle[i + 1];
+      random_shuffle[i + 1] = new_neighbor;
+    }
+  }
+
+  return random_shuffle;
+}
+
+export function shuffleAlternateGroups(arr_groups, random_group_order = false) {
+  const n_groups = arr_groups.length;
+  if (n_groups == 1) {
+    console.warn(
+      "shuffleAlternateGroups() was called with only one group. Defaulting to simple shuffle."
+    );
+    return shuffle(arr_groups[0]);
+  }
+
+  let group_order = [];
+  for (let i = 0; i < n_groups; i++) {
+    group_order.push(i);
+  }
+  if (random_group_order) {
+    group_order = shuffle(group_order);
+  }
+
+  const randomized_groups = [];
+  let min_length = null;
+  for (let i = 0; i < n_groups; i++) {
+    min_length =
+      min_length === null ? arr_groups[i].length : Math.min(min_length, arr_groups[i].length);
+    randomized_groups.push(shuffle(arr_groups[i]));
+  }
+
+  const out = [];
+  for (let i = 0; i < min_length; i++) {
+    for (let j = 0; j < group_order.length; j++) {
+      out.push(randomized_groups[group_order[j]][i]);
+    }
+  }
+
+  return out;
+}
+
+export function sampleWithoutReplacement(arr, size) {
+  if (!Array.isArray(arr)) {
+    console.error("First argument to sampleWithoutReplacement() must be an array");
+  }
+
+  if (size > arr.length) {
+    console.error("Cannot take a sample larger than the size of the set of items to sample.");
+  }
+  return shuffle(arr).slice(0, size);
+}
+
+export function sampleWithReplacement(arr, size, weights?) {
+  if (!Array.isArray(arr)) {
+    console.error("First argument to sampleWithReplacement() must be an array");
+  }
+
+  const normalized_weights = [];
+  if (typeof weights !== "undefined") {
+    if (weights.length !== arr.length) {
+      console.error(
+        "The length of the weights array must equal the length of the array " +
+          "to be sampled from."
+      );
+    }
+    let weight_sum = 0;
+    for (const weight of weights) {
+      weight_sum += weight;
+    }
+    for (const weight of weights) {
+      normalized_weights.push(weight / weight_sum);
+    }
+  } else {
+    for (let i = 0; i < arr.length; i++) {
+      normalized_weights.push(1 / arr.length);
+    }
+  }
+
+  const cumulative_weights = [normalized_weights[0]];
+  for (let i = 1; i < normalized_weights.length; i++) {
+    cumulative_weights.push(normalized_weights[i] + cumulative_weights[i - 1]);
+  }
+
+  const samp = [];
+  for (let i = 0; i < size; i++) {
+    const rnd = Math.random();
+    let index = 0;
+    while (rnd > cumulative_weights[index]) {
+      index++;
+    }
+    samp.push(arr[index]);
+  }
+  return samp;
+}
+
+export function factorial(factors: Record<string, any>, repetitions = 1, unpack = false) {
+  let design = [{}];
+  for (const [factorName, factor] of Object.entries(factors)) {
+    const new_design = [];
+    for (const level of factor) {
+      for (const cell of design) {
+        new_design.push({ ...cell, [factorName]: level });
+      }
+    }
+    design = new_design;
+  }
+
+  return repeat(design, repetitions, unpack);
+}
+
+export function randomID(length = 32) {
+  let result = "";
+  const chars = "0123456789abcdefghjklmnopqrstuvwxyz";
+  for (let i = 0; i < length; i++) {
+    result += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return result;
+}
+
+/**
+ * Generate a random integer from `lower` to `upper`, inclusive of both end points.
+ * @param lower The lowest value it is possible to generate
+ * @param upper The highest value it is possible to generate
+ * @returns A random integer
+ */
+export function randomInt(lower: number, upper: number) {
+  if (upper < lower) {
+    throw new Error("Upper boundary must be less than or equal to lower boundary");
+  }
+  return lower + Math.floor(Math.random() * (upper - lower + 1));
+}
+
+/**
+ * Generates a random sample from a Bernoulli distribution.
+ * @param p The probability of sampling 1.
+ * @returns 0, with probability 1-p, or 1, with probability p.
+ */
+export function sampleBernoulli(p: number) {
+  return Math.random() <= p ? 1 : 0;
+}
+
+export function sampleNormal(mean: number, standard_deviation: number) {
+  return randn_bm() * standard_deviation + mean;
+}
+
+export function sampleExponential(rate: number) {
+  return -Math.log(Math.random()) / rate;
+}
+
+export function sampleExGaussian(
+  mean: number,
+  standard_deviation: number,
+  rate: number,
+  positive = false
+) {
+  let s = sampleNormal(mean, standard_deviation) + sampleExponential(rate);
+  if (positive) {
+    while (s <= 0) {
+      s = sampleNormal(mean, standard_deviation) + sampleExponential(rate);
+    }
+  }
+  return s;
+}
+
+/**
+ * Generate one or more random words.
+ *
+ * This is a wrapper function for the {@link https://www.npmjs.com/package/random-words `random-words` npm package}.
+ *
+ * @param opts An object with optional properties `min`, `max`, `exactly`,
+ * `join`, `maxLength`, `wordsPerString`, `separator`, and `formatter`.
+ *
+ * @returns An array of words or a single string, depending on parameter choices.
+ */
+export function randomWords(opts) {
+  return rw(opts);
+}
+
+// Box-Muller transformation for a random sample from normal distribution with mean = 0, std = 1
+// https://stackoverflow.com/a/36481059/3726673
+function randn_bm() {
+  var u = 0,
+    v = 0;
+  while (u === 0) u = Math.random(); //Converting [0,1) to (0,1)
+  while (v === 0) v = Math.random();
+  return Math.sqrt(-2.0 * Math.log(u)) * Math.cos(2.0 * Math.PI * v);
+}
+
+function unpackArray(array) {
+  const out = {};
+
+  for (const x of array) {
+    for (const key of Object.keys(x)) {
+      if (typeof out[key] === "undefined") {
+        out[key] = [];
+      }
+      out[key].push(x[key]);
+    }
+  }
+
+  return out;
+}

package/src/modules/turk.ts

@@ -0,0 +1,99 @@
+interface turkInformation {
+  /**
+   * Is the experiment being loaded in preview mode on Mechanical Turk?
+   */
+  previewMode: boolean;
+  /**
+   * Is the experiment being loaded outside of the Mechanical Turk environment?
+   */
+  outsideTurk: boolean;
+  /**
+   * The HIT ID.
+   */
+  hitId: string;
+  /**
+   * The Assignment ID.
+   */
+  assignmentId: string;
+  /**
+   * The worker ID.
+   */
+  workerId: string;
+  /**
+   * URL for submission of the HIT.
+   */
+  turkSubmitTo: string;
+}
+
+/**
+ * Gets information about the Mechanical Turk Environment, HIT, Assignment, and Worker
+ * by parsing the URL variables that Mechanical Turk generates.
+ * @returns An object containing information about the Mechanical Turk Environment, HIT, Assignment, and Worker.
+ */
+export function turkInfo(): turkInformation {
+  const turk: turkInformation = {
+    previewMode: false,
+    outsideTurk: false,
+    hitId: "INVALID_URL_PARAMETER",
+    assignmentId: "INVALID_URL_PARAMETER",
+    workerId: "INVALID_URL_PARAMETER",
+    turkSubmitTo: "INVALID_URL_PARAMETER",
+  };
+
+  const param = function (url, name) {
+    name = name.replace(/[\[]/, "\\[").replace(/[\]]/, "\\]");
+    const regexS = "[\\?&]" + name + "=([^&#]*)";
+    const regex = new RegExp(regexS);
+    const results = regex.exec(url);
+    return results == null ? "" : results[1];
+  };
+
+  const src = param(window.location.href, "assignmentId")
+    ? window.location.href
+    : document.referrer;
+
+  const keys = ["assignmentId", "hitId", "workerId", "turkSubmitTo"];
+  keys.map(function (key) {
+    turk[key] = unescape(param(src, key));
+  });
+
+  turk.previewMode = turk.assignmentId == "ASSIGNMENT_ID_NOT_AVAILABLE";
+
+  turk.outsideTurk =
+    !turk.previewMode && turk.hitId === "" && turk.assignmentId == "" && turk.workerId == "";
+
+  return turk;
+}
+
+/**
+ * Send data to Mechnical Turk for storage.
+ * @param data An object containing `key:value` pairs to send to Mechanical Turk. Values
+ * cannot contain nested objects, arrays, or functions.
+ * @returns Nothing
+ */
+export function submitToTurk(data) {
+  const turk = turkInfo();
+  const assignmentId = turk.assignmentId;
+  const turkSubmitTo = turk.turkSubmitTo;
+
+  if (!assignmentId || !turkSubmitTo) return;
+
+  const form = document.createElement("form");
+  form.method = "POST";
+  form.action = turkSubmitTo + "/mturk/externalSubmit?assignmentId=" + assignmentId;
+
+  for (const key in data) {
+    if (data.hasOwnProperty(key)) {
+      const hiddenField = document.createElement("input");
+      hiddenField.type = "hidden";
+      hiddenField.name = key;
+      hiddenField.id = key;
+      hiddenField.value = data[key];
+
+      form.appendChild(hiddenField);
+    }
+  }
+
+  document.body.appendChild(form);
+  form.submit();
+}

package/src/modules/utils.ts

@@ -0,0 +1,30 @@
+/**
+ * Finds all of the unique items in an array.
+ * @param arr The array to extract unique values from
+ * @returns An array with one copy of each unique item in `arr`
+ */
+export function unique(arr: Array<any>) {
+  return [...new Set(arr)];
+}
+
+export function deepCopy(obj) {
+  if (!obj) return obj;
+  let out;
+  if (Array.isArray(obj)) {
+    out = [];
+    for (const x of obj) {
+      out.push(deepCopy(x));
+    }
+    return out;
+  } else if (typeof obj === "object" && obj !== null) {
+    out = {};
+    for (const key in obj) {
+      if (obj.hasOwnProperty(key)) {
+        out[key] = deepCopy(obj[key]);
+      }
+    }
+    return out;
+  } else {
+    return obj;
+  }
+}

package/.github/workflows/jest.yml

@@ -1,20 +0,0 @@
-# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
-
-name: Jest Test
-
-on: [ push, pull_request ]
-
-jobs:
-  build:
-
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v2
-    - name: Use Node.js
-      uses: actions/setup-node@v1
-      with:
-        node-version: '14.x'
-    - run: npm ci
-    - run: npm test