User Manual: Inquisit Cognitive Effort Discounting Task


						Cognitive Effort Discounting Task (with n-back task)

Script Author: Katja Borchert, Ph.D. ( for Millisecond Software LLC
last updated:  04-17-2023 by K. Borchert ( for Millisecond Software, LLC

Script Copyright © 04-17-2023 Millisecond Software

Millisecond Software thanks Jenny Crawford and her lab at Washington University in St. Louis 
for help fine-tuning this Cognitive Effort Discounting Task procedure!

This script implements a variant of the Cognitive Effort Discounting Procedure to establish
indifference points (minimum price points) at which people start to discount ("devalue") monetary rewards
paid for higher effort tasks in favor of less paid lower effort tasks.

This script uses the n-back procedure as the cognitive task.

Reference for the n-back Cognitive Effort Discounting Procedure*:									
Westbrook A, Kester D, Braver TS (2013). What Is the Subjective Cost of Cognitive Effort? Load,
Trait, and Aging Effects Revealed by Economic Preference. 
Pessiglione M, ed. PLoS One 981 8:e68210.	

*Note: the script runs an updated version of the procedure used in the Braver Lab 
at Washington University in St. Louis)											
Participants are repeatedly asked to choose between a more difficult cognitive task with
a higher earning potential or an easier cognitive task with less earning potential.
Through a series of questions the participants' cognitive effort indifference point for the pair
of tasks is determined (aka the price point at which participants start to devalue the potential
higher pay for a challenging cognitive task in favor of less pay for a less challenging one).
In this script, the cognitive task chosen is the n-back working memory task.
4 levels of n-back tasks are used in this task (editable) with the 1-back being the designated 'easy' task.

The procedure is divided into 3 phases:

1. Participants get familiar with the n-back procedure and work through several rounds of n-back tasks for the 
different levels of N. The n-back levels are referred to by assigned colors.

2. Participants work through the indifference point estimation procedure (without actually performing the n-back tasks)
for the 3 higher levels of N (1 vs.2; 1 vs. 3; 1 vs. 4)
=> 3 indifference points are estimated for each level of N tested

3. One of the participant's choices is randomly selected, the participant works through 5 (default) more rounds
of n-backs with the selected N and promised reward.
*N-back Task (with letter stimuli)*
*2-key n-back procedure*
The 2-key n-back task requires participants to press one key for targets (go) and
another key for non-targets. Which stimuli are targets depends on the level of N:										
for N=1 trials (1-back):
- is the letter the same as the one that preceded it? If so (it's a target), and press "S". If not, press "K".

for N=2 trials (2-back):
- is the letter the same as the one presented two trials before? If so (it's a target), and press "S". If not, press "K".

for N=3 trials (3-back):
- is the letter the same as the one presented three trials before? If so (it's a target), and press "S". If not, press "K".


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

The default data stored in the data files are:

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

phase1BlockCount:					the total number of n-back practice blocks run (phase 1)
phase3BlockCount:					the total number of phase 3 n-back blocks run

phase:								1 = n-back practice
									2 = indifference point assessment
									3 = final n-back runs to earn money
N:									the level of N currently tested								

stimulusitem.1:						phase1/phase3: n-back trials: the letter presented																
stimulusnumber.1: 					n-back trials: the item number of the presented letter

currenttarget:						n-back trials: the item number of the current target

response:							the response of the participant (scancode of response button)
									nback trials:
									31 = S (for n-back trials: correct target response)
									37 = K (for n-back trials: correct notarget response)
									choice trials:
									16 = Q (left box selected during Choice Trials)
									25 = P (right box selected during Choice Trials)
									remaining trials:
									57 = spacebar
									0 = no response
correct:							the correctness of the response (1 = correct; 0 = otherwise)
									Note: has no meaning for phase 2 trials
latency:							how fast a participant responded within the given timeframe (in ms)
									Phase1/Phase3: n-back trials => latencies of 1500ms (stimulus presentation time) are no responses

the following variables have only meaning for phase2:									
N1_x:								25pct = the N1 reward was located in the left box
									75pct = the N1 reward was located in the right box
level1Reward:						Phase 2: the currently offered reward for choosing the 1-back task									
levelNReward:						Phase 2: the currently offered reward for choosing the higher level N-back task							

the following variables have only meaning for phase3:
RoundWinAmount: 					Phase 3: the amount won after the current phase 3 round
TotalWinAmount:						Phase 3: the total amount won during phase 3

//current NASATLX summary variables: on scale: 1 (very low) - 21 (very high)
(2) Summary data file: 'cognitiveeffortdiscountingtask_summary*.iqdat' (a separate file for each participant)

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

IP12-IP16:							indifference points 
									(here: level1Reward after the 6th choice for the currently tested level of N)
TotalWinAmount:						the total win amount from phase 3								
hitrate_N6:							store the hitrates (targets) for N levels 1-6 during phase 1 (across all rounds for each N-level)
									hit = pressing 's' for a target trial
CRrate_N6:							store the correct rejection (non-targets) rate for N levels 1-6 during phase 1 (across all rounds for each N-level)			 	
									CR = pressing 'k' for a non-target trial
//NASATLX summary variables (per level of Nback run during phase 1): on scale: 1 (very low) - 21 (very high)								


3 phases:

(1) Phase 1: n-back Practice

- by default, this script runs through 1 run of N-levels 1-4 (see section Editable Parameters to select N-levels and/or change number
of rounds) => 4 blocks of n-backs

- each n-back block runs for 20 trials (see section Editable Parameters to change the number of trials; the start trials that
cannot be target yet are not counted towards the trialcount)
Note: Westbrook et al (2013) ran 64 trials per block.

- each block runs 25% targets (here: 5 target trials) (see section Editable Parameters to change the proportion)
!!!This script does not run target-lure trials (see Westbrook et al, 2013, p.2)
- the order of targets and nontargets is randomly determined

- this script uses a 2 key n-back procedure: one key (S) is used for target identification; another (K) for nontarget identification

- each level of N is assigend a particular letter color
Note: the level of N is only referenced by assigned color
N1 = black
N2 = red
N3 = blue
N4 = purple
N5 = green
N6 = brown

- at the end of each block, participants receive feedback

Trial Sequence:
Letter (1500ms = response timeout) -> Fixation Cross (2000ms) -> Letter.....

Responses are only registered during letter presentations. Responses do not interrupt letter presentations. 

Note: after each level participants are asked to self-report on the 6 rating scales of the NASA TASK LOAD INDEX- Survey:

(2) Phase 2: Indifference Point Estimations
- 3 Indifference Points for level of N tested (e.g. 3 different standard amounts are offered for each level of N)
- by default this script runs 54 trials = 3 levels of N (2, 3, 4) x 3 IPs per N level x 6 trials
- the trials are presented in random order in a mixed design
- level of n-backs are referred to only by color
- the position (right/left) of the standard amount is randomly determined:
half the trials the standard amount appears on the right
- participants have 9s to make a choice (after 9s the black task is automatically assigned as the default choice)

Indifference Point Algorithm:
- the harder level N always offers a higher (fixed) reward (see section Editable Parameters),
- the possible reward for the easier 1-back starts at 1 but gets adjusted according to the choices made:
	- if the harder choice was previously selected; the reward goes up (by half the previous adjustment)
	- if the easier choice was previously selected; the reward goes down (by half the previous adjustment)
- Indifference Points: the adjusted reward for level 1 after the last choice (aka: the reward offered for level 1 on the 
7th round)

(3) Phase 3: Actual Money Earning Phase  (can be skipped; see parameters.phase3Runs for more info)
- one of the 3 (level of N: 2-4) * 6 (trials per level of N) * 3 indifference points per n-level = 54 choice trials
from Phase 2 is randomly selected by the computer
- the chosen N during that trial as well as the promised reward is used for another 5 (editable)
rounds of n-backs

This script does not provide any behavioral measure of actual 'effort' during phase 3
* the n-back task runs with consonants (see section Editable Stimuli)
* the size of the letters can be adjusted under section Editable Parameters

provided by Millisecond Software as *.htm files.
To change instructions, edit the htm files directly (e.g. in TextEdit for Macs or Notepad for Windows).
Instructions have been generously shared by Jenny Crawford and her lab

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: