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)

docs/demos/jspsych-visual-search-circle-demo2.html

@@ -49,13 +49,11 @@
 
       var trial = {
         type: 'visual-search-circle',
-        target: 'img/elephant.png',
+        stimuli: ['img/elephant.png', 'img/lion.png', 'img/monkey.png'],
-        foil: ['img/lion.png', 'img/monkey.png'],
         fixation_image: 'img/fixation.gif',
         target_present_key: 'e',
         target_absent_key: 'n',
-        target_present: true,
+        target_present: true
-        set_size: 3
       }
 
       var trial_loop = {

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?                   |
+| 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. |
-| set_size           | numeric         | *undefined*   | How many items should be displayed?      |
+| 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. |
-| target             | string          | *undefined*   | Path to image file that is the search target. |
+| 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.  |
-| 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. |
+| 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. |
-| fixation_image     | string          | *undefined*   | Path to image file that is a fixation target. |
+| 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. |

examples/jspsych-visual-search-circle.html

@@ -27,6 +27,7 @@
       stimulus: '<p>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.</p><p>Press any key to begin.</p>'
     };
 
+    // 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]);
 
   </script>
 </html>

packages/plugin-visual-search-circle/src/index.ts

@@ -3,37 +3,48 @@ import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
 const info = <const>{
   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<Info> {
       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<Info> {
       'px"></div>';
     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<Info> {
     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 +=
           "<img src='" +