jspsych 6.2.0 → 7.1.0

package/src/modules/data/DataCollection.ts

@@ -0,0 +1,198 @@
+import { deepCopy } from "../utils";
+import { DataColumn } from "./DataColumn";
+import { JSON2CSV, saveTextToFile } from "./utils";
+
+export class DataCollection {
+  private trials: any[];
+
+  constructor(data = []) {
+    this.trials = data;
+  }
+
+  push(new_data) {
+    this.trials.push(new_data);
+    return this;
+  }
+
+  join(other_data_collection: DataCollection) {
+    this.trials = this.trials.concat(other_data_collection.values());
+    return this;
+  }
+
+  top() {
+    if (this.trials.length <= 1) {
+      return this;
+    } else {
+      return new DataCollection([this.trials[this.trials.length - 1]]);
+    }
+  }
+
+  /**
+   * Queries the first n elements in a collection of trials.
+   *
+   * @param n A positive integer of elements to return. A value of
+   *          n that is less than 1 will throw an error.
+   *
+   * @return First n objects of a collection of trials. If fewer than
+   *         n trials are available, the trials.length elements will
+   *         be returned.
+   *
+   */
+  first(n = 1) {
+    if (n < 1) {
+      throw `You must query with a positive nonzero integer. Please use a
+               different value for n.`;
+    }
+    if (this.trials.length === 0) return new DataCollection();
+    if (n > this.trials.length) n = this.trials.length;
+    return new DataCollection(this.trials.slice(0, n));
+  }
+
+  /**
+   * Queries the last n elements in a collection of trials.
+   *
+   * @param n A positive integer of elements to return. A value of
+   *          n that is less than 1 will throw an error.
+   *
+   * @return Last n objects of a collection of trials. If fewer than
+   *         n trials are available, the trials.length elements will
+   *         be returned.
+   *
+   */
+  last(n = 1) {
+    if (n < 1) {
+      throw `You must query with a positive nonzero integer. Please use a
+               different value for n.`;
+    }
+    if (this.trials.length === 0) return new DataCollection();
+    if (n > this.trials.length) n = this.trials.length;
+    return new DataCollection(this.trials.slice(this.trials.length - n, this.trials.length));
+  }
+
+  values() {
+    return this.trials;
+  }
+
+  count() {
+    return this.trials.length;
+  }
+
+  readOnly() {
+    return new DataCollection(deepCopy(this.trials));
+  }
+
+  addToAll(properties) {
+    for (const trial of this.trials) {
+      Object.assign(trial, properties);
+    }
+    return this;
+  }
+
+  addToLast(properties) {
+    if (this.trials.length != 0) {
+      Object.assign(this.trials[this.trials.length - 1], properties);
+    }
+    return this;
+  }
+
+  filter(filters) {
+    // [{p1: v1, p2:v2}, {p1:v2}]
+    // {p1: v1}
+    let f;
+    if (!Array.isArray(filters)) {
+      f = deepCopy([filters]);
+    } else {
+      f = deepCopy(filters);
+    }
+
+    const filtered_data = [];
+    for (const trial of this.trials) {
+      let keep = false;
+      for (const filter of f) {
+        let match = true;
+        for (const key of Object.keys(filter)) {
+          if (typeof trial[key] !== "undefined" && trial[key] === filter[key]) {
+            // matches on this key!
+          } else {
+            match = false;
+          }
+        }
+        if (match) {
+          keep = true;
+          break;
+        } // can break because each filter is OR.
+      }
+      if (keep) {
+        filtered_data.push(trial);
+      }
+    }
+
+    return new DataCollection(filtered_data);
+  }
+
+  filterCustom(fn) {
+    return new DataCollection(this.trials.filter(fn));
+  }
+
+  select(column) {
+    const values = [];
+    for (const trial of this.trials) {
+      if (typeof trial[column] !== "undefined") {
+        values.push(trial[column]);
+      }
+    }
+    return new DataColumn(values);
+  }
+
+  ignore(columns) {
+    if (!Array.isArray(columns)) {
+      columns = [columns];
+    }
+    const o = deepCopy(this.trials);
+    for (const trial of o) {
+      for (const delete_key of columns) {
+        delete trial[delete_key];
+      }
+    }
+    return new DataCollection(o);
+  }
+
+  uniqueNames() {
+    const names = [];
+
+    for (const trial of this.trials) {
+      for (const key of Object.keys(trial)) {
+        if (!names.includes(key)) {
+          names.push(key);
+        }
+      }
+    }
+
+    return names;
+  }
+
+  csv() {
+    return JSON2CSV(this.trials);
+  }
+
+  json(pretty = false) {
+    if (pretty) {
+      return JSON.stringify(this.trials, null, "\t");
+    }
+    return JSON.stringify(this.trials);
+  }
+
+  localSave(format, filename) {
+    format = format.toLowerCase();
+    let data_string;
+    if (format === "json") {
+      data_string = this.json();
+    } else if (format === "csv") {
+      data_string = this.csv();
+    } else {
+      throw new Error('Invalid format specified for localSave. Must be "json" or "csv".');
+    }
+
+    saveTextToFile(data_string, filename);
+  }
+}

