User Manual: Inquisit Emotional Adaptive Dual N-back Task


___________________________________________________________________________________________________________________	

								*Emotional Adaptive Dual nback Task*
___________________________________________________________________________________________________________________	

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

Script Copyright © 10-11-2024 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	

This Inquisit script provides trials and instructions for adaptive DUAL n-back tasks with words and paired images
that appear in 16 different screen locations (see Schweitzer et al, 2013). 

This script is uses the Inquisit framework of the dual n-back script that
follows the procedure for adaptive dual nback tasks provided by Jaeggi et al (2010).
This script provides code to run N=1 to infinite levels of N.

Reference:
Jaeggi S.M, Studer-Luethi, B., Buschkuehl, M, Su, Y.-F., Jonides, J., Perrig, W.J. (2010). The relationship between n-back performance
and matrix reasoning - implications for training and transfer. Intelligence, 38, 625-635.

Schweizer,S., Grahn,G., Hampshire,A., Mobbs,D. and Dalgleish, T. (2013). Training the Emotional Brain: Improving Affective Control
through Emotional Working Memory Training. The Journal of Neuroscience, 33(12):5301–5311

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	

In dual n-back tasks, participants are presented with two sequences of stimuli in two modalities at the same time
Here:
a) VISUAL: a random sequence of images (paired with auditory words) that can be presented in 
16 different locations on the screen  and 
b) AUDITORY: a random sequence of 20 spoken words 
In each trial one visual and one auditory stimulus are presented and participants are asked to indicate 
whether the currently presented stimuli fulfill the following criteria:

