User Manual for Inquisit's BIRD Task - ABCD Consortium - Tablet


___________________________________________________________________________________________________________________	

											ABCD BIRD TASK
											(tablet version)
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: Nov 2014
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 runs the ABCD Research Consortium version of the Inquisit BIRD task optimized
for tablet (in person testing) use. A smartphone version (remote testing) is also available
through the Millisecond Software Task library.
The script was generously made available by the ABCD Research Consortium.

Bird Reference:
Daughters, S.B, Reynolds, E.K., MacPherson, L., Kahler, C.W.,  Danielson, C.K., Zvolensky, M. & Lejuez, C.W. (2009). 
Distress tolerance and early adolescent externalizing and internalizing symptoms: The moderating role of gender and ethnicity.
Behaviour Research and Therapy, 47, 198–205.

The Bird task is a child version of the computerized distress tolerance task PASAT-C by Lejuez et al (2003)	
(see Millisecond Software's PASAT-C.iqx)
___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	
A green dot appears above 1 out of 10 possible boxes and participants are asked to click the box as fast as possible.
If participants click the box before the trial times out, a bird is set free from its cage and participants win a point.
If participants are not fast enough, the bird remains in the cage and no points are won.
The goal of the game it to win as many points as possible.
Participants work through 3 levels with the last level being the most challenging in terms of timing.
During level 3, participants have the option to quit prematurely (=measure of distress tolerance).

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


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

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

 scriptlastupdate:	should store the date of the last change made to the script

build:						Inquisit build
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
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.
										
counttrials:				counts all freebird trials within a level
dotposition:				(box) 1-10
stimulusitem:				the presented stimuli in order of trial presentation
response:					the participant's response
correct:					the correctness of the response (1 = correct; 0 = incorrect)
latency: 					the response latency (in ms)
trialdotlatency: 			the max. time the current dot is presented before a new trial is started (used for trial timeout)
score:						stores the current scorecount


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

inquisit.version: 			Inquisit build
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)

score:						stores the final scorecount
meandotlatency:				stores the mean dot latency (in ms) of level 1 (response latency of correct and incorrect responses)
challengelatency:			stores the challenge dot latency (= 1/2 of the mean dot latency in level 1)

quit:						1 = participant quit level 3 prematurely; 
							0 = participant did not quit level 3
								
level3duration:				stores the time spent on level 3 
level1correct:				stores the correct responses for level1
level2acorrect:				stores the correct responses for level2A
level2bcorrect:				stores the correct responses for level2B
level2correct:				stores the combined correct responses for level 2
level3correct:				stores the correct responses for level3

+ rating responses for pre/post ratings for Anxiety, Frustration, Irritability, Happiness


___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________
3 levels:
Level1: used to calculate participant's mean dot latency (~ latency at which the dot moves that participant can still 'beat'); 
2 min duration
Note: the starting dot latency is set at 5000ms.
Success => dot latency is reduced by 500ms (editable parameter)
Failure => dot latency is increased by 500ms
Level2A: uses mean dot latency for 2 min (default timing; can be edited)
Level2B: uses challenge dot latency ( = mean dot latency / 2) for 1 min (default timing; can be edited)
Level3: uses challenge dot latency for 6 min (default timing; can be edited) with the option to quit/escape prematurely

In this script, the feedback (success = bird flies away & happy chirp; failure = bird stays in cage; sad chirp)
takes 100ms (default; can be edited) => therefore the SOA btw. dots = current dot latency + feedback duration).


___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________
Stimuli are provided by Millisecond Software and can be exchanged under section
EDITABLE CODE -> Editable Stimuli

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
Instructions are provided to Millisecond Software

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

/birdincagesize:					sets the size of the bird in the cage picture (default: 20% of canvas height)

Timeouts: sets the block timeouts for the various levels in ms (Note: level 2 is split in level2A and level2B in this script)
/level1_timeout = 120000          	=> 2 Minutes  
/level2A_timeout = 120000			=> 2 Minutes
/level2B_timeout = 60000			=> 1 Minute
/level3_timeout = 360000			=> max. 6 Minutes

/startdotlatency:					sets the start dot latency for Level 1 trials in ms (default: 5000ms)
/level1_dotlatency_adjust:			defines the adjustment to the dot latency during Level1 depending on success (decrease) or failure (increase) in ms (default: 500ms)
/feedbackduration:					sets the duration of the success/failure feedback in ms (default: 100ms)
									=> Stimulus Onset Asynchrony (dots) = current dot latency + feedbackduration

/winpoints:							sets how many points participants win for each successful response (default: 1)