User Manual: Inquisit Balloon Popping Task


___________________________________________________________________________________________________________________	

						Balloon Popping: Child friendly Extinction Learning Task
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 05-18-2022
last updated:  11-05-2024 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 11-05-2024 Millisecond Software
___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________
This script implements Millisecond Software's version of the Balloon Popping Task, an Extinction Learning Task
described by Semmelmann et al (2016) for young children.
Extinction learning refers to the decrease in a behavior after a period of non-reinforcement.

Note the script runs with proportional sizing by default. 
Researchers can select to run the task with an absolute screen size to ensure that distances
stay the same across devices. See section Defaults for more info.

The task was used for children ages 1-3 (and adults as a control group).

Reference:											
Semmelmann et al (2016).U Can Touch This: How Tablets Can Be Used to Study Cognitive Development .
Frontiers in Psychology, 7
URL=https://www.frontiersin.org/article/10.3389/fpsyg.2016.01021     	  
DOI=10.3389/fpsyg.2016.01021 
___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________

The Balloon Popping Task runs in 3 stages:

1. Acquisition Stage:
The screen shows a blue sky with clouds.
2-6 balloons of 2 different colors (e.g. red and yellow) fly from the bottom of the screen to the top.
Participants are encouraged to pop as many balloons as they can. Whenever a balloon is touched,
the balloon is popped and a new balloon appears on screen.
At the acquisiton stage, participants can pop any colored balloon.
By default the Acquisition Stage takes 1.5 minutes

2.Extinction Stage:
The screen changes to an evening sky.
2-6 balloons of 2 different colors (e.g. red and yellow, same as during acquisition) fly from the 
bottom of the screen to the top.
Participants are encouraged to pop as many balloons as they can. Whenever a balloon is touched,
the balloon is popped and a new balloon appears on screen.
During the extinction stage, participants can pop only balloons of one color (randomly decided).
By default the Extinction Stage takes 1.5 minutes

3. Renewal Stage => same as Acquisition Stage
The screen shows a blue sky with clouds (same as during acquisition).
2-6 balloons of 2 different colors (e.g. red and yellow, same as during acquisition) fly from the 
bottom of the screen to the top.
Participants are encouraged to pop as many balloons as they can. Whenever a balloon is touched,
the balloon is popped and a new balloon appears on screen.
At the acquisiton stage, participants can pop any colored balloon.
By default the Renewal Stage takes 1.5 minutes
___________________________________________________________________________________________________________________	
DURATION 
___________________________________________________________________________________________________________________	
the default set-up of the script takes appr. 5 minutes to complete

___________________________________________________________________________________________________________________	
DATA OUTPUT DICTIONARY
___________________________________________________________________________________________________________________
The default data stoballoon2 in the data files are:

(1) Raw data file: 'balloonpoppingtask_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:					with the current subject id
group: 						with the current group id
session:					with the current session id

//Play Setup:
(parameter) runAbsoluteSizes:	true (1) = should run absolutely sized canvas (see parameters- canvasHeightMM)
								false (0) = should use proportionally sized canvas (uses width = 43*screenHeight)
								
playAreaHeightMM:			the width of the play area in mm 
playAreaWidthMM:				the height of the play area in mm 								
								
canvasAdjustments:				NA: not applicable => parameters- runAbsoluteSize was set to 'false'
								0: parameters- runAbsoluteSize was set to 'true' and screen size was large enough
								1: parameters- runAbsoluteSize was set to 'true' BUT screen size was too small and 
								adjustments had to be made


(parameters) numberBalloonsOnScreen: the number of balloons to fly across the screen

(parameters) balloonTravelDurationMS: 	the basic time (in ms) it should take a balloon starting from 100% bottom to 0% top of playarea
balloonSpeedMMPerMS:			the calculated speed of a balloon in mm/ms 
										(Note: depending on playarea size the speed might differ to keep the balloon travel duration 
										constant across monitors)	

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. 
															
response:					the response of participant (which balloon was touched)
correct:					1 = correct response; 0 = otherwise
latency:					response latency (in ms); measured from: onset of trial

//default itemnumbers:1 = green; 2 = red; 3 = blue; 4 = yellow
firstBalloonNumber:			stores the first balloon itemnumber selected for the task
secondBalloonNumber:		stores the second balloon itemnumber selected for the task
targetColor:				stores the randomly assigned target itemnumber ('color')
balloon1:					stores the itemnumber of the balloon image to use for balloon1 
balloon2:					stores the itemnumber of the balloon image to use for balloon2 
balloon3:					stores the itemnumber of the balloon image to use for balloon3 
balloon4:					stores the itemnumber of the balloon image to use for balloon4 
balloon5:					stores the itemnumber of the balloon image to use for balloon5 
balloon6:					stores the itemnumber of the balloon image to use for balloon6
Note: the numbering does not refer to the track that balloon is flying in
the numbering is simply used to distinguish between 6 possible balloons

adjust:						stores the balloon number of the balloon that needs to be adjusted next
							(either if it was popped OR if it reached the top first)
							'-1' => used during phase2 if a balloon was touched that should not explode,
							in this case, the trial ends as if it had popped but not adjustments are made to the
							balloon
							
