User Manual: Inquisit UNRAVEL Task


___________________________________________________________________________________________________________________	

										UNRAVEL
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 01-25-2017
last updated:  03-02-2022 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 03-02-2022 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	
This script implements the UNRAVEL paradigm, a test of placekeeping ability: the ability to perform the steps
of a complex task in a prescribed order without skipping or repeating steps.
Each letter in the acronym UNRAVEL stands for one of seven distinct categorization tasks that need to be performed
in repeated sequences without external reminders of the target task at any one point - even after distractor tasks. 
Each of the tasks has designated response keys. The use of a particular response key is thus indicative of
of the task being performed. 

This task requires the use of a keyboard. If the script cannot find a keyboard, an alert is given and the script
is automatically terminated.

Reference:

Altmann, E. M., Trafton, J. G., & Hambrick, D. Z. (2014). Momentary
interruptions can derail the train of thought. Journal of Experimental
Psychology: General, 143, 215–226


Millisecond Software thanks Dr. Eric Altmann for his collaboration on this script!

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	
On each trial participants see a character inside a box and another character outside of it (above or below the box).
The characters are presented in opposite corners (e.g. if one is presented on the left side of the box,
the other is presented on the right side of the box).
One of the characters is a letter (default letters used: A, B, V, U) and the other a digit (default digits: 1, 2, 8, 9). 
One of the characters is colorful (red or yellow), the other is white. 
One of the characters is formatted (underlined or italicized) and the other one isn't.

Participants are asked to work through seven 2FC tasks in sequence without prompts telling them which 
task to perfrom on any given trial other than the acronym 'UNRAVEL' as a sequence guide:
1. U: is the formatted character underlined (press U) or italicized (press I)
2. N: is the letter near (press N) or far (press F) the start of the alphabet 
3. R: is the colorful character red (press R) or yellow (press Y)?
4. A: is the character outside the box above it (press A) or below it (press B)?
5. V: is the letter a vowel (press V) or a consonant (press C)?
6. E: is the digit even (press E) or odd (press O)
7. L: is the digit less than 5 (press L) or more than 5 (press M)?
Because each task uses unique response keys, the choice of response key on any given trial indicates 
the type of task (and its place in the UNRAVEL sequence) performed.
On average, every 6 trials a distractor task (interruption) is presented: twice participants are asked to
enter a displayed code into a textbox. Only if the code is entered correctly, is the participant returned
to the current place in the UNRAVEL trial sequence.

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

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

(1) Raw data file: 'unravel_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. 
										
testBlockCount:					counts the number of UNRAVEL test blocks run

trialcount:						counts the unravel trials in each block (demo, practice, testblocks)
									Note: during practice and test, the same unravel trial can be called several times
									due to errors made (practice) or help menu calls (test).
									The actual trialcount is only updated for each new trial.
									Only UNRAVEL test trials with testTrialCode < 3 (baseline and post-interruption trials) 
									are considered for summary data.

testTrialCode:					1 = baseline UNRAVEL test trial (unravel trials that follows an unravel trial OR is the first trial in a block)
								2 = post-interruption UNRAVEL test trial (after code-interruption)
								3 = 'invalid' unravel test trial (no UNRAVEL response: participant pressed Tab-key to see RULES)
								4 = code-interruption during testing
								"" (empty) for demo trials and practice trials

///Stimulus Make-Up Variables:								
U:								1 = underlined character; 2 = italic character
N:								1 = letter is near the end of the alphabet; 2 = otherwise
R:								1 = character is red; 2 = character is yellow
A:								1 = character is above the box; 2 = character is below the box
V:								1 = letter is a vowel; 2 = letter is a consonant
E:								1 = digit is even; 2 = digit is odd
L:								1 = digit < 5; 2 = digit > 5									
									
letter:							stores the sampled letter for the current trial (letter needs to be in accordance with V and N)
digit:							stores the sampled digit for the current trial (digit needs to be in accordance with E and L)
inside:							stores the actual character (letter or digit) that is selected to be presented inside the box
outside:						stores the actual character (letter or digit) that is selected to be presented outside the box

location:						1 = character is presented to the left inside box/to the right outside box
								2 = character is presented to the right inside box/to the left outside box
								
locationColorChar:				1 = colored character is inside character; 
								2 = colored character is outside character
								
locationFormattedChar:			1 = formatted (underlined/italicized) character is inside character; 
								2 = formatted (underlined/italicized) character is outside character

