From 4f4df108e26552a73dd9c8593022ae3ac6007641 Mon Sep 17 00:00:00 2001 From: Becky Gilbert Date: Tue, 12 Nov 2024 15:03:01 -0800 Subject: [PATCH 1/6] standardize section titles and orders, add separate sections for start/stop plugins --- packages/record/README.md | 144 +++++++++++++++++++++++++++----------- 1 file changed, 105 insertions(+), 39 deletions(-) diff --git a/packages/record/README.md b/packages/record/README.md index 290b127..1c830c1 100644 --- a/packages/record/README.md +++ b/packages/record/README.md @@ -25,7 +25,7 @@ following language codes: | Portuguese | Brazil | pt-BR | | Portuguese | | pt | -## Video Configuration +## Video Configuration Plugin To record _any_ video during an experiment, including a consent video, you must add a video configuration trial. This trial allows the user to give permissions @@ -61,7 +61,7 @@ const videoConfig = { }; ``` -## Video Consent +## Video Consent Plugin Users will need to record themselves accepting the consent document for your study. This trial will allow the user to read the consent document and record a @@ -73,41 +73,6 @@ To create the video consent trial. const videoConsent = { type: chsRecord.VideoConsentPlugin, ...parameters }; ``` -### Example - -```javascript -const videoConsent = { - type: chsRecord.VideoConsentPlugin, - PIName: "Jane Smith", - institution: "Science University", - PIContact: "Jane Smith at 123 456 7890", - purpose: - "Why do babies love cats? This study will help us find out whether babies love cats because of their soft fur or their twitchy tails.", - procedures: - "Your child will be shown pictures of lots of different cats, along with noises that cats make like meowing and purring. We are interested in which pictures and sounds make your child smile. We will ask you (the parent) to turn around to avoid influencing your child's responses.", - risk_statement: - "There are no expected risks if you participate in the study. (This is optional, but should typically be included. If you leave it out there's no 'risks' section and you should include risk information elsewhere.)", - voluntary_participation: - "There are two sessions in this study; you will be invited to complete another session next month. It is okay not to do both sessions! (This is optional; leave it out if you don't need to say anything besides participation in this session being voluntary.)", - payment: - "After you finish the study, we will email you a $5 BabyStore gift card within approximately three days. To be eligible for the gift card your child must be in the age range for this study, you need to submit a valid consent statement, and we need to see that there is a child with you. But we will send a gift card even if you do not finish the whole study or we are not able to use your child's data! There are no other direct benefits to you or your child from participating, but we hope you will enjoy the experience.", - datause: - "We are primarily interested in your child's emotional reactions to the images and sounds. A research assistant will watch your video to measure the precise amount of delight in your child's face as he or she sees each cat picture.", - include_databrary: true, - additional_video_privacy_statement: - "We will also ask your permission to use your videos as stimuli for other parents. (This is optional; leave it out if there aren't additional ways you'll share video beyond as described in the participant's video privacy level and Databrary selections.)", - gdpr: false, - research_rights_statement: - "You are not waiving any legal claims, rights or remedies because of your participation in this research study. If you feel you have been treated unfairly, or you have questions regarding your rights as a research subject, you may contact the [IRB NAME], [INSTITUTION], [ADDRESS/CONTACT]", - additional_segments: [ - { - title: "US Patriot Act Disclosure", - text: "[EXAMPLE ONLY, PLEASE REMOVE ADDITIONAL_SEGMENTS UNLESS YOU NEED THEM.] Lookit is a U.S. organization and all information gathered from the website is stored on servers based in the U.S. Therefore, your video recordings are subject to U.S. laws, such as the US Patriot Act. This act allows authorities access to the records of internet service providers. If you choose to participate in this study, you understand that your video recording will be stored and accessed in the USA. The security and privacy policy for Lookit can be found at the following link: https://lookit.mit.edu/privacy/.", - }, - ], -}; -``` - ### Parameters Parameter names are shown below, along with their type and default value. If the @@ -328,7 +293,60 @@ Replace the default spoken consent statement with your custom text. Whether to omit the phrase “or in the very unlikely event of a research-related injury” from the contact section. (This was required by the Northwestern IRB.) -## Trial Recording +### Example + +```javascript +const videoConsent = { + type: chsRecord.VideoConsentPlugin, + PIName: "Jane Smith", + institution: "Science University", + PIContact: "Jane Smith at 123 456 7890", + purpose: + "Why do babies love cats? This study will help us find out whether babies love cats because of their soft fur or their twitchy tails.", + procedures: + "Your child will be shown pictures of lots of different cats, along with noises that cats make like meowing and purring. We are interested in which pictures and sounds make your child smile. We will ask you (the parent) to turn around to avoid influencing your child's responses.", + risk_statement: + "There are no expected risks if you participate in the study. (This is optional, but should typically be included. If you leave it out there's no 'risks' section and you should include risk information elsewhere.)", + voluntary_participation: + "There are two sessions in this study; you will be invited to complete another session next month. It is okay not to do both sessions! (This is optional; leave it out if you don't need to say anything besides participation in this session being voluntary.)", + payment: + "After you finish the study, we will email you a $5 BabyStore gift card within approximately three days. To be eligible for the gift card your child must be in the age range for this study, you need to submit a valid consent statement, and we need to see that there is a child with you. But we will send a gift card even if you do not finish the whole study or we are not able to use your child's data! There are no other direct benefits to you or your child from participating, but we hope you will enjoy the experience.", + datause: + "We are primarily interested in your child's emotional reactions to the images and sounds. A research assistant will watch your video to measure the precise amount of delight in your child's face as he or she sees each cat picture.", + include_databrary: true, + additional_video_privacy_statement: + "We will also ask your permission to use your videos as stimuli for other parents. (This is optional; leave it out if there aren't additional ways you'll share video beyond as described in the participant's video privacy level and Databrary selections.)", + gdpr: false, + research_rights_statement: + "You are not waiving any legal claims, rights or remedies because of your participation in this research study. If you feel you have been treated unfairly, or you have questions regarding your rights as a research subject, you may contact the [IRB NAME], [INSTITUTION], [ADDRESS/CONTACT]", + additional_segments: [ + { + title: "US Patriot Act Disclosure", + text: "[EXAMPLE ONLY, PLEASE REMOVE ADDITIONAL_SEGMENTS UNLESS YOU NEED THEM.] Lookit is a U.S. organization and all information gathered from the website is stored on servers based in the U.S. Therefore, your video recordings are subject to U.S. laws, such as the US Patriot Act. This act allows authorities access to the records of internet service providers. If you choose to participate in this study, you understand that your video recording will be stored and accessed in the USA. The security and privacy policy for Lookit can be found at the following link: https://lookit.mit.edu/privacy/.", + }, + ], +}; +``` + +## Trial Recording Extension + +Trial recording can be added to most jsPsych trials. This is a jsPsych extension +that allows you to add video recording to the trial. The trial will start once +the video recording has been set up, and the video recording will finish as soon +as the trial has ended. + +To use the CHS trial recording extension, you need to: + +1. Add it to the experiment settings, which is an optional object passed to + `initjsPsych`. +2. Add it to the `extensions` parameter for any trial(s) that you want to be + recorded. + +### Parameters + +This extension does not accept any parameters. + +### Example To record a single trial, you will have to first load the extension in `initJsPsych`. @@ -362,7 +380,40 @@ You might prefer to record across multiple trials in a study session. This can be done by using trials created with the start and stop recording plugins. This gives a bit of flexibility over which of the study trials are recorded. -To record a study session, create the start and stop recording trials. +To record a set of trials, add a 'start' trial in your jsPsych experiment +timeline right before you'd like to start recording, and add a 'stop' trial at +the point in your timeline when you'd like to stop recording. + +### Start Recording Plugin + +The plugin to start session recording is called `chsRecord.StartRecordPlugin`. + +```javascript +const startRec = { type: chsRecord.StartRecordPlugin }; +``` + +#### Parameters + +This plugin does not accept any parameters, other those available in all +plugins. + +### Stop Recording Plugin + +The plugin to stop session recording is called `chsRecord.StopRecordPlugin`. + +```javascript +const stopRec = { type: chsRecord.StopRecordPlugin }; +``` + +#### Parameters + +This plugin does not accept any parameters, other those available in all +plugins. + +### Example + +First, make sure that you've added a video config trial to your experiment +timeline. Then, create your start and stop recording trials: ```javascript const startRec = { type: chsRecord.StartRecordPlugin }; @@ -390,3 +441,18 @@ stop or start recording trials within the timeline. ```javascript jsPsych.run([videoConfig, startRec, morning, evening, stopRec, night]); ``` + +You can also create more than one session recording: + +```javascript +jsPsych.run([ + videoConfig, + startRec, + morning, + stopRec, + evening, + startRec, + night, + stopRec, +]); +``` From 018b92095179f5b619c6303d34599d51357edfba Mon Sep 17 00:00:00 2001 From: Becky Gilbert Date: Tue, 12 Nov 2024 15:06:43 -0800 Subject: [PATCH 2/6] add admonitions extension and add notes about adding a video config trial, and when not to use trial/session recording --- mkdocs.yml | 3 +++ packages/record/README.md | 19 ++++++++++++++++++- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 43631ee..117e29a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -35,3 +35,6 @@ plugins: extra: jsPsych: https://www.jspsych.org/v8/ + +markdown_extensions: + - admonition diff --git a/packages/record/README.md b/packages/record/README.md index 1c830c1..2449573 100644 --- a/packages/record/README.md +++ b/packages/record/README.md @@ -67,7 +67,10 @@ Users will need to record themselves accepting the consent document for your study. This trial will allow the user to read the consent document and record a video accepting it. -To create the video consent trial. +!!! caution "Don't forget a video config trial!" You MUST have a video config +trial in your experiment timeline before the video consent trial. + +To create the video consent trial: ```javascript const videoConsent = { type: chsRecord.VideoConsentPlugin, ...parameters }; @@ -335,6 +338,10 @@ that allows you to add video recording to the trial. The trial will start once the video recording has been set up, and the video recording will finish as soon as the trial has ended. +!!! important "When to use trial recording" Trial recording should NOT occur +simultaneously with session recording, or with any plugins that already use the +webcam (e.g. video config, video consent). + To use the CHS trial recording extension, you need to: 1. Add it to the experiment settings, which is an optional object passed to @@ -342,6 +349,9 @@ To use the CHS trial recording extension, you need to: 2. Add it to the `extensions` parameter for any trial(s) that you want to be recorded. +!!! caution "Don't forget a video config trial!" You MUST have a video config +trial in your experiment timeline before doing any trial recording. + ### Parameters This extension does not accept any parameters. @@ -380,10 +390,17 @@ You might prefer to record across multiple trials in a study session. This can be done by using trials created with the start and stop recording plugins. This gives a bit of flexibility over which of the study trials are recorded. +!!! important "When to use session recording" Sesssion recording should NOT +occur simultaneously with trial recording, or with any plugins that already use +the webcam (e.g. video config, video consent). + To record a set of trials, add a 'start' trial in your jsPsych experiment timeline right before you'd like to start recording, and add a 'stop' trial at the point in your timeline when you'd like to stop recording. +!!! caution "Don't forget a video config trial!" You MUST have a video config +trial in your experiment timeline before doing any session recording. + ### Start Recording Plugin The plugin to start session recording is called `chsRecord.StartRecordPlugin`. From 392191866da179c2dd309d6d6aaed4bdc7e287eb Mon Sep 17 00:00:00 2001 From: Becky Gilbert Date: Tue, 12 Nov 2024 15:07:31 -0800 Subject: [PATCH 3/6] update package-lock --- package-lock.json | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/package-lock.json b/package-lock.json index a138834..9b6bccc 100644 --- a/package-lock.json +++ b/package-lock.json @@ -23706,7 +23706,7 @@ }, "packages/data": { "name": "@lookit/data", - "version": "0.1.0", + "version": "0.2.0", "license": "ISC", "dependencies": { "@aws-sdk/client-s3": "^3.685.0", @@ -23753,19 +23753,19 @@ }, "packages/lookit-initjspsych": { "name": "@lookit/lookit-initjspsych", - "version": "1.0.6", + "version": "2.0.0", "license": "ISC", "devDependencies": { "@jspsych/config": "^3.0.1" }, "peerDependencies": { - "@lookit/data": "^0.1.0", + "@lookit/data": "^0.2.0", "jspsych": "^8.0.3" } }, "packages/record": { "name": "@lookit/record", - "version": "2.0.0", + "version": "3.0.0", "license": "ISC", "dependencies": { "auto-bind": "^5.0.1", @@ -23783,8 +23783,8 @@ "typescript": "^5.6.2" }, "peerDependencies": { - "@lookit/data": "^0.1.0", - "@lookit/templates": "^1.1.0", + "@lookit/data": "^0.2.0", + "@lookit/templates": "^2.0.0", "jspsych": "^8.0.3" } }, @@ -23816,12 +23816,12 @@ }, "packages/style": { "name": "@lookit/style", - "version": "0.0.6", + "version": "0.1.0", "license": "ISC", "devDependencies": { "@jspsych/config": "^3.0.1", - "@lookit/record": "^2.0.0", - "@lookit/surveys": "^2.0.0", + "@lookit/record": "^3.0.0", + "@lookit/surveys": "^3.0.0", "rollup-plugin-scss": "^4.0.0", "sass": "^1.78.0", "trash-cli": "^5.0.0" @@ -23829,7 +23829,7 @@ }, "packages/surveys": { "name": "@lookit/surveys", - "version": "2.0.1", + "version": "3.0.0", "license": "ISC", "dependencies": { "@jspsych/plugin-survey": "^2.0.0", @@ -23842,14 +23842,14 @@ "@types/dompurify": "^3.0.5" }, "peerDependencies": { - "@lookit/data": "^0.1.0", - "@lookit/templates": "^1.1.0", + "@lookit/data": "^0.2.0", + "@lookit/templates": "^2.0.0", "jspsych": "^8.0.3" } }, "packages/templates": { "name": "@lookit/templates", - "version": "1.1.0", + "version": "2.0.0", "license": "ISC", "dependencies": { "handlebars": "^4.7.8", @@ -23865,7 +23865,7 @@ "rollup-plugin-string": "^3.0.0" }, "peerDependencies": { - "@lookit/data": "^0.1.0", + "@lookit/data": "^0.2.0", "jspsych": "^8.0.3" } }, From dff8a75b8bf355abca66b6b7ec3c8ef07576b224 Mon Sep 17 00:00:00 2001 From: Becky Gilbert Date: Tue, 12 Nov 2024 15:08:05 -0800 Subject: [PATCH 4/6] add changeset --- .changeset/tricky-islands-visit.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/tricky-islands-visit.md diff --git a/.changeset/tricky-islands-visit.md b/.changeset/tricky-islands-visit.md new file mode 100644 index 0000000..04c962b --- /dev/null +++ b/.changeset/tricky-islands-visit.md @@ -0,0 +1,5 @@ +--- +"@lookit/record": patch +--- + +Update the documentation. From 6b2594dd451beb494d1e57925137a46b927f4a49 Mon Sep 17 00:00:00 2001 From: Becky Gilbert Date: Tue, 12 Nov 2024 15:20:52 -0800 Subject: [PATCH 5/6] update link --- packages/templates/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/templates/README.md b/packages/templates/README.md index cd51cd6..c0e97fb 100644 --- a/packages/templates/README.md +++ b/packages/templates/README.md @@ -2,5 +2,5 @@ This package contains the translated templates used in other custom CHS jsPsych trials. Please see the trial documentation (e.g. -[Video Consent](../record/README.md#video-consent)) for help using these +[Video Consent](../record/README.md#video-consent-plugin)) for help using these templates. From 02c5d7bd6429862132ac3b7c0f2520b6e2d5ea08 Mon Sep 17 00:00:00 2001 From: Becky Gilbert Date: Tue, 12 Nov 2024 15:26:34 -0800 Subject: [PATCH 6/6] add line break after markdown admonition so that prettier does not ruin it --- packages/record/README.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/packages/record/README.md b/packages/record/README.md index 2449573..719e084 100644 --- a/packages/record/README.md +++ b/packages/record/README.md @@ -67,8 +67,9 @@ Users will need to record themselves accepting the consent document for your study. This trial will allow the user to read the consent document and record a video accepting it. -!!! caution "Don't forget a video config trial!" You MUST have a video config -trial in your experiment timeline before the video consent trial. +!!! caution "Don't forget a video config trial!" + + You MUST have a video config trial in your experiment timeline before the video consent trial. To create the video consent trial: @@ -338,9 +339,9 @@ that allows you to add video recording to the trial. The trial will start once the video recording has been set up, and the video recording will finish as soon as the trial has ended. -!!! important "When to use trial recording" Trial recording should NOT occur -simultaneously with session recording, or with any plugins that already use the -webcam (e.g. video config, video consent). +!!! important "When to use trial recording" + + Trial recording should NOT occur simultaneously with session recording, or with any plugins that already use the webcam (e.g. video config, video consent). To use the CHS trial recording extension, you need to: @@ -349,8 +350,9 @@ To use the CHS trial recording extension, you need to: 2. Add it to the `extensions` parameter for any trial(s) that you want to be recorded. -!!! caution "Don't forget a video config trial!" You MUST have a video config -trial in your experiment timeline before doing any trial recording. +!!! caution "Don't forget a video config trial!" + + You MUST have a video config trial in your experiment timeline before doing any trial recording. ### Parameters @@ -390,16 +392,17 @@ You might prefer to record across multiple trials in a study session. This can be done by using trials created with the start and stop recording plugins. This gives a bit of flexibility over which of the study trials are recorded. -!!! important "When to use session recording" Sesssion recording should NOT -occur simultaneously with trial recording, or with any plugins that already use -the webcam (e.g. video config, video consent). +!!! important "When to use session recording" + + Sesssion recording should NOT occur simultaneously with trial recording, or with any plugins that already use the webcam (e.g. video config, video consent). To record a set of trials, add a 'start' trial in your jsPsych experiment timeline right before you'd like to start recording, and add a 'stop' trial at the point in your timeline when you'd like to stop recording. -!!! caution "Don't forget a video config trial!" You MUST have a video config -trial in your experiment timeline before doing any session recording. +!!! caution "Don't forget a video config trial!" + + You MUST have a video config trial in your experiment timeline before doing any session recording. ### Start Recording Plugin