t1C1: 						stores the number of times that a color1 balloon was touched during time period t1 (0-30s)
t1C2: 						stores the number of times that a color2 balloon was touched during time period t1 (0-30s) 
t2C1: 						stores the number of times that a color1 balloon was touched during time period t2 (30-60s) 
t2C2: 						stores the number of times that a color2 balloon was touched during time period t2 (30-60s) 
t3C1: 						stores the number of times that a color1 balloon was touched during time period t3 (60-90s) 
t3C2: 						stores the number of times that a color2 balloon was touched during time period t3 (60-90s) 	
t1:							marks the end of time period t1 (in scriptelapsedtime) 
t2:							marks the end of time period t2 (in scriptelapsedtime) 
script.elapsedTime:			measures the time the script has been running from beginning

trialTimeout:				stores the current trialtimeout (in ms) => if no balloon is popped, the trial should end after this time
							because that means a balloon has reached the top

//to check trialTimeouts							
balloon1Duration:			the current duration (in ms) that balloon1 should be flying		
balloon2Duration:			the current duration (in ms) that balloon2 should be flying
balloon3Duration:			the current duration (in ms) that balloon3 should be on screen 
balloon4Duration:			the current duration (in ms) that balloon4 should be on screen
balloon5Duration: 			the current duration (in ms) that balloon5 should be on screen
balloon6Duration:			the current duration (in ms) that balloon6 should be on screen


(2) Summary data file: 'balloonpoppingtask_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); measuballoon2 from onset to offset of script
completed:					0 = script was not completed (prematurely aborted); 
							1 = script was completed (all conditions run)
							
//Play Setup:
(parameter) runAbsoluteSizes:	true (1) = should run absolutely sized canvas (see parameters- canvasHeightMM)
								false (0) = should use proportionally sized canvas (uses width = 43*screenHeight)
								
playAreaHeightMM:			the width of the play area in mm 
playAreaWidthMM:				the height of the play area in mm 								
								
canvasAdjustments:				NA: not applicable => parameters- runAbsoluteSize was set to 'false'
								0: parameters- runAbsoluteSize was set to 'true' and screen size was large enough
								1: parameters- runAbsoluteSize was set to 'true' BUT screen size was too small and 
								adjustments had to be made							
							
(parameters) numberBalloonsOnScreen:		the number of balloons to fly across the screen

(parameters) balloonTravelDurationMS: 	the basic time (in ms) it should take a balloon starting from 100% bottom to 0% top of playarea
balloonSpeedMMPerMS:			the calculated speed of a balloon in mm/ms 
										(Note: depending on playarea size the speed might differ to keep the balloon travel duration 
										constant across monitors)	


//default itemnumbers:1 = green; 2 = red; 3 = blue; 4 = yellow
firstBalloonNumber:			stores the first balloon itemnumber selected for the task
secondBalloonNumber:		stores the second balloon itemnumber selected for the task
targetColor:				stores the randomly assigned target itemnumber ('color')
						
propTargetColorPhase1:	overall proportion of target color balloons touched (exploded) during phase1
propTargetColorPhase2:	overall proportion of target color balloons touched (unexploded) during phase2
propTargetColorPhase3:	overall proportion of target color balloons touched (exploded) during phase3

//Phase 1: Acquisition	
Note: color1 = target color (the color that is unpoppable during stage2)						
phase1T1C1:				number of balloons of color1 popped during timeinterval t1 during phase1 
phase1T1C2:				number of balloons of color2 popped during timeinterval t1 during phase1 

phase1T2C1:				number of balloons of color1 popped during timeinterval t2 during phase1  
phase1T2C2:				number of balloons of color2 popped during timeinterval t2 during phase1 

phase1T3C1:				number of balloons of color1 popped during timeinterval t3 during phase1 
phase1T3C2:				number of balloons of color2 popped during timeinterval t3 during phase1


//Phase 1: Extinction							
phase2T1C1:				number of balloons of color1 popped during timeinterval t1 during phase2 
phase2T1C2:				number of balloons of color2 popped during timeinterval t1 during phase2 

phase2T2C1:				number of balloons of color1 popped during timeinterval t2 during phase2  
phase2T2C2:				number of balloons of color2 popped during timeinterval t2 during phase2 

phase2T3C1:				number of balloons of color1 popped during timeinterval t3 during phase2 
phase2T3C2:				number of balloons of color2 popped during timeinterval t3 during phase2 


//Phase 3: Renewal							
phase3T1C1:				number of balloons of color1 popped during timeinterval t1 during phase3 
phase3T1C2:				number of balloons of color2 popped during timeinterval t1 during phase3 

phase3T2C1:				number of balloons of color1 popped during timeinterval t2 during phase3  
phase3T2C2:				number of balloons of color2 popped during timeinterval t2 during phase3 

phase3T3C1:				number of balloons of color1 popped during timeinterval t3 during phase3 
phase3T3C2:				number of balloons of color2 popped during timeinterval t3 during phase3 
 
							
___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	

