User Manual: Inquisit Dynamically Adjusted Motion Prediction Task (DAMP)


___________________________________________________________________________________________________________________	

						DYNAMICALLY ADJUSTED MOTION PREDICTION TASK (DAMP)
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 03-03-2016
last updated:  09-16-2019 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 09-16-2019 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	
This script implements a Dynamically Adjusted Motion Prediction Task (DAMP) similarly to the one described in:

Ullsperger, M. & Crampon v., D.Y. (2003). Error Monitoring Using External Feedback: Specific Roles of
the Habenular Complex, the Reward System, and the Cingulate Motor Area Revealed by Functional Magnetic
Resonance Imaging. The Journal of Neuroscience,23(10),4308–4314.

This script implements 100% informative feedback (Experiment1).

NOTE: Ullsperger & Crampon (2003) kept the error rates constant for each participant (~40% error rate) by (dynamically) adapting 
the task difficulty of the task to each participant's ability. "Task difficulty" was operationalized solely as the time difference 
of arrival of the two balls at the finish line.  No further details of the adjustment procedure are provided by U & C other than 
"To keep the error rate high during the first trials of the experiments, individual difficulty levels were determined in a 
training session (100 trials and only informative feedback) that was performed during the anatomical scans (p. 4309)."

Script DynamicallyAdjustedMotionPrediction_Baseline.iqx implements an interweaved stairway procedure to assess individual
Arrival Times Difference Thresholds. Script DynamicallyAdjustedMotionPrediction.iqx (current one) uses the established
Arrival Times Difference Threshold to keep error rate constant.
Arrival Time Difference Threshold in this script: (roughly) the threshold at which participants start to guess with 
a 50/50 probability which ball reaches the finish line first.

This batch script runs both scripts sequentially and hands of the ArrivalTimeDifference (ATD) threshold.

___________________________________________________________________________________________________________________	
DURATION 
___________________________________________________________________________________________________________________	
the default set-up of this script takes appr. 25 minutes to run



___________________________________________________________________________________________________________________	

							DYNAMICALLY ADJUSTED MOTION PREDICTION TASK (DAMP)
							Baseline Assessment via Interweaved Staircase Procedure
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 02-16-2016
last updated:  02-21-2022 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 02-21-2022 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	
This script implements a procedure to establish a 'time arrival difference' baseline for 
a Dynamically Adjusted Motion Prediction Task (DAMP) similarly to the one described in:

Ullsperger, M. & Crampon v., D.Y. (2003). Error Monitoring Using External Feedback: Specific Roles of
the Habenular Complex, the Reward System, and the Cingulate Motor Area Revealed by Functional Magnetic
Resonance Imaging. The Journal of Neuroscience,23(10), 4308–4314.

NOTE: Ullsperger & Crampon (2003) kept the error rates constant for each participant (~40% error rate) by 
(dynamically) adapting the task difficulty of the task to each participant's ability. 
"Task difficulty" was operationalized solely as the time difference of arrival of the two balls at the finish line.  
No further details of the adjustment procedure are provided by U & C other than 
"To keep the error rate high during the first trials of the experiments, individual difficulty levels 
were determined in a training session (100 trials and only informative feedback) that was performed during 
the anatomical scans (p. 4309)."

This script adapts an interweaved upward/downward staircase like procedure to determine individual 
"arrival time difference thresholds" 
- (roughly) the threshold at which participants start to guess with a 50/50 probability 
which ball reaches the finish line first.

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	
Participants view 2 balls that travel towards a finish line starting from different screen positions at 
different speeds. One ball is assigned the role of 'base' (the arrival time of the base ball is kept constant 
across all trials in this script) and one ball is assigned the role of 'target' 
(the target is always faster than the base at the finish Line). 
Long before the balls reach the finish line, the balls disappear and participants have to predict
which ball will first reach the finish line (=target). Smiley or frowny faces provide feedback for each prediction.
											  
___________________________________________________________________________________________________________________	
DURATION 
___________________________________________________________________________________________________________________	
the default set-up of the script takes appr. 8 minutes to complete

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