package/src/modules/data/DataColumn.ts

@@ -0,0 +1,86 @@
+export class DataColumn {
+  constructor(public values = []) {}
+
+  sum() {
+    let s = 0;
+    for (const v of this.values) {
+      s += v;
+    }
+    return s;
+  }
+
+  mean() {
+    return this.sum() / this.count();
+  }
+
+  median() {
+    if (this.values.length === 0) {
+      return undefined;
+    }
+    const numbers = this.values.slice(0).sort(function (a, b) {
+      return a - b;
+    });
+    const middle = Math.floor(numbers.length / 2);
+    const isEven = numbers.length % 2 === 0;
+    return isEven ? (numbers[middle] + numbers[middle - 1]) / 2 : numbers[middle];
+  }
+
+  min() {
+    return Math.min.apply(null, this.values);
+  }
+
+  max() {
+    return Math.max.apply(null, this.values);
+  }
+
+  count() {
+    return this.values.length;
+  }
+
+  variance() {
+    const mean = this.mean();
+    let sum_square_error = 0;
+    for (const x of this.values) {
+      sum_square_error += Math.pow(x - mean, 2);
+    }
+    const mse = sum_square_error / (this.values.length - 1);
+    return mse;
+  }
+
+  sd() {
+    const mse = this.variance();
+    const rmse = Math.sqrt(mse);
+    return rmse;
+  }
+
+  frequencies() {
+    const unique = {};
+    for (const x of this.values) {
+      if (typeof unique[x] === "undefined") {
+        unique[x] = 1;
+      } else {
+        unique[x]++;
+      }
+    }
+    return unique;
+  }
+
+  all(eval_fn) {
+    for (const x of this.values) {
+      if (!eval_fn(x)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  subset(eval_fn) {
+    const out = [];
+    for (const x of this.values) {
+      if (eval_fn(x)) {
+        out.push(x);
+      }
+    }
+    return new DataColumn(out);
+  }
+}

package/src/modules/data/index.ts

@@ -0,0 +1,174 @@
+import { JsPsych } from "../../JsPsych";
+import { DataCollection } from "./DataCollection";
+import { getQueryString } from "./utils";
+
+export class JsPsychData {
+  // data storage object
+  private allData: DataCollection;
+
+  // browser interaction event data
+  private interactionData: DataCollection;
+
+  // data properties for all trials
+  private dataProperties = {};
+
+  // cache the query_string
+  private query_string;
+
+  constructor(private jsPsych: JsPsych) {
+    this.reset();
+  }
+
+  reset() {
+    this.allData = new DataCollection();
+    this.interactionData = new DataCollection();
+  }
+
+  get() {
+    return this.allData;
+  }
+
+  getInteractionData() {
+    return this.interactionData;
+  }
+
+  write(data_object) {
+    const progress = this.jsPsych.getProgress();
+    const trial = this.jsPsych.getCurrentTrial();
+
+    //var trial_opt_data = typeof trial.data == 'function' ? trial.data() : trial.data;
+
+    const default_data = {
+      trial_type: trial.type.info.name,
+      trial_index: progress.current_trial_global,
+      time_elapsed: this.jsPsych.getTotalTime(),
+      internal_node_id: this.jsPsych.getCurrentTimelineNodeID(),
+    };
+
+    this.allData.push({
+      ...data_object,
+      ...trial.data,
+      ...default_data,
+      ...this.dataProperties,
+    });
+  }
+
+  addProperties(properties) {
+    // first, add the properties to all data that's already stored
+    this.allData.addToAll(properties);
+
+    // now add to list so that it gets appended to all future data
+    this.dataProperties = Object.assign({}, this.dataProperties, properties);
+  }
+
+  addDataToLastTrial(data) {
+    this.allData.addToLast(data);
+  }
+
+  getDataByTimelineNode(node_id) {
+    return this.allData.filterCustom(
+      (x) => x.internal_node_id.slice(0, node_id.length) === node_id
+    );
+  }
+
+  getLastTrialData() {
+    return this.allData.top();
+  }
+
+  getLastTimelineData() {
+    const lasttrial = this.getLastTrialData();
+    const node_id = lasttrial.select("internal_node_id").values[0];
+    if (typeof node_id === "undefined") {
+      return new DataCollection();
+    } else {
+      const parent_node_id = node_id.substr(0, node_id.lastIndexOf("-"));
+      const lastnodedata = this.getDataByTimelineNode(parent_node_id);
+      return lastnodedata;
+    }
+  }
+
+  displayData(format = "json") {
+    format = format.toLowerCase();
+    if (format != "json" && format != "csv") {
+      console.log("Invalid format declared for displayData function. Using json as default.");
+      format = "json";
+    }
+
+    const data_string = format === "json" ? this.allData.json(true) : this.allData.csv();
+
+    const display_element = this.jsPsych.getDisplayElement();
+
+    display_element.innerHTML = '<pre id="jspsych-data-display"></pre>';
+
+    document.getElementById("jspsych-data-display").textContent = data_string;
+  }
+
+  urlVariables() {
+    if (typeof this.query_string == "undefined") {
+      this.query_string = getQueryString();
+    }
+    return this.query_string;
+  }
+
+  getURLVariable(whichvar) {
+    return this.urlVariables()[whichvar];
+  }
+
+  createInteractionListeners() {
+    // blur event capture
+    window.addEventListener("blur", () => {
+      const data = {
+        event: "blur",
+        trial: this.jsPsych.getProgress().current_trial_global,
+        time: this.jsPsych.getTotalTime(),
+      };
+      this.interactionData.push(data);
+      this.jsPsych.getInitSettings().on_interaction_data_update(data);
+    });
+
+    // focus event capture
+    window.addEventListener("focus", () => {
+      const data = {
+        event: "focus",
+        trial: this.jsPsych.getProgress().current_trial_global,
+        time: this.jsPsych.getTotalTime(),
+      };
+      this.interactionData.push(data);
+      this.jsPsych.getInitSettings().on_interaction_data_update(data);
+    });
+
+    // fullscreen change capture
+    const fullscreenchange = () => {
+      const data = {
+        event:
+          // @ts-expect-error
+          document.isFullScreen ||
+          // @ts-expect-error
+          document.webkitIsFullScreen ||
+          // @ts-expect-error
+          document.mozIsFullScreen ||
+          document.fullscreenElement
+            ? "fullscreenenter"
+            : "fullscreenexit",
+        trial: this.jsPsych.getProgress().current_trial_global,
+        time: this.jsPsych.getTotalTime(),
+      };
+      this.interactionData.push(data);
+      this.jsPsych.getInitSettings().on_interaction_data_update(data);
+    };
+
+    document.addEventListener("fullscreenchange", fullscreenchange);
+    document.addEventListener("mozfullscreenchange", fullscreenchange);
+    document.addEventListener("webkitfullscreenchange", fullscreenchange);
+  }
+
+  // public methods for testing purposes. not recommended for use.
+  _customInsert(data) {
+    this.allData = new DataCollection(data);
+  }
+
+  _fullreset() {
+    this.reset();
+    this.dataProperties = {};
+  }
+}

package/src/modules/data/utils.ts

@@ -0,0 +1,75 @@
+// private function to save text file on local drive
+export function saveTextToFile(textstr: string, filename: string) {
+  const blobToSave = new Blob([textstr], {
+    type: "text/plain",
+  });
+  let blobURL = "";
+  if (typeof window.webkitURL !== "undefined") {
+    blobURL = window.webkitURL.createObjectURL(blobToSave);
+  } else {
+    blobURL = window.URL.createObjectURL(blobToSave);
+  }
+
+  const link = document.createElement("a");
+  link.id = "jspsych-download-as-text-link";
+  link.style.display = "none";
+  link.download = filename;
+  link.href = blobURL;
+  link.click();
+}
+
+// this function based on code suggested by StackOverflow users:
+// http://stackoverflow.com/users/64741/zachary
+// http://stackoverflow.com/users/317/joseph-sturtevant
+
+export function JSON2CSV(objArray) {
+  const array = typeof objArray != "object" ? JSON.parse(objArray) : objArray;
+  let line = "";
+  let result = "";
+  const columns = [];
+
+  for (const row of array) {
+    for (const key in row) {
+      let keyString = key + "";
+      keyString = '"' + keyString.replace(/"/g, '""') + '",';
+      if (!columns.includes(key)) {
+        columns.push(key);
+        line += keyString;
+      }
+    }
+  }
+
+  line = line.slice(0, -1); // removes last comma
+  result += line + "\r\n";
+
+  for (const row of array) {
+    line = "";
+    for (const col of columns) {
+      let value = typeof row[col] === "undefined" ? "" : row[col];
+      if (typeof value == "object") {
+        value = JSON.stringify(value);
+      }
+      const valueString = value + "";
+      line += '"' + valueString.replace(/"/g, '""') + '",';
+    }
+
+    line = line.slice(0, -1);
+    result += line + "\r\n";
+  }
+
+  return result;
+}
+
+// this function is modified from StackOverflow:
+// http://stackoverflow.com/posts/3855394
+
+export function getQueryString() {
+  const a = window.location.search.substr(1).split("&");
+  const b = {};
+  for (let i = 0; i < a.length; ++i) {
+    const p = a[i].split("=", 2);
+    if (p.length == 1) b[p[0]] = "";
+    else b[p[0]] = decodeURIComponent(p[1].replace(/\+/g, " "));
+  }
+  return b;
+}

package/src/modules/extensions.ts

@@ -0,0 +1,23 @@
+export interface JsPsychExtensionInfo {
+  name: string;
+}
+
+export interface JsPsychExtension {
+  /**
+   * Called once at the start of the experiment to initialize the extension
+   */
+  initialize(params?: Record<string, any>): Promise<void>;
+  /**
+   * Called at the start of a trial, prior to invoking the plugin's trial method.
+   */
+  on_start(params?: Record<string, any>): void;
+  /**
+   * Called during a trial, after the plugin makes initial changes to the DOM.
+   */
+  on_load(params?: Record<string, any>): void;
+  /**
+   * Called at the end of the trial.
+   * @returns Data to append to the trial's data object.
+   */
+  on_finish(params?: Record<string, any>): Record<string, any>;
+}

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

@@ -0,0 +1,32 @@
+export class HardwareAPI {
+  /**
+   * Indicates whether this instance of jspsych has opened a hardware connection through our browser
+   * extension
+   **/
+  hardwareConnected = false;
+
+  constructor() {
+    //it might be useful to open up a line of communication from the extension back to this page
+    //script, again, this will have to pass through DOM events. For now speed is of no concern so I
+    //will use jQuery
+    document.addEventListener("jspsych-activate", (evt) => {
+      this.hardwareConnected = true;
+    });
+  }
+
+  /**
+   * Allows communication with user hardware through our custom Google Chrome extension + native C++ program
+   * @param		mess	The message to be passed to our extension, see its documentation for the expected members of this object.
+   * @author	Daniel Rivas
+   *
+   */
+  hardware(mess) {
+    //since Chrome extension content-scripts do not share the javascript environment with the page
+    //script that loaded jspsych, we will need to use hacky methods like communicating through DOM
+    //events.
+    const jspsychEvt = new CustomEvent("jspsych", { detail: mess });
+    document.dispatchEvent(jspsychEvt);
+    //And voila! it will be the job of the content script injected by the extension to listen for
+    //the event and do the appropriate actions.
+  }
+}