plugin-histogram-button-response

README.md

@@ -52,6 +52,7 @@ Plugin | Contributor | Description
 [video-several-keyboard-responses](https://github.com/jspsych/jspsych-contrib/blob/main/packages/plugin-video-several-keyboard-responses/README.md) | [Maria Emine Nylund](https://github.com/marianylund) | jsPsych plugin for playing a video file and getting several keyboard responses 
 [vsl-animate-occlusion](https://github.com/jspsych/jspsych-contrib/blob/main/packages/plugin-vsl-animate-occlusion/README.md) | [Josh de Leeuw](https://github.com/jodeleeuw) | he VSL (visual statistical learning) animate occlusion plugin displays an animated sequence of shapes that disappear behind an occluding rectangle while they change from one shape to another. 
 [vsl-grid-scene](https://github.com/jspsych/jspsych-contrib/blob/main/packages/plugin-vsl-grid-scene/README.md) | [Josh de Leeuw](https://github.com/jodeleeuw) | The VSL (visual statistical learning) grid scene plugin displays images arranged in a grid. 
+[histogram-button-response](https://github.com/jspsych/jspsych-contrib/blob/main/packages/plugin-histogram-button-response/README.md) | [Courtney B. Hilton](https://github.com/courtney-bryce-hilton) | This plugin displays an interactive histogram to the participant.
 
 
 ### Extensions

packages/plugin-histogram-button-response/CITATION.cff

@@ -0,0 +1,40 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Courtney B. Hilton" # Replace with last name
+    given-names: "Courtney B. Hilton" # Replace with first name
+    name-particle: "Courtney B. Hilton" # Replace with name particle(s)
+    orcid: "https://orcid.org/0000-0000-0000-0000" # Replace with ORCID
+# More  authors can be listed here in the same format as above
+contact: # Contact person for this extension
+  - family-names: "Courtney B. Hilton"
+    given-names: "Courtney B. Hilton"
+    email: "{email}" # Replace with contact person's email
+    orcid: "https://orcid.org/0000-0000-0000-0000" # Replace with contact person's ORCID
+title: "jsPsychPluginHistogramButtonResponse"
+version: 0.0.0
+doi: 10.5281/zenodo.1234 # Replace with DOI
+date-released: 2000-01-01
+url: "{softwareUrl}" # Replace with URL to this extension
+
+# If you wish to cite a paper on this extension instead, you can use the following template:
+preferred-citation:
+  authors:
+    - family-names: "Courtney B. Hilton"
+      given-names: "Courtney B. Hilton"
+      name-particle: "Courtney B. Hilton"
+      orcid: "https://orcid.org/0000-0000-0000-0000"
+  # More authors can be listed here in the same format as above
+  date-published: 2023-05-11
+  doi: 10.21105/joss.12345
+  issn: 1234-5678
+  issue: 01
+  journal: Journal for Open Source Software
+  publisher:
+    name: Open Journals
+  start: 0001
+  title: "{title}"
+  type: article # Other options include: book, pamphlet, conference-paper...
+  url: "{linkToPublicationInJournal}"
+  volume: 1
+# More information on the preffered-citation CFF format can be found at https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files#citing-something-other-than-software

packages/plugin-histogram-button-response/README.md

@@ -0,0 +1,113 @@
+# plugin-histogram-button-response
+
+## Overview
+
+The `histogram-button-response` plugin displays a histogram chart and records responses generated by a button click. The chart can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically if the participant does not respond within a fixed length of time. The button itself can be customized using HTML formatting.
+
+The histogram stimulus is generated from a numeric array of data, with optional parameters for setting the number of bins to use. You can also add an annotation to the chart by setting the bin corresponding to a particular score as a different colour, with a corresponding text annotation.
+
+This plugin uses [Chart.js](https://www.chartjs.org/) under the hood, and supports features like axis labeling, legend display, and percentage formatting on the y-axis.
+
+---
+
+## Loading (Note: these CDN resources don't currently exist... but maybe will eventually?)
+
+Using the CDN-hosted JavaScript file:
+
+```js
+<script src="https://unpkg.com/@jspsych/plugin-histogram-button-response@VERSION_HERE"></script>
+```
+
+Using the JavaScript file downloaded from a GitHub release dist archive:
+
+```js
+<script src="jspsych/plugin-histogram-button-response.js"></script>
+```
+
+Using NPM:
+
+```
+npm install @jspsych/plugin-histogram-button-response
+```
+
+```js
+import jsPsychHistogramButtonresponse from "@jspsych/plugin-histogram-button-response";
+```
+
+---
+
+## Compatibility
+
+- jsPsych version: **v8.0.0 or later**
+
+---
+
+## Parameters
+
+| Name               | Type             | Default       | Description                                                      |
+| ------------------ | ---------------- | ------------- | ---------------------------------------------------------------- |
+| `description_text` | HTML string      | `undefined`   | Optional text shown above the chart for instructions or context. |
+| `chart_data`       | Array of numbers | `undefined`   | Required numeric data used to generate the histogram.            |
+| `n_bins`           | Integer          | `10`          | Number of bins to use when grouping the values.                  |
+| `n_x_labels`       | Integer          | `5`           | Maximum number of tick marks on the x-axis.                      |
+| `n_y_labels`       | Integer          | `5`           | Maximum number of tick marks on the y-axis.                      |
+| `base_color`       | String (color)   | `"#02c39a80"` | Color used for histogram bars except the highlighted one.        |
+| `highlight_color`  | String (color)   | `"#fee44080"` | Color used to fill the highlighted bin.                          |
+| `highlight_score`  | Number           | `null`        | A numeric value used to identify the bin to highlight.           |
+| `highlight_label`  | String           | `null`        | Label text shown above the highlighted bin.                      |
+| `x_axis_label`     | String           | `""`          | Label for the x-axis.                                            |
+| `y_axis_label`     | String           | `""`          | Label for the y-axis.                                            |
+| `y_percent`        | Boolean          | `false`       | If true, scales y-axis from 0 to 1 and formats as percentages.   |
+| `show_legend`      | Boolean          | `false`       | Whether to show a legend beside the chart.                       |
+| `choices`          | Array of strings | `undefined`   | Labels for the response buttons.                                 |
+| `button_html`      | Function         | _(see below)_ | Function that returns the HTML string for each button.           |
+
+**Default `button_html` function:**
+
+```ts
+(choice: string, choice_index: number) =>
+  `<button class="jspsych-btn">${choice}</button>`;
+```
+
+---
+
+## Data Generated
+
+| Name       | Type    | Description                                                     |
+| ---------- | ------- | --------------------------------------------------------------- |
+| `rt`       | Integer | Response time in milliseconds from trial start to button click. |
+| `response` | Integer | Index (0-based) of the selected button in the `choices` array.  |
+
+---
+
+## Example
+
+```js
+const trial = {
+  type: "histogram-button-response",
+  description_text: "<p>Which distribution best represents this data?</p>",
+  chart_data: [21, 22, 22, 24, 25, 25, 26, 27, 28, 29, 30, 32],
+  n_bins: 6,
+  highlight_score: 25,
+  highlight_label: "Target",
+  base_color: "#8888cc80",
+  highlight_color: "#ff6600",
+  x_axis_label: "Score",
+  y_axis_label: "Count",
+  y_percent: false,
+  choices: ["Low", "Medium", "High"],
+};
+```
+
+---
+
+## Documentation
+
+See [documentation](https://github.com/themusiclab/pose/tree/main/plugin-histogram-button-response/README.md)
+
+---
+
+## Author / Citation
+
+[Courtney B. Hilton](https://github.com/courtney-bryce-hilton)  
+If you use this plugin in your research, please cite the corresponding repository or paper when available.

packages/plugin-histogram-button-response/docs/plugin-histogram-button-response.md

@@ -0,0 +1,113 @@
+# plugin-histogram-button-response
+
+## Overview
+
+The `histogram-button-response` plugin displays a histogram chart and records responses generated by a button click. The chart can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically if the participant does not respond within a fixed length of time. The button itself can be customized using HTML formatting.
+
+The histogram stimulus is generated from a numeric array of data, with optional parameters for setting the number of bins to use. You can also add an annotation to the chart by setting the bin corresponding to a particular score as a different colour, with a corresponding text annotation.
+
+This plugin uses [Chart.js](https://www.chartjs.org/) under the hood, and supports features like axis labeling, legend display, and percentage formatting on the y-axis.
+
+---
+
+## Loading (Note: these CDN resources don't currently exist... but maybe will eventually?)
+
+Using the CDN-hosted JavaScript file:
+
+```js
+<script src="https://unpkg.com/@jspsych/plugin-histogram-button-response@VERSION_HERE"></script>
+```
+
+Using the JavaScript file downloaded from a GitHub release dist archive:
+
+```js
+<script src="jspsych/plugin-histogram-button-response.js"></script>
+```
+
+Using NPM:
+
+```
+npm install @jspsych/plugin-histogram-button-response
+```
+
+```js
+import jsPsychHistogramButtonresponse from "@jspsych/plugin-histogram-button-response";
+```
+
+---
+
+## Compatibility
+
+- jsPsych version: **v8.0.0 or later**
+
+---
+
+## Parameters
+
+| Name               | Type             | Default       | Description                                                      |
+| ------------------ | ---------------- | ------------- | ---------------------------------------------------------------- |
+| `description_text` | HTML string      | `undefined`   | Optional text shown above the chart for instructions or context. |
+| `chart_data`       | Array of numbers | `undefined`   | Required numeric data used to generate the histogram.            |
+| `n_bins`           | Integer          | `10`          | Number of bins to use when grouping the values.                  |
+| `n_x_labels`       | Integer          | `5`           | Maximum number of tick marks on the x-axis.                      |
+| `n_y_labels`       | Integer          | `5`           | Maximum number of tick marks on the y-axis.                      |
+| `base_color`       | String (color)   | `"#02c39a80"` | Color used for histogram bars except the highlighted one.        |
+| `highlight_color`  | String (color)   | `"#fee44080"` | Color used to fill the highlighted bin.                          |
+| `highlight_score`  | Number           | `null`        | A numeric value used to identify the bin to highlight.           |
+| `highlight_label`  | String           | `null`        | Label text shown above the highlighted bin.                      |
+| `x_axis_label`     | String           | `""`          | Label for the x-axis.                                            |
+| `y_axis_label`     | String           | `""`          | Label for the y-axis.                                            |
+| `y_percent`        | Boolean          | `false`       | If true, scales y-axis from 0 to 1 and formats as percentages.   |
+| `show_legend`      | Boolean          | `false`       | Whether to show a legend beside the chart.                       |
+| `choices`          | Array of strings | `undefined`   | Labels for the response buttons.                                 |
+| `button_html`      | Function         | _(see below)_ | Function that returns the HTML string for each button.           |
+
+**Default `button_html` function:**
+
+```ts
+(choice: string, choice_index: number) =>
+  `<button class="jspsych-btn">${choice}</button>`;
+```
+
+---
+
+## Data Generated
+
+| Name       | Type    | Description                                                     |
+| ---------- | ------- | --------------------------------------------------------------- |
+| `rt`       | Integer | Response time in milliseconds from trial start to button click. |
+| `response` | Integer | Index (0-based) of the selected button in the `choices` array.  |
+
+---
+
+## Example
+
+```js
+const trial = {
+  type: "histogram-button-response",
+  description_text: "<p>Which distribution best represents this data?</p>",
+  chart_data: [21, 22, 22, 24, 25, 25, 26, 27, 28, 29, 30, 32],
+  n_bins: 6,
+  highlight_score: 25,
+  highlight_label: "Target",
+  base_color: "#8888cc80",
+  highlight_color: "#ff6600",
+  x_axis_label: "Score",
+  y_axis_label: "Count",
+  y_percent: false,
+  choices: ["Low", "Medium", "High"],
+};
+```
+
+---
+
+## Documentation
+
+See [documentation](https://github.com/themusiclab/pose/tree/main/plugin-histogram-button-response/README.md)
+
+---
+
+## Author / Citation
+
+[Courtney B. Hilton](https://github.com/courtney-bryce-hilton)  
+If you use this plugin in your research, please cite the corresponding repository or paper when available.

packages/plugin-histogram-button-response/examples/index.html

@@ -0,0 +1,51 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>jsPsychPluginHistogramButtonResponse Example</title>
+    <script src="https://unpkg.com/jspsych@8"></script>
+    <!-- Load the published plugin package here, e.g.
+    <script src="https://unpkg.com/plugin-histogram-button-response"></script>-->
+    <script src="../dist/index.browser.js"></script>
+    <link rel="stylesheet" href="https://unpkg.com/jspsych@8/css/jspsych.css" />
+  </head>
+
+  <body></body>
+  <script>
+    const jsPsych = initJsPsych();
+
+    // function to sample normally distributed data
+    function sampleNormal(mean, stdDev) {
+      let u = 0,
+        v = 0;
+      // making sure u and v are not zero to avoid taking log(0)
+      while (u === 0) u = Math.random();
+      while (v === 0) v = Math.random();
+      return (
+        // using Box–Muller transform
+        Math.sqrt(-2.0 * Math.log(u)) * Math.cos(2.0 * Math.PI * v) * stdDev +
+        mean
+      );
+    }
+
+    const example_data = Array.from({ length: 500 }, () => {
+      const sample = sampleNormal(70, 10);
+      // clamp between 0 and 100
+      return Math.min(100, Math.max(0, sample));
+    });
+
+    const trial = {
+      type: jsPsychPluginHistogramButtonResponse,
+      description_text:
+        "This is how your score compares to others that have completed the test.",
+      chart_data: example_data,
+      n_bins: 15,
+      x_axis_label: "Score",
+      y_axis_label: "Count",
+      highlight_score: 91.1,
+      highlight_label: "Your Score!",
+      choices: ["Next"],
+    };
+
+    jsPsych.run([trial]);
+  </script>
+</html>

packages/plugin-histogram-button-response/jest.config.cjs

@@ -0,0 +1 @@
+module.exports = require("@jspsych/config/jest").makePackageConfig(__dirname);