User Manual for Inquisit's Dot Memory Task


___________________________________________________________________________________________________________________	

								Dot Memory Task
___________________________________________________________________________________________________________________	


Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 05-11-2022
last updated:  05-16-2022 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 05-16-2022 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________
This script implements Millisecond Software's version of the Dot Memory Task (Sliwinski et al, 2018),
a brief visual spatial memory test used to assess working memory.

The task is intended for touchscreens such as ipads but can also be run with the mouse on non-touchscreens.

Reference:											
Sliwinski MJ, Mogle JA, Hyun J, Munoz E, Smyth JM, Lipton RB. (2018).
Reliability and Validity of Ambulatory Cognitive Assessments. 
Assessment. 2018 Jan;25(1):14-30. 
doi: 10.1177/1073191116643164.

Siedlecki KL. Investigating the structure and age invariance of episodic memory across the adult lifespan. 
Psychology and Aging. 2007; 22(2):251–268. http://doi.org/10.1037/0882-7974.22.2.251

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________

The Dot Memory Task consists of 3 phases:

Encoding Phase: presents a 5x5 matrix with 3 dots for 3s
Distractor Phase: find all the 'F's (8s)
Retrieval Phase: select the matrix positions of the 3 dots

The default script runs 2 trials (see Sliwinski et al, 2018).
___________________________________________________________________________________________________________________	
DURATION 
___________________________________________________________________________________________________________________	
the default set-up of the script takes appr. 2 minutes to complete

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

(1) Raw data file: 'dotmemorytask_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:					with the current subject id
group: 						with the current group id
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. 

response:					the response of participant
							Note: by default, the dot placement procedure does not generate its own line of data.
							The final placements are stored by trial.dotRecall_end.
							Similarly the distractor task procedure only records one line of data at the end of 
							the distractor task during trial.distractor_end
														
correct:					correctness of response (1 = correct, 0 = error)
							trial.dotRecall_end: 1 = all three dots were correctly placed; 0 = otherwise
							trial.distractor_end: 1 = all 'F' were correctly placed; 0 = otherwise

latency:					response latency (in ms)


//////////////////////////////
Dot Recall Task: 5 x 5 matrix

numbering from left to right,
top to bottom
1....
....25
//////////////////////////////

dot1:						stores the box location (1-25) for the first target dot
dot2:						stores the box location (1-25) for the second target dot
dot3:						stores the box location (1-25) for the third target dot
							Note: 
							1-5 = top row from left to right
							...
							21-15 = bottom row from left to right
						
dotRecall_RT:				the time (in ms) it took to make dot placements during the recall trial (measured from onset of matrix until done button is pressed)
dotRecall_ACC:				1 = all three dots were correctly placed; 0 = otherwise
countCorrectDots:			the number of correctly placed dots

targetDotPositions:			a string variable that contains the positions of the target dots
placedDotPositions:			a string variable that contains the positions of the placed recall dots
lastDot1:					stores the box number of the currently placed dot1
lastDot2:					stores the box number of the currently placed dot2 
lastDot3:					stores the box number of the currently placed dot3

//Euklidean Recall Error Score:	The script matches each placed dot with a target dot using pixel Euklidean distance measures.
//The distances btw. matched dots are summed up to present the recall Error Score.
//Higher scores indicating less accurate placement and poorer performance
//Note: for perfectly placed dots, the score = 0.

recallErrorScore_px:		The sum of all three placed dot-target dot distances in pixels (monitor dependent)
recallErrorScore:			The recallErrorScore_px set relative to the pixel distance between the center of two
							adjacent boxes in the 5x5 matrix (see expressions.adjacentBoxDistance_px) (monitor independent)
							Example: recallErrorScore_px = 489px (monitor dependent)
							adjacentBoxDistance_px = 346px (monitor dependent)
							recallErrorScore = 489px/346px = 1.41 => monitor independent => the dot was placed 1.41 boxes away from the target dot
														

//the individual distances calculated by the script (in pixels) as well as the three minimum distance measures used
//to calculate the final recallErrorScore:

dist_11,dist_12,dist_13:  	distances (in px) from target dot1 to placed dot1, placed dot2, placed dot3
dist_21,dist_22,dist_23:  	distances (in px) from target dot2 to placed dot1, placed dot2, placed dot3
dist_31,dist_32,dist_33:  	distances (in px) from target dot3 to placed dot1, placed dot2, placed dot3

min1:						the first minimum distance (matches the first target dot with a placed dot -> these dots are then removed from the selection for the next minimum distance)
min2:						the second minimum distance (matches the first target dot with a placed dot -> these dots are then removed from the selection for the next minimum distance)
min3:						the third minimum distance (at this point, only one distance is left)