inside_x:						stores the x-coordinate of the inside character 
inside_y:						stores the y-coordinate of the inside character	(inside character is always at y = 50%)						
outside_x:						stores the x-coordinate of the outside character
outside_y:						stores the y-coordinate of the outside character (needs to be in accordance with A)


desc_insideChar:				stores a description of the inside character (Example: 'inside: right, yellow, underlined B')
desc_outsideChar:				stores a description of the outside character (Example: 'outside: left, above, white, 9')

///Interruption-related Variables:

code:							the code of the current Interruption Trial
interruption:					1 = an interruption should be run after this unravel trial; 0 = no interruption will be run
counter_uninterruptedTrials: 	counts the number of consecutive trials run without an interruption
uninterruptedTrials:			stores the current number of trials that should be run in between interruptions
countBlockInterruptions:		counts the number of interruptions run in a block

DV-Variables:																																		
response:						the participant's response: scancode of response button (or entered code for interruption trials)
responseKeyLabel:				the interpreted key response (Example: 22 = U)								
								
latency: 						the response latency (in ms)
								UNRAVEL Trials: measured from onset of trial until response key is hit
								Interruption Trials: measured from onset of trial until the Return button is hit
								
correct:						the correctness of the response (1 = correct (no sequence error and no nonsequence error); 0 = otherwise)

performedTask_ACC:				1 = currently performed task is performed correctly (regardless of sequence); 
								0 = otherwise
								
blockACC:						proportion of trials in a block where response was correct AND in sequence (per block)								
								
lastTask:						stores the preceding task that participant performed (U, N, R, A, V, E, L)
expectedTask:					the expected task based on the last Task performed
currentTask:					stores the currently performed task (U, N, R, A, V, E, L) based on response key used
		
wrongTask:						1 = the currently performed task is out of sequence with the preceding task (regardless of accuracy); 
								0 = otherwise
								
errorType:						0 = correct response (sequence correct & task performance correct)
								1 = sequence Error (correct): wrong task (out of sequence) was performed BUT the task was performed correctly
								2 = sequence Error (incorrect): wrong task was performed AND it was performed incorrectly
								3 = insequence Error: in sequence task was performed BUT the task was performed incorrectly
								
sequenceError:					1 = sequence Error; 
								0 = otherwise -> NOTE: errorType = 1 and 2
								
nonsequenceError:				1 = nonsequence Error; 
								0 = otherwise -> NOTE: errorType = 3	
								
performedTaskSequence:			stores the performed tasks in sequence (per block)
IntLag:							time (in ms) between interruption onset and first passcode key

showRule:						0 = unravel test trial without a rule call; 
								1 = unravel test trial with at least one rule call
								
InvKey:  						cumulative sum of invalid keystrokes on UNRAVEL test trials (neither trial response nor help)								



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

ACCA1:							proportion correct (response correct AND in sequence) of all UNRAVEL test trials in block 1
ACCA2:							proportion correct (response correct AND in sequence) of all UNRAVEL test trials in block 2
ACCA3:							proportion correct (response correct AND in sequence) of all UNRAVEL test trials in block 3
ACCA4:							proportion correct (response correct AND in sequence) of all UNRAVEL test trials in block 4

Pass   							0=failed accuracy check (default: less than 3 test blocks with UNRAVEL performance >= 0.7), 1=passed accuracy check
BlkAcc  						number of ok (=blocks with UNRAVEL performance >= 0.7) test blocks
totalTrialcount:				the number of all test UNRAVEL trials run
okTrials:						number of ok test trials (ok = trials from blocks with block performance >= 70% correct)

ACC1:							proportion correct (response correct AND in sequence) of ok UNRAVEL test trials in block 1
ACC2:							proportion correct (response correct AND in sequence) of ok UNRAVEL test trials in block 2
ACC3:							proportion correct (response correct AND in sequence) of ok UNRAVEL test trials in block 3
ACC4:							proportion correct (response correct AND in sequence) of ok UNRAVEL test trials in block 4

P1Acc:  						number of ALL post-interruption UNRAVEL trials without sequence errors (regardless of task performance)
									(Note: trials where participant made a correct response (errorType = 0) or a nonsequence Error (errorType = 3))

PracEr:  						number of incorrect (but valid) keystrokes during practice (regardless of type of error)
									Note: does not count using keys other than the response keys
InvKey:  						number of invalid keystrokes on All UNRAVEL test trials (neither trial response nor help)
IntroT:  						time for introduction (tutorial + practice) (in seconds)
TestT:							time for test blocks (in s)
TotalT:							total time for session in s (IntroT + TestT)

