Return to the Pursuit Rotor Task (beta version only!) page
															       
___________________________________________________________________________________________________________________	

										*PURSUIT ROTOR TASK*
___________________________________________________________________________________________________________________	

last updated:  12-19-2019 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC
Script Copyright © 12-19-2019 Millisecond Software
___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	

This script implements the Pursuit Rotor Task; a task to measure manual dexterity and visual-motor tracking abilities.

References:
-The Multivariate Study of Pursuit Rotor Skill Development, 11 Aug. 2011, http://www.science.smith.edu/departments/EXER_SCI/Faculty/DS/PR.html
-Measuring Hand/Eye Coordination, 11 Aug. 2011, http://www.psywww.com/intropsych/ch07_cognition/measuring_hand_eye_coordination.html
-Pursuit Rotor, 11 Aug. 2011, http://sourceforge.net/apps/mediawiki/pebl/index.php?title=Pursuit_Rotor

___________________________________________________________________________________________________________________
TASK DESCRIPTION
___________________________________________________________________________________________________________________	
Participant tracks a yellow target with a mouse cursor/finger, as the target moves steadily in a circular path. 

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

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

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

usedCanvas_inmm:					data file variable that stores the dimension of the active canvas (in mm) used for the task										
usedCanvas_inpx:					data file variable that stores the dimension of the active canvas (in pixels) used for the task
trackRadius_inmm:					the radius of the track in mm				
discRadius_inmm:					the radius of the disc in mm
discRadius_inpx:					the radius of the target disc in pixels
trialDuration:						the duration of one trial/one rotation in ms (default: 10000ms)

sum_offDurations_trial:				the sum of the durations spent OFF the target disk per trial (in ms)
timeOnTarget_trial:					the duration spent ON the target disk per trial (in ms)

meanDistanceFromCenterDisc_trial:	the mean distance (in pixels) of recorded cursor positions from the center of the target disc per trial
meanOffDistanceFromDiscEdge_trial: 	the mean distance (in pixels) from of the current cursor position from the perimeter of the target circle per trial for OFF target mouse positions

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

usedCanvas_inmm:					data file variable that stores the dimension of the active canvas (in mm) used for the task									
usedCanvas_inpx:					data file variable that stores the dimension of the experimental canvas (in pixels) used for the task
trackRadius_inmm:					the radius of the track in mm				
discRadius_inmm:					the radius of the target disc in mm
discRadius_inpx:					the radius of the target disc in pixels
parameters.trialDuration:			the duration of one trial/one rotation in ms (default: 10000ms)
trial.rotate.trialcount:			the number of trials that were run 

meanTime_OFFTarget:			the average time (in ms) a participant spent OFF disc during a rotation trial
sum_offDurations_total:			the sum of the durations spent OFF the target disk across all trials (in ms)
timeOnTarget_total:			the duration spent ON the target disk across trials (in ms)

meanDistanceFromCenterDisc_total:		the mean distance (in pixels) of recorded cursor positions from the center of the target disc across trials
meanOffDistanceFromDiscEdge_total:	the mean distance (in pixels) of recorded mouse positions from the target disc (to edges of disc; not the center) across trials (= OFF target distances)

										
(3)	Mouse Cursor Position data file: 'pursuitrotor_stream*.iqdat' (a separate file for each participant)
This data file records mouse positions and relevant data after each stimulusframe

build:							The specific Inquisit version used (the 'build') that was run
computer.platform:				the platform the script was run on (win/mac/ios/android)
display.refreshinterval:				the refreshrate of the current monitor
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. 
										
usedCanvas_inmm:					data file variable that stores the dimension of the active canvas (in mm) used for the task									
usedCanvas_inpx:					data file variable that stores the dimension of the experimental canvas (in pixels) used for the task
trackRadius_inmm:					the radius of the track in mm				
discRadius_inmm:					the radius of the disc in mm
discRadius_inpx:					the radius of the target disc in pixels
parameters.trialDuration:			the duration of one trial/one rotation in ms (default: 10000ms)										

rotationCount:						the count of the current rotation trial (1-4)
mouse.x:							the recorded  horizontal coordinate of the cursor at the end of a vertical frame refresh (in screen pixels)
mouse.y:							the recorded  vertical coordinate of the cursor at the end of a vertical frame refresh (in screen pixels)
shape.animatedCircle.hposition:		the recorded  horizontal coordinate of the target disc at the end of a vertical frame refresh (in screen pixels)
shape.animatedCircle.vposition:		the recorded  vertical coordinate of the target disc at the end of a vertical frame refresh (in screen pixels)
distance:							the pixel distance from the mouse cursor to the center of the target disc
OFFtarget:							"ON" or "OFF": compares distance to radius of disc
script.elapsedtime:					the elapsed script time in ms at point of data recording
offDuration:						stores the last calculated duration (in ms) participant spent off the disc
	
___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	
- task runs 4 trials (default; can be edited under section Editable Parameters) 
- each trial takes 10s (default; can be edited under section Editable Parameters)
- the script records the position of cursor and disc every 16.7ms on a 60Hz monitor (vertical refresh rate of monitor) 
in the datastream data file

Note: the default active canvas is set to be 120mm x 120mm. All stimuli are defined in proportion to the
height of the active canvas.
If the script is run on a screen that does not support these dimensions, the script
alerts participants and then aborts.

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

User Interface: 	
the active canvas (= the part of the screen used for the task) can be specified in mm.
The radius of the track as well as the radius of the disc and all text stimuli
are defined in proportion to the height of the active canvas.
Note: the canvas in this script is defined with width:height = 1:1


/canvasHeight_inmm:				The default height of the active canvas is 120mm							
/trackRadius_propCanvasHeight:	the radius of the track as a proportion of the canvas height (default: 0.4 => 0.4*120 = 48mm)
/discRadius_propCanvasHeight:	the radius of the disc as a proportion of the canvas height (default: 0.065 => 7.8mm)							



/trialDuration:					the duration of one trial/one rotation in ms (default: 10000ms)
/NumTrials:						the number of trials to run (default: 4)

/presentSummaryFeedback:		true (1) = presents performance feedback at the end of the script (default)
								false (0) = does not present performance feedback