for N=1 trials:
- is the location of the image the same as the one  in the previous trial? If so (it's a target), and press "A".  
If not, don't press "A".

- is the word the same as the one in the previous trial? If so (it's a target), and press "L". 
If not, don't press "L".

for N=2 trials:
- is the location of the image the same as the one  two trials before? If so (it's a target), and press "A". If not, don't press "A".
- is the word the same as the one two trials before? If so (it's a target), and press "L". If not, don't press "L".

etc.

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

___________________________________________________________________________________________________________________	
DATA OUTPUT DICTIONARY
___________________________________________________________________________________________________________________	
The fields in the data files are:

(1) Raw data file: 'emotionaladaptivedualnback_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. 

totalBlocks:					the total number of experimental blocks run
n:								the type of N-back trial

startTrialCounter:				counts the number of start trials run

visualStim:						image presented
vPosition:						contains the position of the current image (1-16)
xpos:							horizontal coordinate of the current image position (proportion of canvas)
ypos:							vertical coordinate of the current image position (proportion of canvas)
vCurrentTarget:				the position number of the current target shape
audioStim:						audio Stim presented
aStimNumber:					contains item number of the currently presented text
vCurrentTarget:				the item number of the current target text

response1:						the value of the first response (if any)
response2:						the value of the second response (if any)

correct:						1 = if correct response, 0 = otherwise

latency1:						the latency value of response1 (in ms)
latency2:						the latency value of response2 (in ms)
latency:						the latency value of the last response made (if any), MAX=3000 (=no response made)

trialHitv:						trial Hit for visual stimulus (1 = hit, 0 = no hit) (visual Hit: any trial response -either the first or the second- for a visual target)
trialMissv:						trial Miss for visual stimulus (1 = miss, 0 = no miss) (visual Miss: no trial response for a visual target if a visual target was presented)
trialCRv:						trial Correct Rejection  for visual stimulus (1 = CR, 0 = no CR) (visual CR: no trial response for a visual target if no visual target was presented)
trialFAv:						trial False Alarm for visual stimulus (1 = FA, 0 = no FA) (visual FA: any trial response for visual target -either the first or the second- if no visual target was presented)
trialHita:						trial Hit for auditory stimulus (1 = hit, 0 = no hit) (auditory Hit: any trial response -either the first or the second- for an auditory target)
trialMissa:						trial Miss for auditory stimulus (1 = miss, 0 = no miss) (auditory Miss: no trial response for an auditory target if an auditory target was presented)
trialCRa:						trial Correct Rejection  for auditory stimulus (1 = CR, 0 = no CR) (auditory CR: no trial response for an auditory target if no auditory response was presented)
trialFAa:						trial False Alarm for auditory stimulus (1 = FA, 0 = no FA) (auditory FA: any trial response for an auditory target -either the first or the second- if no auditory response was presented)

vHits:							the number of Hits for visual modality
vFalseA:						the number of False Alarms for visual modality
 v_Misses:						the number of Misses for visual modality
vCorrReject:					the number of Correct Rejections for visual modality
aHits:							the number of Hits for auditory modality
aFalseA:						the number of False Alarms for auditory modality
 a_Misses:						the number of Misses for auditory modality
aCorrReject:					the number of Correct Rejections for auditory modality
consecutive3:					1 = at some point during the block, participant responded correctly to 3+ consecutive trials; 0 = otherwise 
consecutive5:					1 = at some point during the block, participant responded incorrectly to 5+ consecutive trials; 0 = otherwise


(2) Summary data file: 'emotionaladaptivedualnback_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)
								
totalBlocks:					the total number of blocks run

/////////////////////////
visual modality
/////////////////////////

vTargetTrialCounter:			the total number of visual target trials run
vTotalHits:						the number of total hits across all experimental blocks for the visual modality
vHitRate:						the visual hit rate (responding correctly to a visual target)
vMissRate:						the visual miss rate

vNontargetTrialCounter:			the total number of visual nontarget trials run
vTotalFA:						the number of total false alarms across all experimental blocks for the visual modality							
vFaRate:						the visual FA rate (responding to a NON visual target)
vCrRate:						the correct rejection rate for visual nontargets

//signal detection measures
Note: *Adjustments to z-scores as recommended by:
Gregg, A. & Sedikides, C. (2010). Narcissistic Fragility:
Rethinking Its Links to Explicit and Implicit Self-esteem, Self and Identity, 9:2, 142-161 (p.148)										
=> Adjustments are made if the  FArate (hitRate) = 0 (increased to 0.005) or 1 (decreased to 0.995)*

zVHitRate:			the z-score of the visual hitrate
zVFARate:			the z-score of the visual FA rate

dPrimeVisual:		difference btw. (zscore of hitrate - zscore of FArate): measure of Sensitivity
						=> Range (in this script): 
						-5.1516586840152740479 <= dprime <= 5.1516586840152740479 (=perfect performance)
						=> The higher the value, the better signals  were overall distinguished from noise 
						(d' = 0: chance performance; negative d-primes: participant treated nontargets as targets and targets as nontargets)									

cVisual: 			c-criterion in signal detection:The absolute value of c provides an indication of the strength of
					the response bias/response style
					negative: participant more likely to report that signal is present (liberal response style);
					may favor faster responding in speed-accuracy trade-off response paradigms
					positive: favoring caution (conservative response style)


/////////////////////////
auditory modality
/////////////////////////

aTargetTrialCounter:			the total number of auditory target trials run
aTotalHits:						the number of total hits across all experimental blocks for the auditory modality
aHitRate:						the auditory hit rate (responding correctly to a auditory target)
aMissRate:						the auditory miss rate

aNontargetTrialCounter:			the total number of auditory nontarget trials run
aTotalFA:						the number of total false alarms across all experimental blocks for the auditory modality							
aFaRate:						the auditory FA rate (responding to a NON auditory target)
aCrRate:						the correct rejection rate for auditory nontargets

zAHitRate:						the z-score of the auditory hitrate
zAFARate:						the z-score of the auditory FA rate

dPrimeAudio:					difference btw. (zscore of hitrate - zscore of FArate): measure of Sensitivity
cAudio: 						c-criterion for auditory modality


aTotalHits:						the number of total hits across all experimental blocks for the auditory modality
vTotalFA:						the number of total false alarms across all experimental blocks for the visual modality
aTotalFA:						the number of total false alarms across all experimental blocks for the auditory modality

__________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	
(1) Dual n-back Experiment (adaptive) information:
- participants start out at level N = 1 and depending on performance, move up or stay on level N = 1

N increase: 3+ consecutive trials correct
N decrease: 5+ consecutive trials incorrect

"if 3+ consecutive trials were completed accurately,
the level of n-back increased by one on the next block. Conversely, if five
or more successive trials were completed inaccurately, the level of n-back
decreased by 1 on the next block." (Schweitzer et al, 2013, p.5303)

(Note: if both events occur in one trial, the N stays effectively the same in this script)

- After a total of 20 blocks, the experiment ends

(2) Dual n-back BLOCK information:
- Each dual n-task block consists of 20 + trials. 
=> + trials are the N trials that cannot display target shapes yet (=start trials). Their numbers vary depending on N. The data collected during these 
		start trials are NOT included in performance counts for Correct Rejections/False Alarms.
=> Of the actual  20 experimental trials, 4 present a visual target only, 4 present an auditory target only, 2 present both targets
and 10 present no targets at all
- The computer selects randomly 
a) which kind of trial 
b) what word/ image location to use if it is not a target

(3) Dual n-back TRIAL information:
- Each trial presents the image/word for 500ms and waits another 2500ms before ending the trial. 
Another 500ms are reserved for auditory feedback before the next image/word in the sequence are presented.
- Participants have 3000ms to respond by pressing "A", "L", or both if they detect a target or two.

___________________________________________________________________________________________________________________
STIMULI
___________________________________________________________________________________________________________________

Visual Stimuli:
- 20 example stimuli taken from NIMSTIM (2 female sets with 5 images, 2 male sets with 5 images)
The images can easily be exchanged under: item.images under section EDITABLE STIMULI

Note: each block randomly selects 1 female and 1 male set (10 stimuli total per block)
(across the 20 blocks each set is run equally often)

Auditory Stimuli:
- this script uses 10 auditory stimuli (10 negative adjectives recorded by a female American native speaker)
The stimuli can be exchanged under: item.audiowords under section EDITABLE STIMULI

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	

The instructions are not original to Schweizer et al (2013). They are based on the instructions used for
Adaptive Dual n-back task by Jaeggi et al (2010).

The instructions are presented by using Scalable Vector Graphics (SVG) images.
Check section EDITABLE INSTRUCTIONS for more information.

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

/startN:						the starting N (Note: StartN > 0), default: 1
/numberTestBlocks:				Number of test blocks run (default is 20)

/stimulusPresentationTime:		the presentation time (in ms) of the stimuli (default: 500ms)								
/soa:							the stimulus onset asynchrony in ms (default: 3000ms); also Response Window
								!!!In this script: Response Window = 3000 ms + 500 ms feedback => actual SOA is 3500ms (500ms more than advertised)

/imageSize:						the size of the images in proportion to the canvas height (here: 23%)									

/debugmode:						Debugmode = 1, target alerts are presented
								Debugmode = 0, target alerts are turned-off (default)