(1) Raw data file: 'dynamicallyadjustedmotionprediction_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 such as feedback trials. Thus, trialnum 
										may not reflect the number of main trials run per block.
										
									
trialcount_DS:						counts the number of trials run in downward staircase (DS)
trialcount_US:						counts the number of trials run in upnward staircase (US)
staircase:							1 = downward staircase (start with big difference); 2 = upward staircase (start with small difference)
fixationDuration:					stores the current fixation duration as selected from list.fixationdurations
xpos1:								stores the x-coordinate (in canvas width percentage) of the starting point of ball1
xpos2:								stores the x-coordinate (in canvas width percentage) of the starting point of ball2
basePosition:						1 = base is top ball; 2 = base is bottom ball
targetPosition:						1 = target is top ball (correct response is ball1); 2 = target is bottom ball (correct response is ball2)
baselineArrivalTime:				the constant winning arrival time in ms (default: 7000)
targetArrivalTime_DS:				the target arrival time (in ms) for downward staircase
targetArrivalTime_US:				the target arrival time (in ms) for upward staircase
differenceArrivalTime_DS:			stores the current difference in arrival Times of Ball1 and Ball2 (in ms) in downstaircase
prevDirection_DS:					1 = the previous arrival time difference was decreased in downstaircase; 2 = the previous arrival time difference was decreased in downstaircase
currDirection_DS:					1 = currently the arrival time difference is decreased in downstaircase; 2 = currently the arrival time difference is increased in downstaircase
differenceArrivalTime_US:			stores the current difference in arrival Times of Ball1 and Ball2 (in ms) in upstaircase
prevDirection_US:					1 = the previous arrival time difference was decreased in upstaircase; 2 = the previous arrival time difference was decreased in upstaircase
currDirection_US:					1 = currently the arrival time difference is decreased in upstaircase; 2 = currently the arrival time difference is increased in upstaircase


response:							the participant's response (scancode of response => 2 for 'ball 1' and 3 for 'ball 2')
responseText:						the response key pressed 
correct:							the correctness of the response (1 = correct; 0 = incorrect)
ACC_selection:						1 = selection was correct; 0 = otherwise
latency: 							the response latency (in ms) - measured from onset of trial


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

inquisit.version: 						Inquisit version run
computer.platform:					the platform the script was run on (win/mac/ios/android)
startDate:							date script was run
startTime:							time script was started
subjectid:							assigned subject id number
groupid:							assigned group id number
sessionid:							assigned session id number
elapsedTime:						time it took to run script (in ms); measured from onset to offset of script
completed:							0 = script was not completed (prematurely aborted); 
									1 = script was completed (all conditions run)

estATD_Threshold:					established arrival time difference (ATD) threshold as the mean of all collected reversal points


___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________

Ullsperger & Crampon (2003) kept the error rates constant for each participant (~40% error rate) by (dynamically) adapting the task difficulty
of the task to each participant's ability. "Task difficulty" was operationalized solely as the time difference of arrival of the two balls
at the finish line.  No more details of the adjustment procedure are provided by U & C other than "To keep the error rate high during the first
trials of the experiments, individual difficulty levels were determined in a training session (100 trials and only informative feedback) 
that was performed during the anatomical scans (p. 4309)."
This script adapts a downward staircase like procedure to determine individual "arrival time difference thresholds" - roughly the 
threshold arrival difference at which participants start to guess (50% error rate).

