Return to the Tower Test page
___________________________________________________________________________________________________________________	

								Tower of London Task (TOL) - D-KEFS Version
___________________________________________________________________________________________________________________	

last updated:  01-14-2020 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC
Script Copyright © 01-14-2020 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	
This script implements a computerized version of the Delis-Kaplan Executive Function System (D-KEFS)
Tower of London Test. The Tower of London Test is a test of excutive functioning with a 
focus on planning abilities.
		
___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	
Participants are asked to arrange up to five discs of varying sizes on three different pegs
in a specific solution pattern in as few moves as possible and observing two movement rules:
"Only move the top disc" and "bigger discs may not be placed on top of smaller discs".
This test is timed.

___________________________________________________________________________________________________________________	
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: 'towertest_d_kefs_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
script.sessionid:					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.problemnumber				Current problem number (1-9)								
values.N_Discs:					stores the number of discs present in the current problem									
values.maxDuration:				stores the allotted maximum duration (in ms) for the current problem

expressions.targetachieved			Returns 1 as soon as the subject has successfully reached a given problem's target / goal state. Otherwise 0.
values.targetmoves				Number of prescribed (minimal) moves to solve the current problem.

values.subjectmoves				Number of subject-performed moves for the current problem.
									Note: each rule violation counts as one extra move in this script 
									(the correction of the violation is not counted as a move)
									
expressions.excessmoves			Returns the difference between number of moves performed by the subject ('subjectmoves')
									and the number of target moves for a given problem.

values.achievementScore			Score awarded for solving the current problem. 
									Problem1-2: 0 (no solution), 1 (non-optimal solution), 2 (optimal solution)
									problem3-4: 0 (no solution), 1 (>= ideal movements + 2), 2 (= ideal movements + 1), 3 (optimal solution)
									problem5-7: 0 (no solution), 1 (>= ideal movements + 3), 2 (= ideal movements + 2), 3 (= ideal movements + 1), 4 (=optimal solution)
									problem 8: 0 (no solution), 1 (>= ideal movements + 5), 2 (= ideal movements + 3/4), 3 (= ideal movements + 1/2), 4 (=optimal solution)
									problem 9: 0 (no solution), 1 (>= ideal movements + 7), 2 (= ideal movements + 4/5/6), 3 (= ideal movements + 1/2/3), 4 (=optimal solution)
									
values.totalscore					Score achieved across the whole set of test problems. Computed
									as the sum of individual problem scores. Maximum is 30 in the 
									standard version.
										
values.consecutiveErrorRuns:		stores the number of consecutive error runs (resets for each correctly solved problem)	

values.stopTask					Pseudo-boolean switch to stop the task prematurely when stop condition has been met
									(= 3 unsuccessful solution attempts for three consecutive problems - except 1)
									
values.violation:					0 = no rule was violated with the currently recorded move
									1 = rule 1 was violated ('no larger disc onto smaller disc')
									2 = rule 2 was violated ('only top disc can be moved')
									(if rule 1 AND rule 2 are violated in the same move, only rule violation 2 is noted.
									The violations count as a single violation in this script)
									
values.countViolations_problem:		counts the number of rule violations per problem


expressions.firstmovetime				Returns the time (in ms) elapsed between initial presentation of 
										the target configuration and the initialization of the subject's first valid
										move. Sometimes also referred to as "planning time" or simply
										"latency". Note: Measure is computed separately for each problem.
										
expressions.solutiontime				Returns the time (in ms) elapsed between initial presentation of
										the target configuration and a subject's successful solution or problem termination.
										Note: Measure is computed separately for each problem.										
										
expressions.executiontime				Computed as solutiontime - firstmovetime. Note: Measure is 
										computed separately for each problem.
										
										
values.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).
									
values.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).
									
values.TotalCompletionTime:			cumulative solution times across all problem sets attempted										

latency:								the latency of the current response in ms (or if no response: trialduration)									
response:								response made (the peg that was moved to)

trial.choice.lastdropsource:				the last moved disc (1, 2, 3, 4, or 5)
trial.choice.lastdroptarget:    			the last peg that a disc was moved to (apeg, bpeg, cpeg)

