User Manual: Inquisit Mirror Tracing Test


___________________________________________________________________________________________________________________	

								*Mirror Tracing Task*
___________________________________________________________________________________________________________________	

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

Script Copyright © 11-01-2024 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________
This script implements Millisecond Software's version of a computerized Mirror Tracing Task (e.g. Starch, 1910), 
a measure of hand eye coordination and novel motor learning. In general, mirror tracing tasks
ask participants to trace various shapes while only being able to see its mirror image.

Researchers can select to run the task with an absolute screen size to ensure that distances
stay the same across devices. The default sizing settings are optimized for ipad touchscreens.
See section Editable Parameters for more info.

The setup of this script was inspired by the Mirror Tracing Task described by the Pittsburgh Stress Battery.
It uses a square and a circle to trace.

References:
//Pittsburgh Stress Battery:
https://measures.scienceofbehaviorchange.org/measuredetails/4deff805-0b33-4b0d-b1b8-5611ea8534e5
Author: Eric Loucks

//General References for Mirror Tracing:
Starch, D. (1910). A demonstration of the trial and error method of learning. 
Psychological Bulletin, 7, 20-23. 

Borresen, C. R. (1973). Reward, Punishment and Reversal on a Mirror-Tracing Task. 
Perceptual and Motor Skills, 37(1), 199–202. 
https://doi.org/10.2466/pms.1973.37.1.199

Julius, M. S., & Adi-Japha, E. (2016). A Developmental Perspective in Learning the Mirror-Drawing Task. 
Frontiers in Human Neuroscience, 10, 83–83. 
https://doi.org/10.3389/fnhum.2016.00083								

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________

The screen is divided into a mirror part (on top) and a drawing canvas (on the bottom).
Participants will be asked to trace a shape (square and/or circle) on the drawing canvas (bottom) but can only 
see their tracing trail on the mirror image of the shape (on the top). 
By default, each tracing trial lasts at most 45s (editable parameter) before it is timed out.
___________________________________________________________________________________________________________________	
DURATION 
___________________________________________________________________________________________________________________	
the default set-up of this script takes appr. 7-8 minutes to complete

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

(1) Raw data file: 'tracingtask_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

/*Parameter Settings*/																				
TracingMechanism:					"finger" vs. "mouse" vs. "stylus"
TracingHand:						"dominant" vs. "nondominant" vs. "left" vs. "right"
runTracingCircle, 					true (1) or false (0)
runTracingSquare:					true (1) or false (0)


//Play Setup: parameter
runAbsoluteSizes:					true (1) = should run absolutely sized canvas (see canvasHeight_inmm)
									false (0) = should use proportionally sized canvas (uses width = 4/3*screenHeight)
								
canvasAdjustments:					N/A: not applicable => runAbsoluteSize was set to 'false'
									0: runAbsoluteSize was set to 'true' and screen size was large enough
									1: runAbsoluteSize was set to 'true' BUT screen size was too small and 
									adjustments had to be made
									
//UI data:									

display.canvasHeight:				the height of the active canvas ('playarea') on the current monitor in pixels
display.canvasWidth:				the width of the active canvas ('playarea') on the current monitor in pixels

px_per_mm:							the conversion factor to convert pixel data into mm-results for the current monitor
									(Note: the higher resolution of the current monitor 
									the more pixels cover the same absolute screen distance)	
									This factor is needed if you want to convert pixel data into absolute mm data									

playareaHeight_inmm:				the width of the play area in mm 
playareaWidth_inmm:					the height of the play area in mm 										
																				
TracingCircleDiameter_inmm:			the diameter of the tracing circle in mm
TracingSquareHeight_inmm:			the diameter of the tracing square in mm
trackWidth_inmm:					the width of the tracks around the stimulus in mm (the area that is considered 'on track')

//raw data: trial by trial
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.
										
									
blockCounter:						counts the number of blocks run per condition									
tracingStimCondition:				1 = circle; 2 = square 
trialCounter:						trial counter per block

success:							in trial.tracingCircle_tracing_end/trial.tracingSquare_tracing_end
									1 = participant reached goal area
									0 = trial was timed out (or ended prematurely)
									
countSuccess:						counts the number of successfule trials per block

ontrack:							1 = the current mouse coordinates are on the track around the circle/square (includes the target zone)
									0 = outside the track
									