SErrA:							proportion of All UNRAVEL test trials with sequence errors
NErrA   						proportion of All UNRAVEL test trials with nonsequence errors
	
SErr:    						proportion of ok UNRAVEL trials with sequence errors (ok = trials from blocks with block performance >= 70% correct)
NErr:    						proportion of ok UNRAVEL trials with nonsequence errors (ok = trials from blocks with block performance >= 70% correct)
PSErr:   						proportion of ok UNRAVEL post-interruption trials with sequence errors (ok = trials from blocks with block performance >= 70% correct)
BSErr:   						proportion of ok UNRAVEL baseline trials with sequence errors (ok = trials from blocks with block performance >= 70% correct)

RTA:							mean correct latency (in ms) of All UNRAVEL test trials
RT:								mean correct latency (in ms) of ok UNRAVEL test trials
PRT:							mean correct latency (in ms) of ok UNRAVEL post-interruption test trials
BRT:							mean correct latency (in ms) of ok UNRAVEL baseline test trials

IntLag:							mean lag time (in ms) between onset of interruption and input of first char
									(Note: if interruption trial repeats due to errors, only the lag from the first interruption trial is measured)
Helps:					   		number of (ok) test trials on which the rule list was displayed at least once
HelpP:							proportion of correct ok test trials on which the rule list was displayed at least once

IntErr:  						mean number of entered passcodes that contained some error (in ok blocks, across code1/code2 trials)
								=> interpreted as: mean number of entered passcodes PER INTERRUPTION that contained some error (in ok blocks)

IntErr_1:  						mean number of entered passcodes that contained some error (in ok blocks, code1 trials only)
								=> interpreted as: mean number of entered passcodes PER INTERRUPTION that contained some error (in ok blocks)

IntErr_2:  						mean number of entered passcodes that contained some error (in ok blocks, code2 trials only)
								=> interpreted as: mean number of entered passcodes PER INTERRUPTION that contained some error (in ok blocks)
																
IntDur:							mean interruption duration (seconds) (in ok blocks)


PER BLOCK PERFORMANCE:

OK1:							1 = block performance >= 70%correct; 0 = otherwise
trials1:						number of test trials block1					
SErr1:							proportion of UNRAVEL trials with sequence errors in block1
NErr1:							proportion of UNRAVEL trials with nonsequence errors in block1:
PSErr1:							proportion of UNRAVEL post-interruption trials with sequence errors in block1
BSErr1:							proportion of UNRAVEL baseline trials with sequence errors in block1
RT1:							mean correct latencies of UNRAVEL test trials in block1
PRT1:							mean correct latencies of UNRAVEL post-interruption test trials in block1
BRT1:							mean correct latencies of UNRAVEL baseline test trials in block1
IntLag1:						mean time (in ms) between interruption onset and first passcode key in block1					
Helps1:							number of UNRAVEL test trials on which the rule list was displayed at least once in block1
HelpP1:							proportion of correct ok UNRAVEL test trials on which the rule list was displayed at least once in block1

mean number of entered passcodes that contained some error
interpreted as: mean number of entered passcodes PER INTERRUPTION that contained some error in block1
IntErr1 (collects errors across code1/code2) /IntErr1_1 (collects errors for code1) /IntErr1_2 (collects errors for code2)
				
IntDur1:						mean interruption duration (seconds) in block1

(same for block2-4)


* separate data files: to change to one data file for all participants (on Inquisit Lab only), go to section
"DATA" and follow further instructions

___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	

1. Demo Tutorial: Participants learn about the meaning of the acronym UNRAVEL while working through each task in sequence.
During the tutorial, participants are told the correct responses to the task at hand (and only those responses advance the tutorial).

2. Practice: 16 practice trials with 2 semi-randomly placed interruptions (by default, interruptions occur randomly after 3, 6, or 7 trials)
In this script, the average number of trials before an interruption = 5.3333 (see list.uninterruptedPracticeTrials under section Editable Lists for more detail)
During practice, errorfeedback in the form of a white flash is provided for incorrect responses and participants have to correct the incorrect response
before advancing.

3. Test: 4 blocks with ~66 test trials per block 
- there is no errorfeedback during the test trials
- each block starts with the U task but participants are never reminded of their place in the UNRAVEL sequence 
(they can, however, view the rules during each trial by pressing the Tab-key)
- Accuracy is based on: 
a) Did the participant stay in sequence (being in sequence is based on the last performed task)? AND
b) was the selected response key correct given the current stimuli (irrespective of sequence standing)?
- at the end of each block: performance feedback and -if appropriate- reminder to a) be faster or b) be more accurate


