Merge pull request #2897 from jspsych/plugin-visual-search-add-fixed-offset

Add options (`randomize_item_locations` and `location_first_item`) to visual-search-circle plugin

.changeset/nervous-carrots-raise.md

@@ -0,0 +1,5 @@
+---
+"@jspsych/plugin-visual-search-circle": minor
+---
+
+Add options (`randomize_item_locations` and `location_first_item`) to allow for fixed locations of the item array across trials.

docs/plugins/visual-search-circle.md

@@ -32,6 +32,8 @@ The `target_present` and `fixation_image` parameters must always be specified. O
 | target_absent_key  | string          | 'f'           | The key to press if the target is not present in the search array. |
 | trial_duration     | numeric         | null          | The maximum amount of time the participant is allowed to search before the trial will continue. A value of null will allow the participant to search indefinitely. |
 | fixation_duration  | numeric         | 1000          | How long to show the fixation image for before the search array (in milliseconds). |
+| randomize_item_locations | bool      | true      | Whether to use randomized locations on the circle for the items. If `false`, then the first item will always show at the location specified by `location_first_item`.
+| location_first_item | numeric | 0 | If `randomize_item_locations` is `false`, the location of the first item on the circle, in degrees. 0 degrees is above the fixation, and moving clockwise in the positive direction.
 | response_ends_trial| boolean         | true         | If true, the trial will end when the participant makes a response. |
 
 ## Data Generated

examples/jspsych-visual-search-circle.html

@@ -51,15 +51,27 @@
       timeline: [trial_1, trial_2, trial_3]
     };
 
-    // example using arbitrary image array
+    // example putting the first location at 90 degrees (right of the fixation)
     var trial_4 = {
+      type: jsPsychVisualSearchCircle,
+      target: 'img/backwardN.gif',
+      foil: 'img/normalN.gif',
+      fixation_image: 'img/fixation.gif',
+      target_present: true,
+      set_size: 3,
+      randomize_item_locations: false,
+      location_first_item: 90
+    };
+
+    // example using arbitrary image array
+    var trial_5 = {
       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]);
+    jsPsych.run([preload_images, intro, trials, trial_4, trial_5]);
 
   </script>
 </html>

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

@@ -100,6 +100,21 @@ const info = <const>{
       type: ParameterType.INT,
       default: 1000,
     },
+    /** Whether to use randomized locations on the circle for the items. If `false`, then the first item will always show at the location specified by `location_first_item`. */
+    randomize_item_locations: {
+      type: ParameterType.BOOL,
+      pretty_name: "Randomize item locations",
+      default: true,
+    },
+    /** 
+     * If `randomize_item_locations` is `false`, the location of the first item on the circle, in degrees.
+     * 0 degrees is above the fixation, and moving clockwise in the positive direction.
+    */
+    location_first_item: {
+      type: ParameterType.INT,
+      pretty_name: "Location first item",
+      default: 0,
+    },
     /** If true, the trial will end when the participant makes a response. */
     response_ends_trial: {
       type: ParameterType.BOOL,
@@ -140,7 +155,7 @@ type Info = typeof info;
 /**
  * This plugin presents a customizable visual-search task modelled after [Wang, Cavanagh, & Green (1994)](http://dx.doi.org/10.3758/BF03206946).
  * The participant indicates whether or not a target is present among a set of distractors. The stimuli are displayed in a circle, evenly-spaced,
- * equidistant from a fixation point. Here is an example using normal and backward Ns:
+ * equidistant from a fixation point. 
  *
  * @author Josh de Leeuw
  * @see {@link https://www.jspsych.org/latest/plugins/visual-search-circle/ visual-search-circle plugin documentation on jspsych.org}
@@ -275,10 +290,6 @@ class VisualSearchCirclePlugin implements JsPsychPlugin<Info> {
           end_trial();
         }, trial.trial_duration);
       }
-
-      function clear_display() {
-        display_element.innerHTML = "";
-      }
     };
   }
 
@@ -303,11 +314,13 @@ class VisualSearchCirclePlugin implements JsPsychPlugin<Info> {
     var hstimw = stimw / 2;
 
     var display_locs = [];
-    var random_offset = Math.floor(Math.random() * 360);
+    var offset = trial.randomize_item_locations 
+      ? Math.floor(Math.random() * 360)
+      : trial.location_first_item - 180; // makes it so 0 is up, moving clockwise
     for (var i = 0; i < n_locs; i++) {
       display_locs.push([
-        Math.floor(paper_size / 2 + this.cosd(random_offset + i * (360 / n_locs)) * radi - hstimw),
+        Math.floor(paper_size / 2 + this.cosd(offset + i * (360 / n_locs)) * radi - hstimw),
-        Math.floor(paper_size / 2 - this.sind(random_offset + i * (360 / n_locs)) * radi - hstimh),
+        Math.floor(paper_size / 2 - this.sind(offset + i * (360 / n_locs)) * radi - hstimh),
       ]);
     }
     return display_locs;