error_inpx:							for coordinates 'ontrack' -> 0
									if not on track: the number of pixels that finger/mouse is currently away from track
									negative values: the finger/mouse went inside the tracing stimulus ('inside error')
									positive values: the finger/mouse went outside the tracing stimulus ('outside error')
									
									CIRCLE condition:
									'inside error': the (negative) pixel difference btw. inner track radius (in px) and distance from mouse coordinates to circle center
									'outside error': the (positive) pixel difference btw. outer track radius (in px) and distance from mouse coordinates to circle center
									=> see expressions.TracingCircle_error_inpx

									Square condition:
									'inside error': script returns the minimum of 4 possible distances to the inner track (Note: 'benefit of a doubt' coding)
									1. vertical distance to top inner track
									2. vertical distance to bottom inner track
									3. horizontal distance to left inner track
									4. horizontal distance to right inner track
									'outside error': script determines in which of 8 possible locations (relative to the tracing square) the coordinates fall into
									1. directly above: returns the difference in y coordinates of the outer track and the mouse coordinates
									2. directly below: returns the difference in y coordinates of the outer track and the mouse coordinates
									3. directly left: returns the difference in x coordinates of the outer track and the mouse coordinates
									4. directly left: returns the difference in x coordinates of the outer track and the mouse coordinates
									the remaining locations return the distance of the mouse coordinates to the nearest corner of the outer track
									=> see expressions.TracingSquare_error_inpx
									
error_x_inpx:						the horizontal x mouse/finger coordinate at time of error									
error_y_inpx:						the vertical y mouse/finger coordinate at time of error

meanTrialError_inpx:				the mean of all 'error_inpx' values across the trial (measure only is based on absolute values => of interest is the absolute distance) in the current trial
									calculated at the end of each trial

onTargetZone:						1 = mouse/finger coordinates are currently on the Target Zone; 0 = otherwise 
leftTargetZone:						1 = mouse/finger coordinates have moved on from initial touchdown on Target Zone; 0 = otherwise
reachedTargetZone:					1 = mouse/finger coordinates have reached Target Zone again after once leaving it; 0 = otherwise 


//ontrack proportion
propOnTrack:						proportion onTrack responses for the current trial
									Note: looks at the proportion of onTrackMovements relative to all Movements
									(excludes movements on target zone)			

//built-in DVs:
response, correct, latency, 
									
//Latency:
tracingRT:							the cumulative tracing Response Time

//Coordinate Measures
mouse.x:							the x coordinate of the finger at the time of the currently measured response (in pixel)
mouse.y:							the y coordinate of the finger at the time of the currently measured response (in pixel)
mirror_x:							the mirrored x-coordinate (in pixel)
mirror_y:							the mirrored y-coordinate (in pixel)

TargetZone_center_x_inpx:			the horizontal x-pixel position of the target/start circle
TargetZone_center_y_inpx:			the vertical y-pixel position of the target/start circle
TargetZoneDiameter_inpx:			the pixel diameter of the target/start circle


//Inquisit built-in variables
response:							the response of participant
									Example:
									'mousemove' => mouse coordinate change was noted
									or the name of the stimulus that was touched

correct:							correctness of response

latency:							measured from: onset trial until recorded response
									

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

/*Parameter Settings*/										
TracingMechanism:					"finger" vs. "stylus" vs. "mouse"
TracingHand:						"dominant" vs. "nondominant" vs. "left" vs. "right"
runTracingCircle, 					true (1) or false (0)
runTracingSquare:					true (1) or false (0)

//Play Setup:
/runAbsoluteSizes:					true (1) = should run absolutely sized canvas (see canvasHeight_inmm)
									false (0) = should use proportionally sized canvas (uses width = 4/3*screenHeight)
								
/canvasAdjustments:					N/A: not applicable => runAbsoluteSize was set to 'false'
									0: runAbsoluteSize was set to 'true' and screen size was large enough
									1: runAbsoluteSize was set to 'true' BUT screen size was too small and 
									adjustments had to be made

display.canvasHeight:				the height of the active canvas ('playarea') on the current monitor in pixels
display.canvasWidth:				the width of the active canvas ('playarea') on the current monitor in pixels

px_per_mm:							the conversion factor to convert pixel data into mm-results for the current monitor
									(Note: the higher resolution of the current monitor 
									the more pixels cover the same absolute screen distance)
									This factor is needed if you want to convert pixel data into absolute mm data
									to compare error distances across screens

/playareaHeight_inmm:				the width of the play area in mm 
/playareaWidth_inmm:				the height of the play area in mm 

TracingCircleDiameter_inmm:			the diameter of the tracing circle in mm
TracingSquareHeight_inmm:			the diameter of the tracing square in mm
trackWidth_inmm:					the width of the tracks around the stimulus in mm (the area that is considered 'on track')
										