adjacentBoxDistance_px:		for debug purposes and manual calculations: stores the horizontal/vertical distance in pixels of 
							the center of two adjacent boxes on the current monitor 
							=> used to calculate the relative Euklidean differences btw. target dots and placed dots


//////////////////////////////
Distractor Task: 5 x 8 matrix

numbering from left to right,
top to bottom
1....
....40
//////////////////////////////							
							
targetDistractorPositions:	distractor task variable: stores the box positions (1-40) of all presented 'F'
selectedDistractors:		distractor task variable: stores the box positions (1-40) of all selected 'F'
countSelectedDistractors:	count the number of selected distractors
countCorrectDistractors:	count the number of correctly selected 'F'

adjust_propCorrect_Distractors: adjusted proportion of correctly selected 'F'
								= [(number of correctly selected 'F's) - (number of selected 'E's)]/number of hidden Fs
								=> correct proportions are adjusted by subtracting the number of incorrect
								selections from the correct one before setting the difference relative to the number of hidden 'F'

(2) Summary data file: 'dotmemorytask_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)
							
						
//Recall Task//
adjacentBoxDistance_px:		for debug purposes and manual calculations: stores the horizontal/vertical distance in pixels of 
							the center of two adjacent boxes on the current monitor 
							=> used to calculate the relative Euklidean differences btw. target dots and placed dots


meanRecallErrorScore_px:	mean Euklidean Distance Recall Error Score (in pixels - monitor dependent)
meanRecallErrorScore:		mean Euklidean Distance Recall Error Score in px set relative to to the pixel distance between the center of two
							adjacent boxes in the 5x5 matrix (see expressions.adjacentBoxDistance_px) (monitor independent)
							=> main DV
							=> Higher scores indicating less accurate placement and poorer performance

meanRecallRT:				mean recall response time (in ms); measured from onset of matrix until Done button was pressed

//Distractor Task//
meanProp_adjustCorrectDistractors:	the mean of the adjusted proportions of selecting 'F's
									(Note: the individual correct proportions are adjusted by subtracting the number of incorrect
									selections from the correct one before setting the difference relative to the number of hidden 'F')
							
___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	

(1) Instructions with Demo Trial: The computer provides an automated demo through the three
stages of the task. The intro can be repeated as often as needed.

(2) Test: runs 2 trial sequences (editable parameter) 
with fixed dot positions (by default - see parameters.runFixedDotPositions for more info)

*Encoding Phase* 
Script presents a 5x5 matrix with 3 dots for 3000ms (editable parameter).

*Distractor Phase* 
The Distractor Phase starts immediately after the the Encoding Phase.
Script presents a 5x8 matrix filled with 'E's and 'F' (number of Fs can be controlled
via editable parameters) and participants are asked to select all 'F's.
Selected letters get highlighted. Letters can be unselected by pressing a highlighted letter
(=> corrections possible). The distractor task lasts for 8s. 

*Retrieval Phase/Recall*
The Retrieval Phase starts immediately after the Distractor Phase.
Script provides an empty 5x5 matrix and asks participants to select the matrix positions of the 3 dots
Any time participants touches an empty box, a dot is placed. Once 3 dots are placed, no further dots
are added. Dots can be erased by touching a previously placed dot (=> corrections possible). 
The recall trial ends when participants select 'done'.
Done button is activated right from the start (participants place 0 to 3 dots).
The screen goes blank for 1000ms (iti, editable parameter) before the next trial is started.


////Dependent Variable Calculation////
The main Dependent variable is the 'RecallError Score' that is based on distance measures from 
placed dots to the target dots.

The Inquisit script uses the following algorithm to calculate the distances (see expressions.recallErrorScore_px
for actual code):

(1) the script collects all 9 possible distances
=> Euklidean Distances from Target1, 2, 3 to placed dot 1, 2, 3 are calculated (in pixels); 
Note: the maximum possible error distance is substituted for missing dots.

(2) the smallest of these distances is interpreted as the first target dot-placed dot pair (values.min1)
=> distances from this target dot/this placed dot are not further taken into consideration

(3) the next smallest of these distances is interpreted as the second target dot-placed dot pair (values.min2)
=> distances from this target dot/this placed dot are not further taken into consideration

(4) the remaining distance is interpreted as the last match between the last target dot-placed dot pair (values.min3)

(5) The minimum distances (in pixels) are summed up and set relative to the pixel distance btw. 2 adjacent matrix boxes
=> monitor-independent score with the unit 'box height'

___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________

provided by Millisecond Software - can be edited under section 'Editable Stimuli'
___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________

provided by Millisecond Software - 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: