Return to the Probabilistic Reversal Learning Task page
														
___________________________________________________________________________________________________________________	

										*Probabilistic Reversal Learning Task*
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 03-07-2018
last updated:  03-11-2020 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 03-11-2020 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	
This script implements a Probabilistic Reversal Learning Task, a task of adaptive learning and flexibility 
in the context of changing stimulus-reward contingencies.

References:

Waegeman, A., Declerck, C.H, Boone, C., Seurinck, R. & Parizel, P.M. (2014). Individual Differences in Behavioral Flexibility in a Probabilistic Reversal Learning Task: An fMRI Study.
Journal of Neuroscience, Psychology, and Economics, Vol. 7, No. 4, 203–218

Cools R, Clark L, Owen AM, Robbins TW. (2002). Defining the neural mechanisms of probabilistic reversal learning using
event-related functional magnetic resonance imaging. J Neurosci. 2002;22:4563–4567.

Notes:
Like Waegeman et al (2014), this Inquisit script 
a) uses a timelimit for each of the test blocks. The number of reversals reached during that time
reflects how fast a participant learned to adjust behavior

b) attaches explicit rewards (aka points) to 'positive' feedback and punishment for 'negative' feedback (however,
the points can be made invisible, see section Editable Parameters) and asks participant to maximize their reward without 
explicitly alerting participants to the fact that payoff probabilities might change (however, instructions can be
easily altered under section Editable Instructions).

c) uses a 80%/20% probability for rewards and punishment (editable under section Editable Parameters)

___________________________________________________________________________________________________________________
TASK DESCRIPTION
___________________________________________________________________________________________________________________	
Participants are asked to select btw. 2 patterns. One patterns has an 80% probability of a reward
and a 20% probability of a loss whereas the probabilities are reversed for the second pattern.
Participants are asked to maximize their rewards. After participants have learned to consistently select the 
pattern with the higher reward probability, the probabilities of the patterns are reversed.
A block ends after 9 minutes.

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

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

(1) Raw data file: 'probabilisticreversallearningtask_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
script.sessionid:					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 such as feedback trials. Thus, trialnum 
										may not reflect the number of main trials run per block. 
										
values.countBlocks:					counts the number of test blocks
values.counttrials:					counts the number of test trials run (across blocks)								
values.index_correctChoice:			the itemnumber of the currently 'lucky' pattern
values.index_incorrectChoice:		the itemnumber of the currently 'unlucky' pattern

values.correctChoicePosition:		1 = lucky pattern is on the left; 2 = lucky pattern is on the right

									
values.maxCorrectChoices:			the number of consecutive correct choices until the next reversal
									(randomly selected from 10, 11, 12, 13, 14, 15)
								
values.reversal:					1 =  the trial just reversed the probabilities (a reversal just took place);
									0 = otherwise
								
values.relearned:					1 = participant has likely learned the reversed probability assignment
									=> the first selection of the new lucky pattern after a reversal
										(lucky guesses excluded)
									0 = participant has likey not learned the reversed probability assignment
								
presentedCorrectStim:				the presented image file of the 'lucky pattern'
presentedIncorrectStim:				the presented image file of the 'unlucky pattern'

response:							the participant's response (scancode of response key):
									18 = E
									23 = I
									57 = spacebar

values.respCategory:				C = correct (selected correct/winning pattern and received 'happy' feedback)
									PE = correct (selected correct/winning patterbBUT received 'unhappy' feedback)
									C-RE* = first correct after reversal error or 'lucky guess' (selected correct outcome and received 'happy' feedback)
									C-RE (PE)* = first correct after reversal errors (selected correct/winning pattern BUT received 'unhappy' feedback)
									lucky guess* = correct (selected correct outcome during a reversal trial and received 'happy' feedback)
									lucky guess (PE)* = correct (selected correct outcome during a reversal trial but received 'unhappy' feedback)
									RE = reversal error =>
									participant selected incorrect outcome (formerly correct) after a reversal until a correct response
									is made (=evidence of relearning)
									Note: a 'lucky guess' is not counted as evidence of relearning
									E = incorrect (selected incorrect outcome and received 'unhappy' feedback)
									E (PE)* = incorrect (selected incorrect outcome BUT received 'happy' feedback)
									NR = no response (participant was not fast enough to select a choice)
										* = should be rare (but are not impossible)
								
correct:							accuracy of response: 1 = correct response (chose the 'lucky' pattern); 
									0 = otherwise
									
latency: 							the response latency (in ms); measured from: onset of patterns

values.countConsecutiveCorrect:		running total of the consecutive choices of the 'lucky' pattern
										(resets for reversals and when the unlucky pattern is selected)
							
values.feedback:					1 = negative feedback (points taken away); 
									2 = positive feedback (points added)
									