The staircase procedure is implemented as follows:
(1) one ball's arrival time is kept constant (=base) at 7000ms (default - can be edited under section Editable Parameters);
the second ball (=target) adapts its speed according to participant's performance. The target is always the ball
that arrives first at the finish line. The target starts with a predetermined arrival time difference of 1000ms (default)
in the downward staircase (DS) and 50ms in the upward staircase (US).
(2) the position of the target is randomly determined to be the top or the bottom ball (-> list.targetPosition)
(3) Different horizontal starting positions are randomly assigned to the top and bottom ball (-> list.xpos1/list.xpos2)
Note: random assignment with constraint that positions always differ
(4) If participant correctly identifies the target as the faster ball, the arrival time difference is decreased
by a predetermined stepsize (default: 100ms - can be edited under section Editable Parameters)
Note: if the arrival time difference drops below 100ms; the stepsize is reduced to 50ms.
If participant chooses the base instead (or does not respond in time), the arrival time difference is increased by the same stepsize.
(5) The algorithm compares two consecutive adjustments: if they are inconsistent (one decreases, the next increases),
then the current 'arrival time difference' is defined as a 'reversal point' and stored in list.reversalDiffs.
DS and US condition store their respective reversal points in the same list.
(6) After 50 trials in each staircase (order is randomly determined -> block.baselineDamp), the procedure terminates 
and the mean of all reversal points is calculated as the participant's threshold (~50% errorrate)

___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________
see section Editable Stimuli

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
see 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:

/xBar:							x-coordinate (in canvas width percentages) of the left top corner of the finish line (default: 90%)
/stimPresentation:				the presentation duration (in ms) of the moving balls (default: 1430)
/baselineArrivalTime:			the constant winning arrival time in ms (default: 7000)
/startdifferenceArrivalTime_DS:	the starting difference in arrival times in ms for the downward staircase (default: 1000)

/startdifferenceArrivalTime_US:	the starting difference in arrival times in ms for the upward staircase (default: 50)
									Note: once the arrival time difference increases above 100ms, the stepsize increases to parameters.stepsize
									
/responseWindow:				response window in ms (default: 1500)
/iti:							intertrial interval (in ms) btw. response trial and feedback trial (default: 750)
/feedbackDuration:				duration (in ms) of feedback presentation (default: 1000)

/stepsize:						the up and down adjustment of the arrival time difference in ms (default: 100)
								Note: once the arrival time difference decreases below 100ms, the stepsize is reduced to 50ms



___________________________________________________________________________________________________________________	

						DYNAMICALLY ADJUSTED MOTION PREDICTION TASK (DAMP)
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 02-16-2016
last updated:  02-21-2022 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 02-21-2022 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	
This script implements a Dynamically Adjusted Motion Prediction Task (DAMP) similarly to the one described in:

Ullsperger, M. & Crampon v., D.Y. (2003). Error Monitoring Using External Feedback: Specific Roles of
the Habenular Complex, the Reward System, and the Cingulate Motor Area Revealed by Functional Magnetic
Resonance Imaging. The Journal of Neuroscience,23(10),4308–4314.

This script implements 100% informative feedback (Experiment1).

NOTE: Ullsperger & Crampon (2003) kept the error rates constant for each participant (~40% error rate) by 
(dynamically) adapting  the task difficulty of the task to each participant's ability. 
"Task difficulty" was operationalized solely as the time difference  of arrival of the two balls at the finish line.  
No further details of the adjustment procedure are provided by U & C other than "To keep the error rate high 
during the first trials of the experiments, individual difficulty levels were determined in a  training session 
(100 trials and only informative feedback) that was performed during the anatomical scans (p. 4309)."

Script DynamicallyAdjustedMotionPrediction_Baseline.iqx implements an interweaved stairway procedure to assess individual
Arrival Times Difference Thresholds. Script DynamicallyAdjustedMotionPrediction.iqx (current one) uses the established
Arrival Times Difference Threshold to keep error rate constant.
Arrival Time Difference Threshold in this script: (roughly) the threshold at which participants start to guess with 
a 50/50 probability which ball reaches the finish line first.

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	
Participants view 2 balls that travel towards a finish line starting from different screen positions at 
different speeds. One ball is assigned the role of 'base' (the arrival time of the base ball is kept constant 
across all trials in this script) and one ball is assigned the role of 'target' (the target is always faster 
than the base at the finish Line).  Long before the balls reach the finish line, the balls disappear and 
participants have to predict which ball will first reach the finish line (=target). 
Smiley or frowny faces provide feedback for each prediction.

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

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

(1) Raw data file: 'dynamicallyadjustedmotionprediction_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 such as feedback trials. Thus, trialnum 
										may not reflect the number of main trials run per block.
																				
trialcount:							counts the number of trials run 
fixationduration:					stores the current fixation duration as selected from list.fixationdurations
xpos1:								stores the x-coordinate (in canvas width percentage) of the starting point of ball1
xpos2:								stores the x-coordinate (in canvas width percentage) of the starting point of ball2
basePosition:						1 = base is top ball; 2 = base is bottom ball
targetPosition:						1 = target is top ball (correct response is ball1); 2 = target is bottom ball (correct response is ball2)

ATD_Threshold:						roughly the arrival time difference at which participant starts guessing
										Note: script DynamicallyAdjustedMotionPrediction_baseline.iqx implements a procedure to 
										assess individual thresholds
										
aboveThreshold: 					0 = target arrival time is below threshold; 0 = target arrival time is above threshold	
propThresholdDiff:					increase/decrease of 25%, 50%, or 75% of Arrival Time Threshold		
baselineArrivalTime:				the constant winning arrival time in ms (default: 7000)
targetArrivalTime:					the target arrival time (in ms) 
arrivalTimeDifference:				stores the current difference in arrival Times of Ball1 and Ball2 (in ms) 

response:							the participant's response (scancode of response => 2 for 'ball 1' and 3 for 'ball 2')
responseText:						the response key pressed 
correct:							the correctness of the response (1 = correct; 0 = incorrect)
latency: 							the response latency (in ms) - measured from onset of trial
properror:							overall error proportion

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

inquisit.version: 						Inquisit version run
computer.platform:					the platform the script was run on (win/mac/ios/android)
startDate:							date script was run
startTime:							time script was started
subjectid:							assigned subject id number
groupid:							assigned group id number
sessionid:							assigned session id number
elapsedTime:						time it took to run script (in ms); measured from onset to offset of script
completed:							0 = script was not completed (prematurely aborted); 
									1 = script was completed (all conditions run)

ATD_Threshold:						roughly the arrival time difference at which participant starts guessing
										Note: script DynamicallyAdjustedMotionPrediction_baseline.iqx implements a procedure to 
										assess individual thresholds
										
properror:							overall error proportion

___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________
* Script runs 120 DAMP trials with a base and target ball. 
* The arrival time of the base at the finish line is kept constant in this script (default: 7000ms)
* The target is always the one arriving first at the finish line. 
* arrival times for targets are calculated in such a way that a set proportion (default: 0.4) is chosen from
below the 'Arrival Time Difference Threshold' (randomly either 60%, 70% or 80% below threshold - selected with replacement)
and a set proportion (default: 0.6) is chosen from above the 'Arrival Time Difference Threshold' 
(randomly either 60%, 70% or 80% above threshold - selected with replacement)
* Vertical screen positions of base and target balls are randomly assigned in such a way that each ball has a 50%
probability to be the top ball (actual frequencies might vary with the default set-up).
* Additionally, horizontal start positions (5%, 25%, 45% -> list.xpos1) are randomly assigned to base and target
with the constraint that they cannot be the same. Actual frequencies of the different starting position combinations
likely vary from participant to participant.

___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________
see section Editable Stimuli

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
see 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:

/xBar:							x-coordinate (in canvas width percentages) of the left top corner of the finish line (default: 90%)
/stimPresentation:				the presentation duration (in ms) of the moving balls (default: 1430)
/baselineArrivalTime:			the constant arrival time of the base ball in ms (default: 7000)
/responseWindow:				response window in ms (default: 1500)
/iti:							intertrial interval (in ms) btw. response trial and feedback trial (default: 750)
/feedbackDuration:				duration (in ms) of feedback presentation (default: 1000)

/ATD_Threshold:					roughly the arrival time difference at which participant starts guessing 
								(set by DynamicallyAdjustedMotionPrediction_baseline.iqx if batch script is run; otherwise set here)
								Note: script DynamicallyAdjustedMotionPrediction_baseline.iqx implements a procedure to assess individual 
								thresholds
									
/propError:						the targeted error proportion (default: 0.4)