Return to the Progressive Ratio Button Press Task page
___________________________________________________________________________________________________________________	

								*Progressive Ratio Button Press Task*
								(Driscoll Procedure)
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 07-27-2020
last Blurrydated:  10-02-2020 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 10-02-2020-2020 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	

This script implements a 'Progressive Ratio Button Press Task' to investigate 
approach-avoidance behavior towards different stimulus categories. The implemented template is based
on the procedure described by Driscoll et (2018).

Reference:
Driscoll, R., Quinn de Launay, K. & Fenske, M.J. (2018).
Less approach, more avoidance: Response inhibition has motivational consequences for sexual stimuli that reflect
changes in affective value not a lingering global brake on behavior.
Psychon Bull Rev (2018) 25:463–471
DOI 10.3758/s13423-017-1291-y


Note: the implemented procedure is Millisecond's best guess effort

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	

Participants view images of two different categories (here: images depicting a positive or a negative scene).
The images are originally somewhat blurry.
Participants get the option to press one button to 'see more' of the image (aka make them more clear)
or press another button to 'see less' of the image (aka make them more blurry).

At the beginning of each round it will take few button presses to get to the extremes 
(aka 'fully clear' or 'fully obscured'). However, as time goes one more and more button presses will be 
needed to reach one of the extremes.

For example, if a participant has selected to see a fully clear picture of a 'positive' image,
the next time the participant wants to see a fully clear view of a positive image DOUBLE
the number of button presses are required. And so on and so on.

Any button press is acceptable and participants can always change their minds, but they will eventually 
have to reach one of the extremes to move on the next image.

___________________________________________________________________________________________________________________	
DURATION 
___________________________________________________________________________________________________________________	
the default set-up of the script takes appr. 12 minutes to complete

___________________________________________________________________________________________________________________	
DATA FILE INFORMATION 
___________________________________________________________________________________________________________________		
The default data stored in the data files are:

(1) Raw data file: 'progressiveratio_driscoll_raw*.iqdat' (a separate file for each participant)*

build:								The specific Inquisit version used (the 'build') that was run
computer.platform:					the platform the script was run on (win/mac/ios/android)
date, time, 						date and time script was run 
subject, group, 					with the current subject/groupnumber
session:							with the current session id

blockcode, blocknum:				the name and number of the current block (built-in Inquisit variable)
trialcode, trialnum: 				the name and number of the currently recorded trial (built-in Inquisit variable)
										Note: trialnum is a built-in Inquisit variable; it counts all trials run; even those
										that do not store data to the data file. 
										
values.round:						Round/Block Count	
values.trialCount:					trialcounter per round (counts the trialsequences)									
										
values.category:					1 = category1 trial (here: positive scene)
									2 = category2 trial (here: negative scene)

values.image:						the presented image during this trial sequence									
values.imageItemnumber:				the itemnumber of the base image presented for the current category
 
values.NoiseItemnumber:				the itemumber of the noise filter presented over the base image during the current trial

response:							the participant's response (scancode of response button)
									46 = C (for clear -> see more of the image)
									48 = B (for blurry -> see less of the image)

latency: 							the response latency (in ms); measured from: onset of trial

values.interpretedResponse:			1 = participant selected to see 'more' (aka more clear) of the category1 image
									2 = participant selected to see 'less' (aka more blurry) of the category1 image
									3 = participant selected to see 'more' (aka more clear) of the category2 image
									4 = participant selected to see 'less' (aka more blurry) of the category2 image
									

values.finalResponse:				the last response made for the current trial (the result)
									1 = participant selected to see 'clearest' view of the category1 image
									2 = participant selected to see 'the most blurry' view of the category1 image
									3 = participant selected to see 'clearest' view of the category2 image
									4 = participant selected to see 'the most blurry' view of the category2 image
									

//category1 Information: here positive images

values.category1_minimumBlurry:		the current/last recorded number of button presses required to see the most blurry view of a category1 image
values.category1_minimumClear:		the current/last recorded number of button presses required to see the clearest view of a category1 image