values.countICFeedback:				counts the number of times negative feedback was given for the lucky pattern
									in between reversals

values.countReversals:				running count of the reversals per block
values.totalPoints:					the accumulated points across all test blocks
values.iti:							duration (in ms) of the current iti

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

computer.platform:					he platform the script was run on (win/mac/ios/android)
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)
								
values.passedPractice:				1 = practice learning criterium (participant reached first reversal) was reached
									0 = practice learning criterium was not reached within 10 minutes and task was aborted
									
values.abort:						1 = task was terminated because participant failed to reach a block's learning criterium
									within the specified timeframe.
									practice learning criterium: participant reached first reversal within 10 minutes
									test block learning criterium: participant reached 10th reversal within 30 minutes

values.totalPoints:					the accumulated points across all test blocks

values.counttrials:					counts the number of choice trials run (across all test blocks)

values.countC:						counts the number of times participant chose the 'correct' option across all test blocks
									=> (C, PE, C-RE, C-RE (PE)) - excludes 'lucky guesses'
									
values.countLG:						counts the number of times participant had a 'lucky guess' 
values.countE:						counts the number of times participant chose the 'incorrect' option (excludes reversal errors) across all test blocks
values.countRE:						counts the number of reversal errors made (see explanation for RE above under values.respCategory) across all test blocks
values.countNR:						counts the number of 'no responses'	across all test blocks	 				
expressions.probC:					proportion of correct responses across all test trials
expressions.probLG:					proportion of 'lucky guesses' across all test trials
expressions.probE:					proportion of errors across all test trials	
expressions.probRE:					proportion of reversal errors across all test trials	
expressions.probNR:					proportion of 'no responses' across all test trials

expressions.MinICFeedback:			the minimum number of negative feedbacks for 'lucky' patterns in between reversals (across all test blocks)
expressions.MaxICFeedback:			the maximum number of negative feedback for 'lucky' patterns in between reversals (across all test blocks)
expressions.Mean_ICFeedback:		the mean number of negative feedback for 'lucky' patterns in between reversals (across all test blocks)

values.countBlocks:					counts the number of test blocks started

values.countReversals_test1:		reversal count in testblock 1 (if completed reversal count should be 9 - default)
values.countReversals_test2:		reversal count in testblock 2 (if completed reversal count should be 9 - default)
values.countReversals_test3:		reversal count in testblock 3 (if completed reversal count should be 9 - default)

* 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 
___________________________________________________________________________________________________________________	

(1) Practice:
- the practice phase presents two patterns with the same reward/punishment probabilities as during the test.
- the initial 'lucky' pattern is randomly determined
- The screen position of the two patterns (left vs. right) is randomly determined (random selection with replacement).
- Practice ends after the first reversal is reached.
Note: if the first reversal is not reached within 5 minutes (default), practice is cut short and the script is aborted

(3) Test: 3 blocks
- each of the blocks gets 2 randomly assigned patterns (6 patterns provided)
- one pattern has an 80% probability of reward (20% probability of punishment),
the reward/punishment probabilities are reversed for the second pattern
(the initial 'lucky' pattern is determined randomly)
- The screen position of the two patterns (left vs. right) is randomly determined (random selection with replacement)
- after 10-15 consecutive choices of the 'lucky' pattern (randomly determined), the reward/punishment probabilities are reversed
- each test block is terminated after 9 minutes => the number of reversals will differ
Trial Sequence:
pattern presentation (max. 2000ms or response) -> Feedback (500ms) -> ITI: variable (min: 500ms)
(entire trial takes: 3000ms => every 3s a new pattern is presented)

___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________	
provided by Millisecond Software - can be edited 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.

The parameters you can change are:

/showTotalPoints:			true (default): shows the total points accumulated
							false: does not show the total points accumulated

/maxStimDuration:		 	the maximum duration (in ms) of the patterns (default: 2000ms)
/feedbackDuration:			the duration of the feedback (in ms) (default: 500ms)
/SOA:						stimulus onset asynchrony (in ms): a new pattern appears every 3s (default: 3000ms)
/readyDuration:				the duration (in ms) of the 'get ready' trial at the beginning of each block (default: 5000ms)

/practiceTimeout:			the practice session ends after 5minutes if participant has not reached the learning criterium 
							(=reach first reversal) (default: 300000ms). In this case, the task is aborted.
							
blockDuration:				the duration (in ms) assigned to each test block (default: 540000 => 9 minutes)							
/highProbability:			the higher (reward) probability (default: 0.8)

/leftKey:					the left response key (default: "E")
/rightKey:					the scancode of the right response key (default: "I")

/picSize:					proportional sizing of the patterns relative to canvas height (default: 30%)