Return to the UNRAVEL Task page
___________________________________________________________________________________________________________________	

										UNRAVEL
___________________________________________________________________________________________________________________	

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

Script Copyright © 09-21-2020 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 Altman 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. 
values.testBlockCount:				counts the number of UNRAVEL test blocks run

values.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.

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

values.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
								
values.locationColorChar:			1 = colored character is inside character; 
									2 = colored character is outside character
								
values.locationFormattedChar:		1 = formatted (underlined/italicized) character is inside character; 
									2 = formatted (underlined/italicized) character is outside character

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


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

Interruption-related Variables:

values.code:							the code of the current Interruption Trial
values.interruption:					1 = an interruption should be run after this unravel trial; 0 = no interruption will be run
values.counter_uninterruptedTrials: 	counts the number of consecutive trials run without an interruption
values.uninterruptedTrials:				stores the current number of trials that should be run in between interruptions
values.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)
values.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)

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

values.showRule:				0 = unravel test trial without a rule call; 
								1 = unravel test trial with at least one rule call
								
values.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)*

computer.platform:				the platform the script was run on (win/mac/ios/android)
script.startdate:				date script was run
script.starttime:				time script was started
script.subjectid:				assigned subject id number
script.groupid:					assigned group id number
script.sessionid:				assigned session id number
script.elapsedtime:				time it took to run script (in ms); measured from onset to offset of script
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 (values.errorType = 0) or a nonsequence Error (values.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. The average number of trials before an interruption = 6
Note: in this script, the sampling process to sample the number of unravel trials before an interruptions samples from 11 possible values without replacement
(see list.uninterruptedTrials under section Editable Lists for more detail)

- 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 Altman
- 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)


/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