values.movestring						Text string containing a record of performed moves. E.g. "1apeg,"
										indicates that disc1 (the smallest) was moved to pegA (the left one).
										A rule violation is expressed as "rule1violation (2bpeg)" => disc2 was moved onto a smaller disc onto b-peg 
									
expressions.top_in_a					Returns the disc number (1, 2, 3, 4, or 5) currently inhabiting the top position 
										on peg 1 (left). Returns 'none' if peg is empty. Used to determine
										valid responses in 'trial.choice'.
									
expressions.top_in_b					Returns the disc number (1, 2, 3, 4, or 5) currently inhabiting the top position 
										on peg 2 (center). Returns 'none' if peg is empty. Used to determine
										valid responses in 'trial.choice'.
									
expressions.top_in_c 					Returns the disc number (1, 2, 3, 4, or 5) currently inhabiting the top position 
										on peg 3 (right). Returns 'none' if peg is empty. Used to determine
										valid responses in 'trial.choice'.									
									
values.a_count						The number of discs currently placed on peg 1 (left).
values.b_count						The number of discs currently placed on peg 2 (center).
values.c_count						The number of discs currently placed on peg 3 (right).									

values.cumMoves:					cumulative number of moves made across all problem sets attempted
values.cumMoves_cS:					cumulative number of moves made across all problem sets that were solved
values.cumOptimalMoves:				cumulative number of optimal moves across those problem sets that were attempted
values.cumOptimalMoves_cS:			cumulative number of optimal moves across those problem sets that were solved

							
(2) Summary data file: 'towertest_d_kefs_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)
									
values.totalscore					Score achieved across the whole set of test problems. Computed
									as the sum of individual problem scores. Maximum is 30 in the 
									standard version.									
									
values.problemnumber				Last problem number (1-9) that was attempted
									
expressions.meanFirstMoveTime:	mean first move time (in ms); based on all recorded first move-times

expressions.timePerMoveRatio:		mean amount of time (in ms) spent on each move
									(ratio of values.totalCompletionTime over the number of moves made)
									
expressions.moveAccRatio:		number of moves made in relationship to the number of optimal moves
									1 = participant made only the number of optimal moves (but may NOT have solved the problems)
									
expressions.moveAccRatio_cS:		number of moves made in relationship to the number of optimal moves
									(only calculated for solved problems)
									1 = participant made only the optimal moves for the problems solved
																																	
values.countViolations_total:		counts the number of rule violations across problems									

_________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	

* 9 problems total with various number of discs
disc1 = smallest to disc5 = largest disc

* each problem is timed (script automatically quits the trial after the allotted time is used up)
-> to edit timings go to section Editable Lists (list.maxDurations)
* script quits after 3 unsuccessful (= target state was not achieved within the time limit) 
consecutive problems (first one excluded from count)
* one attempt per problem

Problem 1 & 2 (but not problem 3-9)
Feedback Prompts:
if the optimal solution wasn't presented, the computer plays an 'optimal solution video'

Rule Reminders provided:
*for the first violation of each rule: a reminder of the rule is provided, and the previous set-up restored
*for subsequent violations: only a 'Violation' reminder is provided and the previous set-up restored
	
___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________	
*see section Editable Stimuli, different base/peg/disc images can be used (iin that case positions of 
base/pegs/discs may have to be adjusted)
*the current and goal states of each disc can be edited under section Editable Lists)

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
Instructions are provided by Millisecond Software. They are adapted from the D-KEFS Tower Test to the computer.
Instructions use problem set 1 as an example (similarly to the original D-KEFS tower 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:

	showTimer:						true = presents the timer to participants while solving the problem (default)
									false = does not present the timer
									
	showMovementInfo:				true = presents the optimal number of movements and tracks the participant's movement on screen (default)
									false = no movement info is presented to participant (default)
									
	showScores:						true = score information is presented to participant
									false = no score information is presented to participant (default)
									
	showRuleReminder:				true = rules are displayed on screen throughout the task (default)
									false = rules are not displayed on screen
									

	n_a_slots						Capacity of peg 1 (left). Default is 5.
	n_b_slots						Capacity of peg 2 (center). Default is 5.
	n_c_slots						Capacity of peg 3 (right). Default is 5.

	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 discs in screen 
									percentages. Defaults are 80%, 65%, 50%.