From 0d6e7074f2b1645a119890c12410c29ecbe97434 Mon Sep 17 00:00:00 2001 From: Becky Gilbert Date: Fri, 10 Sep 2021 15:24:13 -0700 Subject: [PATCH] add stimuli parameter option, foil parameter must be string (not array), foil is now always repeated up to set_size or set_size - 1 (depending on target_present value) --- .../jspsych-visual-search-circle-demo2.html | 6 +- docs/plugins/jspsych-visual-search-circle.md | 18 ++-- examples/jspsych-visual-search-circle.html | 21 +++-- .../plugin-visual-search-circle/src/index.ts | 94 ++++++++++--------- 4 files changed, 77 insertions(+), 62 deletions(-) diff --git a/docs/demos/jspsych-visual-search-circle-demo2.html b/docs/demos/jspsych-visual-search-circle-demo2.html index ae7b9307..43970778 100644 --- a/docs/demos/jspsych-visual-search-circle-demo2.html +++ b/docs/demos/jspsych-visual-search-circle-demo2.html @@ -49,13 +49,11 @@ var trial = { type: 'visual-search-circle', - target: 'img/elephant.png', - foil: ['img/lion.png', 'img/monkey.png'], + stimuli: ['img/elephant.png', 'img/lion.png', 'img/monkey.png'], fixation_image: 'img/fixation.gif', target_present_key: 'e', target_absent_key: 'n', - target_present: true, - set_size: 3 + target_present: true } var trial_loop = { diff --git a/docs/plugins/jspsych-visual-search-circle.md b/docs/plugins/jspsych-visual-search-circle.md index c30c435a..beb1f0a6 100644 --- a/docs/plugins/jspsych-visual-search-circle.md +++ b/docs/plugins/jspsych-visual-search-circle.md @@ -6,15 +6,21 @@ This plugin presents a customizable visual-search task modelled after [Wang, Cav ## Parameters -In addition to the [parameters available in all plugins](/overview/plugins#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable. +In addition to the [parameters available in all plugins](/overview/plugins#parameters-available-in-all-plugins), this plugin accepts the following parameters. The set of images to display must be defined in one of two ways: +* The `target`, `foil` and `set_size` parameters: the combination of these parameters can be used to construct a 'classic' visual search task, where there is a single foil/distractor image that makes up all of the images in the set, with the exception of the target image if it is present. +OR +* The `stimuli` parameter: this array that can be used to present any arbitrary set of image files, with or without the target image, with any number of different foils/distractors, and with any number of repeated images. + +The `target_present` and `fixation_image` parameters must always be specified. Other parameters can be left unspecified if the default value is acceptable. | Parameter | Type | Default Value | Description | | ------------------ | --------------- | ------------- | ---------------------------------------- | -| target_present | boolean | *undefined* | Is the target present? | -| set_size | numeric | *undefined* | How many items should be displayed? | -| target | string | *undefined* | Path to image file that is the search target. | -| foil | array | *undefined* | Array containing one or more paths to image files that make up the foils/distractors. If the foil array contains only one image and the set_size is greater than 1, then this image will be repeated for all distractors up to the set_size. If the foil array contains more than one image, then each image in the array will be used as one distractor. | -| fixation_image | string | *undefined* | Path to image file that is a fixation target. | +| target | string | null | Path to image file that is the search target. This parameter must specified when the stimuli set is defined using the `target`, `foil` and `set_size` parameters, but should NOT be specified when using the `stimuli` parameter. | +| foil | string | null | Path to image file that is the foil/distractor. This image will be repeated for all distractors up to the `set_size` value. This parameter must specified when the stimuli set is defined using the `target`, `foil` and `set_size` parameters, but should NOT be specified when using the `stimuli` parameter. | +| set_size | numeric | null | How many items should be displayed, including the target when `target_present` is `true`? The foil image will be repeated up to this value when `target_present` is `false`, or up to `set_size - 1` when `target_present` is `true`. This parameter must specified when using the `target`, `foil` and `set_size` parameters to define the stimuli set, but should NOT be specified when using the `stimuli` parameter. | +| stimuli | array of images | null | Array containing all of the image files to be displayed. This parameter must be specified when NOT using the `target`, `foil`, and `set_size` parameters to define the stimuli set. | +| target_present | boolean | *undefined* | Is the target present? This parameter must always be specified. When using the `target`, `foil` and `set_size` parameters, `false` means that the foil image will be repeated up to the set_size, and `true` means that the target will be presented along with the foil image repeated up to set_size - 1. When using the `stimuli` parameter, this parameter is only used to determine the response accuracy. | +| fixation_image | string | *undefined* | Path to image file that is a fixation target. This parameter must always be specified. | | target_size | array | `[50, 50]` | Two element array indicating the height and width of the search array element images. | | fixation_size | array | `[16, 16]` | Two element array indicating the height and width of the fixation image. | | circle_diameter | numeric | 250 | The diameter of the search array circle in pixels. | diff --git a/examples/jspsych-visual-search-circle.html b/examples/jspsych-visual-search-circle.html index 307c42b5..8e26b333 100644 --- a/examples/jspsych-visual-search-circle.html +++ b/examples/jspsych-visual-search-circle.html @@ -27,6 +27,7 @@ stimulus: '

You will see a set of Ns on the following screens. Press j if there is a backwards N. If there is no backwards N press f.

Press any key to begin.

' }; + // examples using target, foil, and set_size parameters to define the visual search set var trial_1 = { target_present: true, set_size: 4 @@ -42,21 +43,23 @@ set_size: 6 }; - var trial_4 = { - target_present: false, - foil: ['img/1.gif', 'img/2.gif', 'img/3.gif'], // example of using multiple foils. - set_size: 3 - }; - var trials = { type: jsPsychVisualSearchCircle, target: 'img/backwardN.gif', - foil: ['img/normalN.gif'], + foil: 'img/normalN.gif', fixation_image: 'img/fixation.gif', - timeline: [trial_1, trial_2, trial_3, trial_4] + timeline: [trial_1, trial_2, trial_3] }; - jsPsych.run([preload_images, intro, trials]); + // example using arbitrary image array + var trial_4 = { + type: jsPsychVisualSearchCircle, + stimuli: ['img/backwardN.gif', 'img/normalN.gif', 'img/1.gif', 'img/2.gif', 'img/3.gif'], + fixation_image: 'img/fixation.gif', + target_present: true + }; + + jsPsych.run([preload_images, intro, trials, trial_4]); diff --git a/packages/plugin-visual-search-circle/src/index.ts b/packages/plugin-visual-search-circle/src/index.ts index 1b030d3a..1eceb8dc 100644 --- a/packages/plugin-visual-search-circle/src/index.ts +++ b/packages/plugin-visual-search-circle/src/index.ts @@ -3,37 +3,48 @@ import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych"; const info = { name: "visual-search-circle", parameters: { - /** The target image to be displayed. */ + /** The target image to be displayed. This must specified when using the target, foil and set_size parameters to define the stimuli set, rather than the stimuli parameter. */ target: { type: ParameterType.IMAGE, pretty_name: "Target", - default: undefined, + default: null, }, - /** Path to image file(s) that is/are the foils/distractors. */ + /** The image to use as the foil/distractor. This must specified when using the target, foil and set_size parameters to define the stimuli set, rather than the stimuli parameter. */ foil: { type: ParameterType.IMAGE, pretty_name: "Foil", - default: undefined, + default: null, + }, + /** How many items should be displayed, including the target when target_present is true? This must specified when using the target, foil and set_size parameters to define the stimuli set, rather than the stimuli parameter. */ + set_size: { + type: ParameterType.INT, + pretty_name: "Set size", + default: null, + }, + /** Array containing one or more image files to be displayed. This only needs to be specified when NOT using the target, foil, and set_size parameters to define the stimuli set. */ + stimuli: { + type: ParameterType.IMAGE, + pretty_name: "Stimuli", + default: null, array: true, }, + /** + * Is the target present? + * When using the target, foil and set_size parameters, false means that the foil image will be repeated up to the set_size, + * and if true, then the target will be presented along with the foil image repeated up to set_size - 1. + * When using the stimuli parameter, this parameter is only used to determine the response accuracy. + */ + target_present: { + type: ParameterType.BOOL, + pretty_name: "Target present", + default: undefined, + }, /** Path to image file that is a fixation target. */ fixation_image: { type: ParameterType.IMAGE, pretty_name: "Fixation image", default: undefined, }, - /** How many items should be displayed? */ - set_size: { - type: ParameterType.INT, - pretty_name: "Set size", - default: undefined, - }, - /** Is the target present? */ - target_present: { - type: ParameterType.BOOL, - pretty_name: "Target present", - default: true, - }, /** Two element array indicating the height and width of the search array element images. */ target_size: { type: ParameterType.INT, @@ -116,9 +127,32 @@ class VisualSearchCirclePlugin implements JsPsychPlugin { Math.floor(paper_size / 2 - trial.fixation_size[1] / 2), ]; + // check for correct combination of parameters and create stimuli set + var possible_display_locs: number; + var to_present = []; + if (trial.target !== null && trial.foil !== null && trial.set_size !== null) { + possible_display_locs = trial.set_size; + if (trial.target_present) { + for (var i = 0; i < trial.set_size - 1; i++) { + to_present.push(trial.foil); + } + to_present.push(trial.target); + } else { + for (var i = 0; i < trial.set_size; i++) { + to_present.push(trial.foil); + } + } + } else if (trial.stimuli !== null) { + possible_display_locs = trial.stimuli.length; + to_present = trial.stimuli; + } else { + console.error( + "Error in visual-search-circle plugin: you must specify an array of images via the stimuli parameter OR specify the target, foil and set_size parameters." + ); + } + // possible stimulus locations on the circle var display_locs = []; - var possible_display_locs = trial.set_size; var random_offset = Math.floor(Math.random() * 360); for (var i = 0; i < possible_display_locs; i++) { display_locs.push([ @@ -140,24 +174,6 @@ class VisualSearchCirclePlugin implements JsPsychPlugin { 'px">'; var paper = display_element.querySelector("#jspsych-visual-search-circle-container"); - // check distractors - single image to be repeated up to set_size? - var foil_arr = []; - if (Array.isArray(trial.foil)) { - if (trial.foil.length == 1 && trial.set_size > 1) { - const fa = []; - for (var i = 0; i < trial.set_size; i++) { - fa.push(trial.foil[0]); - } - foil_arr = fa; - } else { - foil_arr = trial.foil; - } - } else { - console.error( - "Error in visual-search-circle plugin: foil parameter must be an array containing one or more image file paths (strings)." - ); - } - const show_fixation = () => { // show fixation //var fixation = paper.image(trial.fixation_image, fix_loc[0], fix_loc[1], trial.fixation_size[0], trial.fixation_size[1]); @@ -199,14 +215,6 @@ class VisualSearchCirclePlugin implements JsPsychPlugin { show_fixation(); const show_search_array = () => { - var search_array_images = []; - - var to_present = []; - if (trial.target_present) { - to_present.push(trial.target); - } - to_present = to_present.concat(foil_arr); - for (var i = 0; i < display_locs.length; i++) { paper.innerHTML += "