- 10 randomly placed interruptions per block.
Note: in this script, the sampling process to sample the number of unravel trials before an interruptions is determined as follows:

N = B + floor(-ln(U(0, 1))/R) (see expressions.generateNextInterruption)

N = number of trials before an interruption occurs
B = 3 (see parameters.MinTestRun)
R = .288 is the rate parameter for the exponential distribution, 
U(0, 1) is a random sample from a uniform distribution bounded by 0 and 1.

The average number of trials before an interruption as calculated with this equation is ~6.

- interruption task: 2 code trials - each trial presents a 14 letter code that needs to be entered correctly into a textbox
if the code was entered incorrectly, the trial gets repeated (the code stays the same) before it moves on
See list.lengthInterruptCode and list.interruptCode for more detail and to change the length/nature of the code.
Example code: 'icvafuobermyln'

UNRAVEL trial sequence: 
overview: (START) unravel trials -> interruption 1 -> unravel trials -> interruption 2->..........->unravel trials-> interruption 10 -> unravel trials (END)

in more detail:
unravel prep (prepares the stims) -> unravel test trial (presents the stims and waits for response) ->
{optional if Tab is pressed: -> help: rules are presented until the finger is lifted off the tab key -> return to unravel test trial (presents the stims and waits for response) ->}
-> randomly, on average after every 6 unravel trials: interruption -> {if incorrect code is entered: another interruption trial until the correct code is entered} ->
-> unravel test trial -> etc. until end is reached

___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________	
1. Unravel trials: 
each trial
- randomly (with replacement) samples whether the trial is a U or an I trial
- randomly (with replacement) samples whether the trial is a N or a F trial
- randomly (with replacement) samples whether the trial is a R or a Y trial
- randomly (with replacement) samples whether the trial is a A or a B trial
- randomly (with replacement) samples whether the trial is a V or a C trial
- randomly (with replacement) samples whether the trial is a E or a O trial
- randomly (with replacement) samples whether the trial is a L or a M trial

letter selection: based on the selected value for the N-task AND the selected value for the V-task, a specific letter is selected
(Example: the letter needs to be at the start of the alphabet and needs to be a consonant: B is selected)
digit selection: based on the selected value for the E-task AND the selected value for the L-task, a specific digit is selected
(Example: the digit needs to be odd and greater than 5: 9 is selected)

Letter/Digit Location: the nature of the character inside the box is selected randomly (with replacement):
If the letter is selected to be inside the box, the digit is placed outside the box.
If the character inside the box is randomly (with replacement) selected to be to the left of the box, 
the character outside the box is placed on the right.

Placement of Formatted Character: it is randomly (with replacement) decided whether the formatted character is the inside
or the outside character.

Placement of Colored Character: it is randomly (with replacement) decided whether the colorful character is the inside
or the outside character.

!!!Note: ALL random selections are done independently of each other

2. Interruption Code:
The code to enter is assembled based on a randomly sampled length of characters (default: always 4) and a random 
assortment of characters (default: letters used in UNRAVEL) -> Example code: 'lura'
The length as well as the character selection can be manipulated under section Editable Lists:
list.lengthInterruptCode (stores the lengths) and list.interruptCode (stores the pool of possible characters)

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________
- follow the original UNRAVEL tutorial generously provided by Dr. Eric Altmann
- can be 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:

response key assignments: scancodes and corresponding labels

/key_underlined = "U"
/key_italic = "I"
/key_near = "N"
/key_far = "F"
/key_red = "R"
/key_yellow = "Y"
/key_above = "A"
/key_below = "B"
/key_vowel = "V"
/key_consonant = "C"
/key_even = "E"
/key_odd = "O"
/key_less = "L"
/key_more = "M"

/charSize:							the size of the presented characters in canvas height percentage (default: 12%)

/minProportionCorrect:				sets the minimum proportion correct that a participant has to obtain in a testblocks to pass (default: 0.7)
/minNr_passedBlocks:				the minimum number of passed Testblocks that needs to be obtained to pass Accuracy check (default: 3)

/MinRunlength:						minimum number of trials to run before the next interruption (default: 3; Minimum: 1)
/testtrialRuns:         			1 + number of interruptions in the test block (default:11 => 10 interruptions)

/debugmode:							1 = script runs in debugmode and presents a text stimulus that contains the 
									expected task and correct response key
									
									0 = no debug stim is presented