values.category1_countClear:		counts the number of 'clear' presses ('see more') recorded for category1 images for the 
									current trial sequence. Reset back to 0 for each new trial sequence.
	
values.category1_countBlurry:		counts the number of 'blurry' presses ('see less') recorded for category1 images for the 
									current trial sequence. Reset back to 0 for each new trial sequence.
	
values.category1_countAll_Clear:	counts the number of 'clear' presses ('see more') recorded for category1 images
									across the entire task
									
values.category1_countAll_Blurry:	counts the number of 'blurry' presses ('see less') recorded for category1 images
									across the entire task
									
values.itemnumberStepsizeBlurry_category1:	the current/last recorded itemnumber stepsize with which category1 images 
											get incrementally more blurry 

values.itemnumberStepsizeClear_category1:	the current/last recorded itemnumber stepsize with which category1 images 
											get incrementally more clear 
											
values.countFinal_category1Clear:	counts the number of times a participant reached the 'most clear' stage for category1 images
									across the entire task
																		
values.countFinal_category1Blurry:	counts the number of times a participant reached the 'most blurry' stage for category1 images
									across the entire task
									
(same for category2 images; here negative images)


(2) Summary data file: 'progressiveratio_driscoll_summary*.iqdat' (a separate file for each participant)*

inquisit.build:						the Inquisit build/version run
computer.platform:					the platform the script was run on (win/mac/ios/android)
inquisit.build:						the version/build of Inquisit
script.startdate:					date script was run
script.starttime:					time script was started
script.subjectid:					assigned subject id number
script.groupid:						assigned group id number
script.sessionid:					assigned session id number
script.elapsedtime:					time it took to run script (in ms); measured from onset to offset of script
script.completed:					0 = script was not completed (prematurely aborted); 
									1 = script was completed (all conditions run)
									
//category1: here positive images
values.category1_countAll_Clear:	counts the number of 'clear' presses ('see more') recorded for category1 images
									across the entire task (independent of final outcomes)
									
values.category1_countAll_Blurry:	counts the number of 'blurry' presses ('see less') recorded for category1 images
									across the entire task (independent of final outcomes)

values.countFinal_category1Clear:	counts the number of times a participant reached the 'most clear' stage for category1 images
									across the entire task
																		
values.countFinal_category1Blurry:	counts the number of times a participant reached the 'most blurry' stage for category1 images
									across the entire task	
	

expressions.meanRT_category1_blurry:	mean reaction time (in ms) of selecting the 'blurry' button for a category1 image across all 'blurry' selections
expressions.meanRT_category1_clear:		mean reaction time (in ms) of selecting the 'clear' button for a category1 image across all 'clear' selections
										
(same for category2 images; here negative images)							
							
* separate data files: to change to one data file for all participants (on Inquisit Lab only), go to section
"DATA" and follow further instructions

___________________________________________________________________________________________________________________	
EXPERIMENTAL SET UP
___________________________________________________________________________________________________________________	

In this script:
- 2 categories of images tested (here: positive vs. negative)
- 8 block/rounds (editable parameter) each presenting 12 images (6 positive, 6 negative)

Each round:
- the order of the positive (category1) and negative (category2) images is selected at random
- the image for each category is selected randomly WITHOUT replacement from the pool of available items*
* This script only provides 6 images per category, so each round presents the same 12 images
To add additional images per category, simple go to section Editable Stimuli and add the stimuli to 
item.category1Images/item.category2Images. The script will automatically adapt to the increased
pool of items.


Trial Sequence:

- the base image is presented with an overlay of noise (noise itemnumber of 33 is used for first presentation)
- participant has to make a decision via key presses: 'see less of image' vs. 'see more of image'
=> depending on key choice and depending on how many key presses are necessary to show
the extreme of this choice, the participant sees a more blurry image or a more clear image and is either
done with this trial or has to make more selections.

Algorithm implemented:
1. At the start of each trial scripts notes the number of key presses required to get to 
the extreme view of an image category in either direction.
Based on this number, the noise itemnumber stepsize is calculated that is needed to jump
through the progressive noise filters (e.g. for the first trial this stepsize is 32, that is
the script would jump from 33 to either 1 or 65 - the extremes- with one key press)

