Merge pull request #3167 from jspsych/skip-data-logging

Allow skipping data logging for a trial with `record_data: false`

Author: jodeleeuw

.changeset/lucky-glasses-crash.md

@@ -0,0 +1,6 @@
+---
+"jspsych": minor
+---
+
+Added `record_data` as a parameter available for any trial. Setting `record_data: false` will prevent data from being stored in the jsPsych data object for that trial.  
+

docs/overview/data.md

@@ -70,6 +70,18 @@ var trial = {
 }
 ```
 
+### Skipping data collection for a particular trial
+
+Sometimes you may want to skip data collection for a particular trial. This can be done by setting the `record_data` parameter to `false`. This is useful if you want your data output to only contain the trials that collect relevant responses from the participant. For example, you might want to skip data collection for trials that just present a fixation cross for a fixed period of time.
+
+```js
+var trial = {
+  type: jsPsychImageKeyboardResponse,
+  stimulus: 'imgA.jpg',
+  record_data: false
+}
+```
+
 ## Aggregating and manipulating jsPsych data
 
 When accessing the data with `jsPsych.data.get()` the returned object is a special data collection object that exposes a number of methods for aggregating and manipulating the data. The full list of methods is detailed in the [data module documentation](../reference/jspsych-data.md).

docs/overview/plugins.md

@@ -62,6 +62,7 @@ There is also a set of parameters that can be specified for any plugin:
 | css_classes    | string   | null                    | A list of CSS classes to add to the jsPsych display element for the duration of this trial. This allows you to create custom formatting rules (CSS classes) that are only applied to specific trials. For more information and examples, see the [Controlling Visual Appearance page](../overview/style.md) and the "css-classes-parameter.html" file in the jsPsych examples folder. |
 | save_trial_parameters | object | `{}` | An object containing any trial parameters that should or should not be saved to the trial data. Each key is the name of a trial parameter, and its value should be `true` or `false`, depending on whether or not its value should be saved to the data. If the parameter is a function that returns the parameter value, then the value that is returned will be saved to the data. If the parameter is always expected to be a function (e.g., an event-related callback function), then the function itself will be saved as a string. For more examples, see the "save-trial-parameters.html" file in the jsPsych examples folder. |
 | save_timeline_variables | boolean or array | `false` | If set to `true`, then all timeline variables will have their current value recorded to the data for this trial. If set to an array, then any variables listed in the array will be saved.
+| record_data | boolean | `true` | If set to `false`, then the data for this trial will not be recorded. |
 
 ### The data parameter
 

packages/jspsych/src/JsPsych.ts

@@ -357,14 +357,20 @@ export class JsPsych {
     },
 
     onTrialResultAvailable: (trial: Trial) => {
-      trial.getResult().time_elapsed = this.getTotalTime();
-      this.data.write(trial);
+      const result = trial.getResult();
+      if (result) {
+        result.time_elapsed = this.getTotalTime();
+        this.data.write(trial);
+      }
     },
 
     onTrialFinished: (trial: Trial) => {
       const result = trial.getResult();
       this.options.on_trial_finish(result);
-      this.options.on_data_update(result);
+
+      if (result) {
+        this.options.on_data_update(result);
+      }
 
       if (this.progressBar && this.options.auto_update_progress_bar) {
         this.progressBar.progress = this.timeline.getNaiveProgress();

packages/jspsych/src/timeline/Timeline.spec.ts

@@ -292,6 +292,19 @@ describe("Timeline", () => {
       expect(onTimelineFinish).toHaveBeenCalledTimes(1);
     });
 
+    it("loop function ignores data from trials where `record_data` is false", async () => {
+      const loopFunction = jest.fn();
+      loopFunction.mockReturnValue(false);
+
+      const timeline = createTimeline({
+        timeline: [{ type: TestPlugin, record_data: false }, { type: TestPlugin }],
+        loop_function: loopFunction,
+      });
+
+      await timeline.run();
+      expect((loopFunction.mock.calls[0][0] as DataCollection).count()).toBe(1);
+    });
+
     describe("with timeline variables", () => {
       it("repeats all trials for each set of variables", async () => {
         const xValues = [];

packages/jspsych/src/timeline/Trial.spec.ts

@@ -725,6 +725,20 @@ describe("Trial", () => {
       expect(trial.getResult()).toEqual(expect.objectContaining({ my: "result" }));
       expect(trial.getResults()).toEqual([expect.objectContaining({ my: "result" })]);
     });
+
+    it("does not return the result when the `record_data` trial parameter is `false`", async () => {
+      TestPlugin.setManualFinishTrialMode();
+      const trial = createTrial({ type: TestPlugin, record_data: false });
+      trial.run();
+
+      expect(trial.getResult()).toBeUndefined();
+      expect(trial.getResults()).toEqual([]);
+
+      await TestPlugin.finishTrial();
+
+      expect(trial.getResult()).toBeUndefined();
+      expect(trial.getResults()).toEqual([]);
+    });
   });
 
   describe("evaluateTimelineVariable()", () => {

packages/jspsych/src/timeline/Trial.ts

@@ -299,14 +299,16 @@ export class Trial extends TimelineNode {
   }
 
   /**
-   * Returns the result object of this trial or `undefined` if the result is not yet known.
+   * Returns the result object of this trial or `undefined` if the result is not yet known or the
+   * `record_data` trial parameter is `false`.
    */
   public getResult() {
-    return this.result;
+    return this.getParameterValue("record_data") === false ? undefined : this.result;
   }
 
   public getResults() {
-    return this.result ? [this.result] : [];
+    const result = this.getResult();
+    return result ? [result] : [];
   }
 
   /**

packages/jspsych/src/timeline/index.ts

@@ -55,6 +55,11 @@ export interface TrialDescription extends Record<string, any> {
   /** https://www.jspsych.org/latest/overview/extensions/ */
   extensions?: Parameter<TrialExtensionsConfiguration>;
 
+  /**
+   * Whether to record the data of this trial. Defaults to `true`.
+   */
+  record_data?: Parameter<boolean>;
+
   // Events
 
   /** https://www.jspsych.org/latest/overview/events/#on_start-trial */

packages/jspsych/tests/data/recorddataparameter.test.ts

@@ -0,0 +1,86 @@
+import htmlKeyboardResponse from "@jspsych/plugin-html-keyboard-response";
+import { pressKey, startTimeline } from "@jspsych/test-utils";
+
+import { initJsPsych } from "../../src";
+
+describe("The record_data parameter", () => {
+  it("Defaults to true", async () => {
+    const { getData } = await startTimeline([
+      {
+        type: htmlKeyboardResponse,
+        stimulus: "<p>foo</p>",
+      },
+    ]);
+
+    await pressKey(" ");
+
+    expect(getData().count()).toBe(1);
+  });
+
+  it("Can be set to false to prevent the data from being recorded", async () => {
+    const onFinish = jest.fn();
+    const onTrialFinish = jest.fn();
+    const onDataUpdate = jest.fn();
+
+    const { getData } = await startTimeline(
+      [
+        {
+          type: htmlKeyboardResponse,
+          stimulus: "<p>foo</p>",
+          record_data: false,
+          on_finish: onFinish,
+        },
+      ],
+      { on_trial_finish: onTrialFinish, on_data_update: onDataUpdate }
+    );
+
+    await pressKey(" ");
+
+    expect(getData().count()).toBe(0);
+    expect(onFinish).toHaveBeenCalledWith(undefined);
+    expect(onTrialFinish).toHaveBeenCalledWith(undefined);
+    expect(onDataUpdate).not.toHaveBeenCalled();
+  });
+
+  it("Can be set as a timeline variable", async () => {
+    const jsPsych = initJsPsych();
+    const { getData } = await startTimeline(
+      [
+        {
+          timeline: [
+            {
+              type: htmlKeyboardResponse,
+              stimulus: "<p>foo</p>",
+              record_data: jsPsych.timelineVariable("record_data"),
+            },
+          ],
+          timeline_variables: [{ record_data: true }, { record_data: false }],
+        },
+      ],
+      jsPsych
+    );
+
+    await pressKey(" ");
+    await pressKey(" ");
+
+    expect(getData().count()).toBe(1);
+  });
+
+  it("Can be set as a function", async () => {
+    const jsPsych = initJsPsych();
+    const { getData } = await startTimeline(
+      [
+        {
+          type: htmlKeyboardResponse,
+          stimulus: "<p>foo</p>",
+          record_data: () => false,
+        },
+      ],
+      jsPsych
+    );
+
+    await pressKey(" ");
+
+    expect(getData().count()).toBe(0);
+  });
+});