plugin-meye-config & extension-meye

.changeset/new-garlics-check.md

@@ -0,0 +1,6 @@
+---
+"@jspsych-contrib/plugin-meye-config": major
+"@jspsych-contrib/extension-meye": major
+---
+
+initial release of meye tooling for jsPsych

.github/workflows/release.yml

@@ -40,4 +40,4 @@ jobs:
 
       - name: Update README list of plugins and extensions
         run: npm run update-readme
-
+

package.json

@@ -29,7 +29,8 @@
     "import-sort-style-module": "^6.0.0",
     "lint-staged": "^11.1.2",
     "prettier": "^2.3.2",
-    "prettier-plugin-import-sort": "^0.0.7"
+    "prettier-plugin-import-sort": "^0.0.7",
+    "typescript": "^5.8.3"
   },
   "prettier": {
     "printWidth": 100

packages/extension-meye/README.md

@@ -0,0 +1,19 @@
+# meye extension
+
+## Overview
+
+This extension collects pupillometric data using Meye, a deep-learning model developed by Fabio Carrara. He made it to run on a website for public use at https://www.pupillometry.it/, and this extension adapts it to JsPsych. After calibrating the extension with the meye plugin (which must be a trial called before any trial using the extension), this extension runs in the background when added to any trial thereafter. 
+
+Minimum requirements are a 720p 30fps webcam. 
+
+## Compatibility
+
+Developed using jsPsych v7.3
+
+## Documentation
+
+Documentation can be found in the /docs folder.
+
+## Author / Citation
+
+Adam Vasarhelyi, Fabio Carrara

packages/extension-meye/docs/extension-meye.md

@@ -0,0 +1,52 @@
+# extension-meye
+
+Current version: 1.0.0.
+
+This extension collects pupillometric data using mEye. mEye is a deep-learning model available for public use at https://www.pupillometry.it/, and this extension adapts it to JsPsych. After calibrating the extension with the meye plugin (which must be a trial called before any trial using the extension), this extension runs in the background when added to any trial thereafter. 
+
+Minimum requirements are a 720p 30fps webcam. The corresponding plugin must be called as a trial once in the experiment before using any trial can use the mEye extension. Original mEye website credits: Raffaele Mazziotti1, Fabio Carrara, Giuseppe Amato, and Tommaso Pizzorusso.
+
+## Parameters
+
+This extension accepts one parameter. If unspecified, the extension will not collect any data.
+
+| Parameter           | Type             | Default Value      | Description                              |
+| ------------------- | ---------------- | ------------------ | ---------------------------------------- |
+| detection_interval  | numeric      	 | null        | Specifies how often (in ms) the extension takes a snapshot of the user's pupil. Due to how JavaScript works, this will typically have a mild error averaging 0.014ms, but up to 0.04ms has been observed. |
+
+## Data Generated
+
+This extension collects the following data. This extension measures the pupil at every interval specified by the parameter detection_interval. However, if the trial ends before the next interval is due, the extension will prematurely take a measurement as the trial ends and cancel the measurement that would occur when the trial no longer exists. For this reason, the last pupil measurement may be very soon after the second last measurement and this will be reflected in the data generated below. Due to how JavaScript works, the last measurement may also delay the trial ending by up to .04 s.
+
+| Name      | Type    | Value                                    |
+| --------- | ------- | ---------------------------------------- |
+| pupil_diameter  | numeric  | The diameter of the user's pupil at the time of snapshot, in pixels relative to the participant's monitor. The participant is assumed to have circular pupils because diameter is reported. |
+| blink_prob  | numeric | The probability that the user was blinking at the time of snapshot. Is between 0 and 1, where 1 indicates that the extension is certain that the user was blinking. |
+| timecode	| numeric	| The seconds (rounded to three decimal places) since the start of the extension-trial dyad that the snapshot was taken, including the moment a trial starts and ends. Due to JavaScript, this cannot be perfectly accurate and an error of up to 30ms occurs on the developer's computer. |
+
+## Install
+
+Using the downloaded jspsych-contrib folder:
+
+```js
+<script src="jspsych-contrib/packages/extension-meye/dist/index.browser.min.js"></script>
+```
+
+## Examples
+
+Ensure that the **plugin** is a trial in the timeline before adding the extension to any trial thereafter.
+
+```javascript
+var meyeCalibrate = {
+	type: jsPsychMeyeConfig,
+};
+
+var useExtension = {
+	type: jsPsychHtmlKeyboardResponse,
+	stimulus: '<img id="some-image" src="some-image.png"/>',
+	trial_duration: 600,
+	response_ends_trial: false,
+	data: { task: 'webcam1', US: 'no'},
+	extensions: [{ type: jsPsychExtensionMeye, params: {detection_interval: 100} }]
+}
+```

packages/extension-meye/examples/index.html

@@ -0,0 +1,82 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+	<script src="https://unpkg.com/[email protected]"></script>
+	<script src="https://unpkg.com/@jspsych/[email protected]"></script>
+	<script src="https://unpkg.com/@jspsych/[email protected]"></script>
+
+	<!-- Make sure that the plugin below has been built before using it. It's different to the current 
+	extension. To build it, go to /plugin-meye-config and run npm run build -->
+	<script src="../../plugin-meye-config/dist/index.browser.min.js"></script>
+	<script src="../dist/index.browser.min.js"></script>
+	<script src="../../extension-countdown/dist/index.browser.min.js"></script>
+</head>
+
+<body>
+	<script>
+	/* initialize jsPsych */
+	var jsPsych = initJsPsych({
+		extensions: [{type: jsPsychExtensionMeye}],
+		on_finish: function() {	  
+			jsPsych.data.displayData();
+			jsPsych.data.get().localSave('csv','TESTDATA.csv');
+		}
+	});
+
+	/* create timeline */
+	var timeline = [];
+	var participant_id = jsPsych.data.getURLVariable('ID');
+	jsPsych.data.addProperties({participant: participant_id});
+
+	var screen_width = window.screen.availHeight;
+	jsPsych.data.addProperties({screenW: screen_width});
+
+	var screen_height = window.screen.availWidth;
+	jsPsych.data.addProperties({screenH: screen_height});
+
+	/* preload images */
+	var preload = {
+		type: jsPsychPreload,
+		images: ['../../plugin-meye-config/img/picture2.png', '../../plugin-meye-config/img/cross.png']
+	};
+
+	timeline.push(preload);
+
+	var meyeCalibrate = {
+		type: jsPsychMeyeConfig,
+		//auto_calibrate: false,
+	};
+
+	const orientblue36 = {
+		timeline:[
+			{
+				type: jsPsychHtmlKeyboardResponse,
+				stimulus: '<img src="../../plugin-meye-config/img/cross.png" width="50" height="50"/>',
+				trial_duration: 600,
+				extensions: [{ type: jsPsychExtensionMeye, params: {detection_interval: 100} }]
+			},
+			{
+				type: jsPsychHtmlKeyboardResponse,
+				stimulus: '<div><img id="Blue" src="../../plugin-meye-config/img/Picture2.png" height="9%" style="position:absolute; top:46%; left:64%"/></div>',
+				trial_duration: 2000,
+				extensions: [{ type: jsPsychExtensionMeye, params: {detection_interval: 200} }]
+			}
+		]
+	}
+
+	var test_procedure = {
+		timeline: [preload, meyeCalibrate, orientblue36]
+	};
+
+	timeline.push(test_procedure);
+	jsPsych.run(timeline);
+
+	</script>
+</body>
+
+</html>

packages/extension-meye/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@jspsych-contrib/extension-meye",
+  "version": "0.0.1",
+  "description": "This extension collects pupillometric data using mEye, a deep-learning model developed by Fabio Carrara. He made it to run on a website \r for public use at https://www.pupillometry.it/, and this a JsPsych adaptation to make it viable for use in research. After calibration, the extension runs behind the scenes just like any other extension. Webcam quality >= 720p and >= 30fps is recommended.",
+  "type": "module",
+  "main": "dist/index.browser.min.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+	"build": "rollup --config"
+  },
+  "keywords": [],
+  "author": "Adam Vasarhelyi",
+  "license": "ISC",
+  "dependencies": {
+	  "@tensorflow/tfjs": "^4.22.0"
+  }
+}

packages/extension-meye/rollup.config.mjs

@@ -0,0 +1,3 @@
+import { makeRollupConfig } from "../../node_modules/@jspsych/config/rollup.js";
+
+export default makeRollupConfig("jsPsychExtensionMeye");