2. Participants makes choice to either see more or less of the image.
Depending on the number of key presses required to see one of the extremes view and the number of
key presses already made in a specific direction,  two outcomes are possible:

1) the trial is over: participant sees selected extreme and can move to the next image.
At this point, the script doubles the number of presses needed for this category of images to 
reach this particular extreme view again during the next presentation of this category.

2) the key press count was not enough to reach the extreme of the selected direction yet 
and results in the selection of a new noise filter (either more blurry or more clear, depending on choice)
for the image.
At this point, the participant can choose to select the same direction again or change
her directional choice. 
Again, the script will update the key press count and compare the number of key presses made to the 
number of key presses required to see the directional extreme view of the image.


Example:

First Category1 Trial of a round:
Participant needs to use 1 key press in either direction to see one of the extremes.
Participant chooses the 'clear' key, sees the extremely clear view of the image (noise filter 1:
transparent overlay with no noise) and moves on to the next trial.

Second Category1 Trial of the round:
The script determines that participant needs 2 key presses to see the clear-extreme view of the image
but still requires only 1 key press to see the blurry-extreme view of the image.
Participant chooses 'clear' key and sees a more clear image (reduced noise filter: 17)- 
however, one more key press is required to see the clear-extreme view of the image, so the trial hasn't ended yet.
At this point, participant changes direction and selects the 'blurry' key. Since one key press is enough
to reach the blurry-extreme (noise filter 65), the trial ends and participant moves to the next trial.

Third Category1 Trial of the round:
Participant now requires 2 key presses in either direction to see one of the extremes.
Participant chooses - clear-blurry-clear and reaches the clear-extreme as 2 key presses towards the clear-extreme
were made. End of Trial.
For the next category1 Trial, participants needs 4 key presses to the clear-extreme view and
2 key presses to the blurry-extreme view.

...and so on and on...

If a participant only wants to see the clear-extreme of positive images:
1) Trial1: 1 key press required
2) Trial2: 2 key presses required
3) Trial3: 4 key presses required
4) Trial4: 8 key presses required
5) Trial5: 16 key presses required
6) Trial6: 32 key presses required
(Note: this script offers 65 noise filters, 32 noise filters going in either direction from starting point 33)

___________________________________________________________________________________________________________________
STIMULI
___________________________________________________________________________________________________________________

Category1/Category2 Stimuli:

6 category1 images (positive images) and 6 category2 images (negative images)
are provided by Millisecond Software as example stimuli.
The images can be edited under section Editable stimuli. Additional images can be edited to
item.category1Images/item.category2Images. The script will automatically adapt to the 
increased pool of stimuli.

Example: to run 8 blocks with 6 positive images each => 48 different positive images
would be required. Thus, if item.category1Images contains 48 images, each image would
only presented once.

Noise Filters:
This script provides 65 noise filters.
Noise Filter 33 is the starting noise filter that is superimposed over the target image at the start of each 
trial sequence. There are 32 increasing noise filters to get to 65 (most blurry) and 32 decreasing noise filters
to get to 1 (no noise at all =  completely transparent noise image).
Note: 32 noise filters in either direction are necessary for 6 trials per category 
with a doubling ratio of key presses.
If more trials should be run, increase the number of noise filters accordingly and change parameters.numbertrials_perblock.
For example, for 7 trials per category, use 129 noise filters; for 8 trials per category use 257 noise filters etc.
(the scripts will automatically adapt the starting noise filter).

noise images: created in paint.net with added plugin
Millisecond Software attempted to evenly space the noise on a transparent background across 65 noise images.
Exchange filter images under section Editable Stimuli

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
provided by Millisecond Software - can be edited under section Editable Instructions
___________________________________________________________________________________________________________________	
EDITABLE CODE 
___________________________________________________________________________________________________________________	
check below for (relatively) easily editable parameters, stimuli, instructions etc. 
Keep in mind that you can use this script as a template and therefore always "mess" with the entire code 
to further customize your experiment.