(1) Intro with option practice 
Optional Practice: presents one balloon of a color not used during the actual task (purple).
The balloon flies from the bottom to top on a sky not used during the actual task 
(same speed as used during the task).
Participants get 10s (editable parameter) to practice popping the flying balloon
(over and over again)

(2) Phase1: Acquisition Stage (blue sky with some clouds)
2-6 balloons (editable parameter) of two randomly selected colors 
(e.g. red and green out of four possible: green, red, blue, yellow)
fly from the bottom to the top of the screen at a speed of  1/50 mm/ms (editable value).
The two colors are assigned randomly WITHOUT replacement for each balloon
(reset after 2 color assignments).
Participants get 90s (editable parameter) to pop as many of the flying balloons as they can.
Participants can pop balloons of any color.
Balloons are replaced if they are
a) popped
b) reached the screen top
In that case, a new balloon flies in from the bottom (color randomly determined WITHOUT
replacement).
=> half of the replaced balloons are color1 (color2)

(3) Phase2: Extinction Stage (evening sky with some clouds)
2-6 balloons (editable parameter) of two randomly selected colors (same colors as during phase1)
fly from the bottom to the top of the screen at a speed of  1/50 mm/ms (editable value).
The two colors are assigned randomly WITHOUT replacement for each balloon
(reset after 2 color assignments).
Participants get 90s (editable parameter) to pop as many of the flying balloons as they can.
Participants can only pop balloons of a randomly selected color.
Balloons are replaced if they are
a) popped
b) reached the screen top
In that case, a new balloon flies in from the bottom (color randomly determined WITHOUT
replacement).
=> half of the replaced balloons are color1 (color2)

(3) Phase3: Renewal Stage (blue sky with some clouds - same as during phase1)
2-6 balloons (editable parameter) of two randomly selected colors (same colors as during phase1)
fly from the bottom to the top of the screen at a speed of  1/50 mm/ms (editable value).
The two colors are assigned randomly WITHOUT replacement for each balloon
(reset after 2 color assignments).
Participants get 90s (editable parameter) to pop as many of the flying balloons as they can.
Participants can pop balloons of any color.
Balloons are replaced if they are
a) popped
b) reached the screen top
In that case, a new balloon flies in from the bottom (color randomly determined WITHOUT
replacement).
=> half of the replaced balloons are color1 (color2)

////Algorithm to place balloons on screen:///
The computer calculates the horizontal coordinates for 6 tracks that can be used to fly
balloons. At the start of a phase, each balloon is randomly assigned to one of these tracks.
The y-coordinate is randomly jiggled to be somewhere from 105% to 120% (aka below the screen),
so starting balloons don't appear on screen at the same exact time.
Replacement balloons are randomly assigned to any track with the constraint that
a minimum distance (calculated based on image height) to another balloon in the same track 
has to be maintained.

___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________

provided by Millisecond Software - can be edited under section 'Editable Stimuli'
images taken from: https://pixabay.com/images/ (free to use for commercial use - no attribution required)
applause sound taken from: https://freesound.org/ (Creative Commons license)

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________

provided by Millisecond Software - can be edited under section 'Editable Instructions'
The instructions are not original to Semmelmann et al (2016)
___________________________________________________________________________________________________________________	
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:

/ runAdjustmentRoutine = true			//true: at script onset the script runs a procedure that allows test
										//administrators to adjust 
										//a) the number of balloons on screen
										//b) the balloon travel time across the screen
										//false: adjustment procedure is not run

/ skipPractice = false					//false: the script runs a practice session (can be repeated)
										//true: no practice phase is run
																			
/ numberBalloonsOnScreen = 6				//suggested: 2,4,6 (to show the same number of balloons of both colors)
										//Range: 2-6
										//Note: if parameters.runAdjustmentRoutine = true, this number can
										//be adjusted after the practice (if practice is run)
										


//timing parameters										
/ practiceDuration = 10000				//the duration (in ms) of the optional practice 									
/ phase1Duration = 90000				//the duration (in ms) of the acquisition stage (phase1)			
/ phase2Duration = 90000				//the duration (in ms) of the extinction stage (phase2)		
/ phase3Duration = 90000				//the duration (in ms) of the renewal stage (phase3)

/ balloonTravelDurationMS = 7000		//the time (in ms) that a balloon takes to travel from bottom to top of screen
										//Note: the balloonTravelDuration is kept constant across differently sized monitors
										//to allow each participant the same time to pop balloons on the screen


//color parameter
/ canvasColor = black					//Display color of the actively used portion of the screen (the 'canvas')
										//Note: if set to a color other than the screenColor, you can distinguish the active canvas
										//from the inactive portion of the screen
									
/ screenColor = black 					//Color of the screen not used by the canvas ('inactive screen')
/ defaultTextColor = white				//Default color of text items

//CANVAS SIZING PARAMETERS
//sizing Parameters in RELATIVE measurements relative to CANVAS HEIGHT
//NOTE: to run the script with ABSOLUTE screen measurements, go to 'defaults' and set 
//canvasSize to absolute measurements																
																		
//Sizing Parameters	
/ balloonSizePct = 30%					//proportional height of the image file (not the balloon)