diff --git a/.changeset/lucky-glasses-crash.md b/.changeset/lucky-glasses-crash.md new file mode 100644 index 0000000000..54522df1e0 --- /dev/null +++ b/.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. + diff --git a/docs/overview/data.md b/docs/overview/data.md index 4e2b0e3634..e4676b3134 100644 --- a/docs/overview/data.md +++ b/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). diff --git a/docs/overview/plugins.md b/docs/overview/plugins.md index 5d79dd1cb1..534ee7cbf7 100644 --- a/docs/overview/plugins.md +++ b/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 diff --git a/packages/jspsych/src/JsPsych.ts b/packages/jspsych/src/JsPsych.ts index b9f34911ab..9f5a6a8950 100644 --- a/packages/jspsych/src/JsPsych.ts +++ b/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(); diff --git a/packages/jspsych/src/timeline/Timeline.spec.ts b/packages/jspsych/src/timeline/Timeline.spec.ts index b94f595f98..b87e4f4929 100644 --- a/packages/jspsych/src/timeline/Timeline.spec.ts +++ b/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 = []; diff --git a/packages/jspsych/src/timeline/Trial.spec.ts b/packages/jspsych/src/timeline/Trial.spec.ts index 83cfc29795..0a3dda8769 100644 --- a/packages/jspsych/src/timeline/Trial.spec.ts +++ b/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()", () => { diff --git a/packages/jspsych/src/timeline/Trial.ts b/packages/jspsych/src/timeline/Trial.ts index c3e4b1a508..94b6b5dd0c 100644 --- a/packages/jspsych/src/timeline/Trial.ts +++ b/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] : []; } /** diff --git a/packages/jspsych/src/timeline/index.ts b/packages/jspsych/src/timeline/index.ts index 6fafa25c13..abf13c11be 100644 --- a/packages/jspsych/src/timeline/index.ts +++ b/packages/jspsych/src/timeline/index.ts @@ -55,6 +55,11 @@ export interface TrialDescription extends Record { /** https://www.jspsych.org/latest/overview/extensions/ */ extensions?: Parameter; + /** + * Whether to record the data of this trial. Defaults to `true`. + */ + record_data?: Parameter; + // Events /** https://www.jspsych.org/latest/overview/events/#on_start-trial */ diff --git a/packages/jspsych/tests/data/recorddataparameter.test.ts b/packages/jspsych/tests/data/recorddataparameter.test.ts new file mode 100644 index 0000000000..cf08561f6c --- /dev/null +++ b/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: "

foo

", + }, + ]); + + 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: "

foo

", + 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: "

foo

", + 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: "

foo

", + record_data: () => false, + }, + ], + jsPsych + ); + + await pressKey(" "); + + expect(getData().count()).toBe(0); + }); +});