Finished packages with questions about plugin-serial grids

packages/plugin-reconstruction/src/index.ts

@@ -1,56 +1,71 @@
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
+import { parameterPathArrayToString } from "jspsych/src/timeline/util";
+
+import { version } from "../package.json";
 
 const info = <const>{
   name: "reconstruction",
+  version: version,
   parameters: {
     /** A function with a single parameter that returns an HTML-formatted string representing the stimulus. */
     stim_function: {
       type: ParameterType.FUNCTION,
-      pretty_name: "Stimulus function",
       default: undefined,
     },
     /** The starting value of the stimulus parameter. */
     starting_value: {
       type: ParameterType.FLOAT,
-      pretty_name: "Starting value",
       default: 0.5,
     },
     /** The change in the stimulus parameter caused by pressing one of the modification keys. */
     step_size: {
       type: ParameterType.FLOAT,
-      pretty_name: "Step size",
       default: 0.05,
     },
     /** The key to press for increasing the parameter value. */
     key_increase: {
       type: ParameterType.KEY,
-      pretty_name: "Key increase",
       default: "h",
     },
     /** The key to press for decreasing the parameter value. */
     key_decrease: {
       type: ParameterType.KEY,
-      pretty_name: "Key decrease",
       default: "g",
     },
     /** The text that appears on the button to finish the trial. */
     button_label: {
       type: ParameterType.STRING,
-      pretty_name: "Button label",
       default: "Continue",
     },
   },
+  data: {
+    /** The starting value of the stimulus parameter. */
+    start_value: {
+      type: ParameterType.INT,
+    },
+    /** The final value of the stimulus parameter. */
+    final_value: {
+      type: ParameterType.INT,
+    },
+    /** The length of time, in milliseconds, that the trial lasted. */
+    rt: {
+      type: ParameterType.INT,
+    },
+  },
 };
 
 type Info = typeof info;
 
 /**
- * **reconstruction**
+ * This plugin allows a participant to interact with a stimulus by modifying a parameter of the stimulus and observing
+ * the change in the stimulus in real-time.
  *
- * jsPsych plugin for a reconstruction task where the subject recreates a stimulus from memory
+ * The stimulus must be defined through a function that returns an HTML-formatted string. The function should take a
+ * single value, which is the parameter that can be modified by the participant. The value can only range from 0 to 1.
+ * See the example at the bottom of the page for a sample function.
  *
  * @author Josh de Leeuw
- * @see {@link https://www.jspsych.org/plugins/jspsych-reconstruction/ reconstruction plugin documentation on jspsych.org}
+ * @see {@link https://www.jspsych.org/latest/plugins/reconstruction/ reconstruction plugin documentation on jspsych.org}
  */
 class ReconstructionPlugin implements JsPsychPlugin<Info> {
   static info = info;

packages/plugin-resize/src/index.ts

@@ -1,56 +1,67 @@
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
 
+import { version } from "../package.json";
+
 const info = <const>{
   name: "resize",
+  version: version,
   parameters: {
-    /** The height of the item to be measured. */
+    /** The height of the item to be measured. Any units can be used
+     * as long as you are consistent with using the same units for
+     * all parameters. */
     item_height: {
       type: ParameterType.INT,
-      pretty_name: "Item height",
       default: 1,
     },
     /** The width of the item to be measured. */
     item_width: {
       type: ParameterType.INT,
-      pretty_name: "Item width",
       default: 1,
     },
     /** The content displayed below the resizable box and above the button. */
     prompt: {
       type: ParameterType.HTML_STRING,
-      pretty_name: "Prompt",
       default: null,
     },
     /** After the scaling factor is applied, this many pixels will equal one unit of measurement. */
     pixels_per_unit: {
       type: ParameterType.INT,
-      pretty_name: "Pixels per unit",
       default: 100,
     },
-    /** The initial size of the box, in pixels, along the larget dimension. */
+    /** The initial size of the box, in pixels, along the largest dimension.
+     * The aspect ratio will be set automatically to match the item width and height. */
     starting_size: {
       type: ParameterType.INT,
-      pretty_name: "Starting size",
       default: 100,
     },
     /** Label to display on the button to complete calibration. */
     button_label: {
       type: ParameterType.STRING,
-      pretty_name: "Button label",
       default: "Continue",
     },
   },
+  data: {
+    /** Final width of the resizable div container, in pixels. */
+    final_width_px: {
+      type: ParameterType.INT,
+    },
+    /** Scaling factor that will be applied to the div containing jsPsych content. */
+    scale_factor: {
+      type: ParameterType.FLOAT,
+    },
+  },
 };
 
 type Info = typeof info;
 
 /**
- * **resize**
  *
- * jsPsych plugin for controlling the real world size of the display
+ * This plugin displays a resizable div container that allows the user to drag until the container is the same size as the
+ * item being measured. Once the user measures the item as close as possible, clicking the button sets a scaling factor
+ * for the div containing jsPsych content. This causes the stimuli that follow to have a known size, independent of monitor resolution.
  *
  * @author Steve Chao
- * @see {@link https://www.jspsych.org/plugins/jspsych-resize/ resize plugin documentation on jspsych.org}
+ * @see {@link https://www.jspsych.org/latest/plugins/resize/ resize plugin documentation on jspsych.org}
  */
 class ResizePlugin implements JsPsychPlugin<Info> {
   static info = info;

packages/plugin-same-different-html/src/index.ts

@@ -1,44 +1,43 @@
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
 
+import { version } from "../package.json";
+
 const info = <const>{
   name: "same-different-html",
+  version: version,
   parameters: {
-    /** Array containing the HTML content to be displayed. */
+    /** A pair of stimuli, represented as an array with two entries, one for
+     * each stimulus. A stimulus is a string containing valid HTML markup.
+     * Stimuli will be shown in the order that they are defined in the array. */
     stimuli: {
       type: ParameterType.HTML_STRING,
-      pretty_name: "Stimuli",
       default: undefined,
       array: true,
     },
     /** Correct answer: either "same" or "different". */
     answer: {
       type: ParameterType.SELECT,
-      pretty_name: "Answer",
       options: ["same", "different"],
       default: undefined,
     },
     /** The key that subjects should press to indicate that the two stimuli are the same. */
     same_key: {
       type: ParameterType.KEY,
-      pretty_name: "Same key",
       default: "q",
     },
     /** The key that subjects should press to indicate that the two stimuli are different. */
     different_key: {
       type: ParameterType.KEY,
-      pretty_name: "Different key",
       default: "p",
     },
-    /** How long to show the first stimulus for in milliseconds. If null, then the stimulus will remain on the screen until any keypress is made. */
+    /** How long to show the first stimulus for in milliseconds. If the value of this parameter is null then the stimulus will be shown until the participant presses any key. */
     first_stim_duration: {
       type: ParameterType.INT,
-      pretty_name: "First stimulus duration",
       default: 1000,
     },
     /** How long to show a blank screen in between the two stimuli. */
     gap_duration: {
       type: ParameterType.INT,
-      pretty_name: "Gap duration",
       default: 500,
     },
     /** How long to show the second stimulus for in milliseconds. If null, then the stimulus will remain on the screen until a valid response is made. */
@@ -47,24 +46,47 @@ const info = <const>{
       pretty_name: "Second stimulus duration",
       default: 1000,
     },
-    /** Any content here will be displayed below the stimulus. */
+    /** This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press). */
     prompt: {
       type: ParameterType.HTML_STRING,
-      pretty_name: "Prompt",
       default: null,
     },
   },
+  data: {
+    /**  An array of length 2 containing the HTML-formatted content that the participant saw for each trial. This will be encoded as a JSON string
+     * when data is saved using the `.json()` or `.csv()` functions. */
+    stimulus: {
+      type: ParameterType.HTML_STRING,
+      array: true,
+    },
+    /** Indicates which key the participant pressed. */
+    response: {
+      type: ParameterType.STRING,
+    },
+    /** The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. */
+    rt: {
+      type: ParameterType.INT,
+    },
+    /** `true` if the participant's response matched the `answer` for this trial.  */
+    correct: {
+      type: ParameterType.BOOL,
+    },
+    /** The correct answer to the trial, either `'same'` or `'different'`. */
+    answer: {
+      type: ParameterType.STRING,
+    },
+  },
 };
 
 type Info = typeof info;
 
 /**
- * **same-different-html**
- *
- * jsPsych plugin for showing two HTML stimuli sequentially and getting a same / different judgment via keypress
+ * The same-different-html plugin displays two stimuli sequentially. Stimuli are HTML objects.
+ * The participant responds using the keyboard, and indicates whether the stimuli were the
+ * same or different. Same does not necessarily mean identical; a category judgment could be made, for example.
  *
  * @author Josh de Leeuw
- * @see {@link https://www.jspsych.org/plugins/jspsych-same-different-html/ same-different-html plugin documentation on jspsych.org}
+ * @see {@link https://www.jspsych.org/latest/plugins/same-different-html/ same-different-html plugin documentation on jspsych.org}
  */
 class SameDifferentHtmlPlugin implements JsPsychPlugin<Info> {
   static info = info;

packages/plugin-same-different-image/src/index.ts

@@ -1,70 +1,95 @@
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
 
+import { version } from "../package.json";
+
 const info = <const>{
   name: "same-different-image",
+  version: version,
   parameters: {
-    /** Array containing the images to be displayed. */
+    /** A pair of stimuli, represented as an array with two entries,
+     * one for each stimulus. The stimulus is a path to an image file.
+     * Stimuli will be shown in the order that they are defined in the array. */
     stimuli: {
       type: ParameterType.IMAGE,
-      pretty_name: "Stimuli",
       default: undefined,
       array: true,
     },
-    /** Correct answer: either "same" or "different". */
+    /** Either `'same'` or `'different'`. */
     answer: {
       type: ParameterType.SELECT,
-      pretty_name: "Answer",
       options: ["same", "different"],
       default: undefined,
     },
     /** The key that subjects should press to indicate that the two stimuli are the same. */
     same_key: {
       type: ParameterType.KEY,
-      pretty_name: "Same key",
       default: "q",
     },
     /** The key that subjects should press to indicate that the two stimuli are different. */
     different_key: {
       type: ParameterType.KEY,
-      pretty_name: "Different key",
       default: "p",
     },
-    /** How long to show the first stimulus for in milliseconds. If null, then the stimulus will remain on the screen until any keypress is made. */
+    /** How long to show the first stimulus for in milliseconds. If the value of this parameter is null then the stimulus will be shown until the participant presses any key. */
     first_stim_duration: {
       type: ParameterType.INT,
-      pretty_name: "First stimulus duration",
       default: 1000,
     },
     /** How long to show a blank screen in between the two stimuli */
     gap_duration: {
       type: ParameterType.INT,
-      pretty_name: "Gap duration",
       default: 500,
     },
     /** How long to show the second stimulus for in milliseconds. If null, then the stimulus will remain on the screen until a valid response is made. */
     second_stim_duration: {
       type: ParameterType.INT,
-      pretty_name: "Second stimulus duration",
       default: 1000,
     },
-    /** Any content here will be displayed below the stimulus. */
+    /** This string can contain HTML markup. Any content here will be displayed
+     * below the stimulus. The intention is that it can be used to provide a
+     * reminder about the action the participant is supposed to take
+     * (e.g., which key to press). */
     prompt: {
       type: ParameterType.HTML_STRING,
-      pretty_name: "Prompt",
       default: null,
     },
   },
+  data: {
+    /** An array of length 2 containing the paths to the image files that the participant saw for each trial.
+     * This will be encoded as a JSON string when data is saved using the `.json()` or `.csv()` functions. */
+    stimulus: {
+      type: ParameterType.STRING,
+      array: true,
+    },
+    /** Indicates which key the participant pressed.  */
+    response: {
+      type: ParameterType.STRING,
+    },
+    /** The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. */
+    rt: {
+      type: ParameterType.INT,
+    },
+    /** `true` if the participant's response matched the `answer` for this trial. */
+    correct: {
+      type: ParameterType.BOOL,
+    },
+    /** The correct answer to the trial, either `'same'` or `'different'`. */
+    answer: {
+      type: ParameterType.STRING,
+    },
+  },
 };
 
 type Info = typeof info;
 
 /**
- * **same-different-image**
- *
- * jsPsych plugin for showing two image stimuli sequentially and getting a same / different judgment via keypress
+ * The same-different-image plugin displays two stimuli sequentially. Stimuli are images.
+ * The participant responds using the keyboard, and indicates whether the stimuli were the
+ * same or different. Same does not necessarily mean identical; a category judgment could be
+ * made, for example.
  *
  * @author Josh de Leeuw
- * @see {@link https://www.jspsych.org/plugins/jspsych-same-different-image/ same-different-image plugin documentation on jspsych.org}
+ * @see {@link https://www.jspsych.org/latest/plugins/same-different-image/ same-different-image plugin documentation on jspsych.org}
  */
 class SameDifferentImagePlugin implements JsPsychPlugin<Info> {
   static info = info;