User Manual: Inquisit Tower of London Task


___________________________________________________________________________________________________________________	

				Tower of London Task (TOL) -- Krikorian et al. (1994) Version
				(German translation)
___________________________________________________________________________________________________________________	

Script Author: David Nitz (dave@millisecond.com) for Millisecond Software, LLC
last updated:  03-02-2022 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 03-02-2022 Millisecond Software

German translation provided by K. Borchert for Millisecond Software
___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________
	This script implements the 'Tower of London' task, an assessment of executive functioning 
	with a focus on planning abilities.	
	
	References:
	
	Shallice, T. (1982). Specifc impairments of planning. Philosophical Transactions of the Royal 
	Society of London, Biology, 298, 199-209.

	Procedural details were adapted from:
	Krikorian, R., Bartok, J., & Gay, N. (1994). Tower of London procedure: A standard method 
	and developmental data. Journal of Clinical and Experimental Neuropsychology, 16, 840-850.
	
	Task instructions were adapted from:
	Anderson, P., Anderson, V., & Lajoie, G. (1996). The Tower of London test: Validation and 
	standardization for pediatric populations. The Clinical Neuropsychologist, 10, 54-65.

	Further references:	
	Berg, W. K. & Byrd, D. L. (2002). The Tower of London spatial problem-solving task:
	Enhancing clinical and research implementation. Journal of Clinical and Experimental 
	Neuropsychology, 24(5), 586-604.
 
___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	
Participants are asked to arrange three colorful discs on 3 provided pegs 
in a specific solution pattern in as few moves as possible.

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

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

(1) Raw data file: 'toweroflondon_german_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.k.
																			
response:						response made (contains the last peg a disc was moved to or 0 for noresponse)
latency:						the latency of the response in ms (or if no response: trialduration)

trial.choice.lastdroplatency:	time (in ms) between intialization of the last move and its completion; move execution time
trial.choice.lastdropsource:	the last moved disc (R, B, G)
trial.choice.lastdroptarget:	the last peg that a disc was moved to (apeg, bpeg, cpeg)


problemnumber					Current problem number. By default the task consists of 1 practice
								problem and 12 test problems presented sequentially. 0 indicates 
								a practice problem.
										
subjectattempts					Number of current attempts to solve the given problem.
targetmoves						Number of prescribed moves for the current problem.
subjectmoves					Number of subject-performed moves for the current problem.

excessmoves						Returns the difference between number of moves performed by the subject and the 
								number of target moves for a given problem.
									
movestring						Text string containing a record of performed moves. E.g. "B2R3"
								indicates that the blue ball (B) was moved to peg 2 (center) and 
								the red ball (R) was moved to peg 3 (right).
									
targetachieved					Returns true as soon as the subject has successfully reached a given
								problem's target / goal state. Otherwise false.
										
problemscore					Score awarded for solving the current problem. See Krikorian et
								al. (1994) for details.
										
totalscore						Score achieved across the whole set of test problems. Computed
								as the sum of individual problem scores. Maximum is 36 in the 
								standard version.
									
firstmovetime					Returns the time (in ms) elapsed between initial presentation of 
								the target configuration and the initialization of the subject's first
								move. Sometimes also referred to as "planning time" or simply
								"latency". Note: Measure is computed separately for each attempt.
										
executiontime					Computed as solutiontime - firstmovetime. Note: Measure is 
								computed separately for each attempt.
										
solutiontime					Returns the time (in ms) elapsed between initial presentation of
								the target configuration and a subject's successful solution.
										Note: Measure is computed separately for each attempt.
										
t_choicestart					Absolute start time for trial.choice in ms. May be used to derive
								additional measures during data analysis (e.g. mean move time).
									
t_choiceend						Absolute end time for trial.choice in ms. May be used to derive
								additional measures during data analysis (e.g. mean move time).
								
t_firstmove						Absolute script timestamp in ms for valid first move 								

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

totalscore:						Score achieved across the whole set of test problems. 
								Computed as the sum of individual problem scores. Maximum is 36 in the standard version.
									
Note: the following variables are calculated independent of accuracy of solution:									
mean_solutionTime:				the mean solution time (in ms) of all solutions with solutiontime > 0
SD_solutionTime:				the standard deviation (in ms) of solution times of solutions with solutiontime > 0			
mean_executionTime:				the mean execution time (in ms) of all solutions with solutiontime > 0
SD_executionTime:				the standard deviation (in ms) of all execution times of all completed solutions with solutiontime > 0	

Note: the following variables are calculated for solutions with problemscore > 0:
mean_solutionTime_correctSolutions:		the mean solution time (in ms) of all solutions with problemscore > 0
SD_solutionTime_correctSolutions:		the standard deviation (in ms) of solution times of solutions problemscore > 0		
mean_executionTime_correctSolutions:	the mean execution time (in ms) of all solutions with problemscore > 0
SD_executionTime_correctSolutions:		the standard deviation (in ms) of all execution times of all completed solutions with problemscore > 0

___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	
1 Practice trial (problem with 2 moves)
12 Test trials (2 problems with 2 moves, 2 problems with 3 moves, 4 problems with 4 moves, 4 problems with 5 moves: 
tested sequentially in fixed order)

Per Problem:
* no time limit
* reset button provided
* 3 attempts per problem to solve it given the max. number of moves. After failure to solve a problem in 3 attempts,
participants are moved to the next problem in the sequence (participants can also move ahead to the next problem
by clicking a 'next' button)
	
___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________	
see section Editable Stimuli
(to re-create new target states, try EmptyPegs.pptx - provided by Millisecond Software)

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
see section Editable Instructions. Instructions are provided in the form of *.html pages. Edits can be made
to the html-files directly.

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

	maxattempts						Allowed number of attempts to solve any given problem with
									minimum amount of moves. Default is 3.
	npracticeproblems				Number of practice problems. By default, the task contains 1
									practice problem and 12 test problems. Default is 1. 
	n_a_slots						Capacity of peg 1 (left). Default is 3.
	n_b_slots						Capacity of peg 2 (center). Default is 2.
	n_c_slots						Capacity of peg 3 (right). Default is 1.
	intertrialinterval				The intertrial interval (time between problems) in ms. Default is 1000.
	feedbackduration				Duration of performance feedback in ms. Default is 2000.
	h1 -> h3						Horizontal coordinates of pegs 1, 2 and 3 in screen percentages.
									Defaults are 20%, 50% and 80%.
	v1 -> v3						Available vertical coordinates for the three balls in screen 
									percentages. Defaults are 80%, 65%, 50%.
	r_startX, r_startY				Determines the red ball's start position (horizontal, vertical).
	g_startX, g_startY				Determines the green ball's start position (horizontal, vertical).
	b_startX, b_startY				Determines the blue ball's start position (horizontal, vertical).