trialCounter_circle:				the number of trials run in the circle conditions
countSuccess_circle: 				the number of successful trials run in the circle condition
									success = participant reached the goal area (was not timed out)
									
trialCounter_square:				the number of trials run in the square conditions
countSuccess_square: 				the number of successful trials run in the square condition
									success = participant reached the goal area (was not timed out)

//the remaining data is only calculated for 'successful' trials:
									
//Latency Data//
meanRT: 					mean tracing RT (in ms) across stim conditions
meanRT_circle: 				mean tracing RT (in ms) for circle condition trial	
meanRT_square: 				mean RT (in ms) for square condition trials

//Pixel Error Data
mean_pixelError:			mean pixel errors across stim conditions
mean_pixelError_circle:		mean pixel errors in circle condition 
mean_pixelError_square:		mean pixel errors in square condition
(see 'error_inpx' - under raw data- for explanation of how pixel errors were computed in this script)
												
___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	
By default, this script runs 2 tracing stimuli (circle, square) in a blocked design with 5 trials each.
Each trial lasts at most 45s (Editable Parameter) before it is timed out. 
After the first block, participants get the chance to take a break (self-paced).
By default, participants receive optional performance feedback at script conclusion.

Check section 'Editable Parameters' for parameters that control
- tracing stimuli (circle/square) conditions to run
- trial numbers
- trial timeouts
- performance feedback settings
etc.
___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________

provided by Millisecond Software - can be edited under section 'Editable Instructions'.
___________________________________________________________________________________________________________________	
EDITABLE CODE 
___________________________________________________________________________________________________________________	
check below for (relatively) easily editable parameters, stimuli, intro1 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:

<parameters>
/TracingMechanism ="mouse"				//"finger" vs. "mouse" vs. "stylus"
										//Note: if set to 'finger' or 'stylus' => trials will repeat if 
										//fingers or stylus is lifted prematurely off the screen during
										//the tracing trials
										
/TracingHand = "dominant"				//choose from: "dominant", "non-dominant", "left", "right"

/skipPerformanceFeedback = false		//true: participants won't receive any performance feedback at the end
										//false: participants will receive performance feedback at the end
										
										
/trialTimeout_inms = 45000				//the maximum time (in ms) that each tracing trial lasts 																							
																		
//design parameters: 2 tracing stims

/runTracingSquare = true
/runTracingCircle = true	

/trialsPerTracingStim = 5				//number of trials per Tracing Stim block
										//By default, participants run 5 trials per square/circle stim

//Screen Sizes		
/runAbsoluteSizes = false				//true = runs absolutely sized canvas (see parameters.canvasHeight_inmm)
										//false = uses proportionally sized canvas (uses width = 4/3*screenHeight)
										
//the setting of the active canvas in absolute mm is only relevant if parameters.runAbsoluteSizes = true (1)
//=> IF the screen is not sufficiently big to allow for the absolute canvassize
//the script will run a default width:height=4:3 and make a note in the data files
//the default absolute sizes provided here are optimized for ipad use																																						
/canvasHeight_inmm = 145				//the height of the active canvas in mm (default: 145mm ~ ipad screen height)																					
/canvasWidth_inmm = 195					//the width of the active canvas in mm (default: 195mm ~ ipad screen width)									

//sizing Parameters in RELATIVE measurements
//the remaining items are sized relative to CANVAS HEIGHT
//=> Result: 
//for absolute canvassizes: you achieve the same absolutely sized stimuli on all screens
//for relative canvassizes: stimuli are proportionally sized on all screens

/TracingCircleDiameter_inpct = 35%		//the diameter of the circle in canvas height percentage (default: 35%)
										//for the default settings, the diameter is: ~5.1cm

/TracingSquareHeight_inpct = 35%		//the height of the TracingSquare in canvas height percentage (default: 35%)
										//for the default settings, the height is: ~5.1cm
										
										
/trackWidth_inpct = 1%					//the width of the tracing track in canvas height percentage (default: 1%)							
										//for the default settings, the width is: ~0.15cm									

/tracingLineWidth_inpct = 1%			//the width of the tracing line (drawn by participant) in canvas height percentage (default: 1%)
										//for the default settings, the diameter is: ~0.15cm

/TargetZoneDiameter_inpct = 5%			//the diameter of the target (also start) zone in canvas height percentage (default: 5%)
										//for the default settings, the diameter is: ~0.72cm								
</parameters>