User Manual: Inquisit Automatic Balloon Analogue Risk Task (Automatic BART)


___________________________________________________________________________________________________________________	

							AUTOMATIC BALLOON ANALOGUE RISK TASK (autoBART)
___________________________________________________________________________________________________________________
	
This script is based in large part on the BART.iqx script provided by Millisecond Software LLC
last updated:  02-17-2022 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 02-17-2022 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________
This script implements the BART, a measure of impulsivity and risk aversion, based on:

Pleskac, T.J., Wallsten, T.S, Wang, P. & Lejuez, C.W. (2008). Development of an Automatic Response Mode to Improve 
the Clinical Utility of Sequential Risk-Taking Tasks. Experimental and Clinical Psychopharmacology, 16, 555–564.

Note: the autoBART differs from the BART in the following ways
(1) participants indicate up front how many times they want to pump up the balloon
(2) default instructions tell participants about the ideal settings
(3) by default participants are told the explosionpoints for balloons that did not pop (setting can be edited)
(4) script can be run with a prefixed sequence of explosionpoints or with randomly determined
explosion points for each balloon (editable values)

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________
Participants are given 30 (default) balloons and are asked up front to indicate how often they want to pump 
up each balloon.
For each successful pump, they can earn money. However, if a balloon pops before the indicated number of pumps
is reached, participants lose all their potential winnings for the current balloon.

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

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

(1) Raw data file: 'autobart_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. 
										
(parameter) fixed_explosionsequence:	true = runs the same explosion point sequence for all participants (default)
										false = explosion point is randomly determined for each balloon 

																				
ballooncount:					running total of number of balloons
totalearnings:					sums up the earnings across balloons

explosionpoint:					the number of pumps after which the current balloon pops/would have popped
									Note: if parameters.fixed_explosionsequence = false and balloon did not pop:
									values.explosionpoint is randomly determined afterwards

explosion:						0 = balloon did not explode
								1 = balloon exploded

wantedpumps:					number of times participant WANTS to pump up a balloon (resets for each balloon)
pumpcount:						number of times a balloon actually gets pumped up (resets for each balloon)
pumpresult:						the selected digit from list.pumpresult (only relevant if parameters.fixed_explosionsequence = false)
									Note: if 1 -> balloon pops
										
timebefore1stpump:				time it takes participant to decide on wanted number of pumps for each balloon 

response:						the participant's response
									Note: only openended.pumpinput could collect response data
										
latency: 						the response latency
									Note: see values.timebefore1stpump (is the same in the autoBart)

									
(2) Summary data file: 'autobart_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)

(parameter) fixed_explosionsequence:	true = runs the same explosion point sequence for all participants (default)
										false = explosion point is randomly determined for each balloon 								

totalearnings:					sums up the earnings across balloons


ballooncount:					running total of number of balloons
total_explosions:				the number of exploded balloons
nonexplodedballoons: 			the number of balloons out of (default) 30 that did NOT explode

total_wantedpumps:				number of wanted pumps across all balloons (whether or not it came to it)
average_wantedpumps:			the mean pump count that participant wanted to pump up each balloon (includes exploded balloons)
std_wantedpumps:				estimated Standard Deviation of wanted pumps 

totalpumpcount:					total number of actual pumps across balloons
averagepumpcount:				the mean number of actual pumps per balloon (includes exploded balloons) 
std_pumpcount:					estimated Standard Deviation of actual pumps (across all balloons, exploded and not)

adjustedtotalpumpcount:			sums up the actual pumps of balloons that did not explode (= the number of pumps that participant indicated for non-exploded balloons)
adjustedaveragepumpcount:		mean number of pumps only of balloons that did not explode (= the number of pumps that participant on average indicated for non-exploded balloons) (=Dependent Variable) 
std_adjustedpumpcount:			estimated Standard Deviation of actual pumps of non-exploded balloons

as well as respective summary statistics (but no STDs) separated for the first 10 trials (1-10), the second 10 trials (11-20) 
and the last 10 trials (21-30)

___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	
* 30 ballons to pump up (default)
* participants indicate up front how many times the balloon should be pumped up
* each (successful) pump increases the possible reward gained from this balloon
* the probability of popping is by default 1/128; explosionpoints are either fixed (parameters.fixed_explosionsequence = true) or
random (parameters.fixed_explosionsequence = false)
	=> If explosion points are random, they get determined by runtime by the same algorithm used for the BART.iqx:
	script samples randomly without replacement from a list of numbers 1-128: once the 1 gets sampled, the balloon pops.
	The probability that the 1 gets sampled increases with each successful pump (-> list.pumpresult).

	=> If explosion points are fixed, the original BARTY (youth BART, Lejuez et al, 2007) sequence 
	is used in this script (-> list.fixed_explosionpoints)

* after 30 balloons have been pumped, the experiment is over, and participants are given their final winnings
* script collects several measures that track the responses to the first 10, the second 10, and the third 10 balloons separately

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________
Instructions are not original but are based in part on Pleskac et al (2008).
Instructions can be easily 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:

/ totalballoons: 					Number of balloons: Default is 30 
										Note: this script includes summary variables that distinguish between the first 10, the second 10, and the third 10 balloons.

/ pumpvalue: 						Payoff per pump: Default is $.05

/ balloonsizeincrement: 			Ballon size increment in scale proportion to the original image

/ showpumpcount: 					Show current pump count
										true: pump count is shown to participant  (default)
										false: pump count is not shown to participant

/ showballooncount: 				Show current balloon count: 
										true: ballon count is shown to participant  (default)
										false: ballon count is not shown to participant

/ showpotentialearnings: 			Show potential earnings for the current balloon (default)

/ revealexplosionpoint:				true = reveals explosionpoints of non-popped balloons (default)
									false = does not reveal explosionpoints of of non-popped balloons

/ fixed_explosionsequence:			true = runs the same explosion point sequence for all participants (default)
									false = explosion point is randomly determined for each balloon 

Durations:
/ pumpduration:						the time it takes for one pump in ms (default: 50ms)
/ revealduration:					the time the explosion point of a non-popped balloon is presented at the end of the sequence