# User Manual: Inquisit Random Dot Kinematogram (RDK) with Staircase Procedure

```
___________________________________________________________________________________________________________________

*DOT MOTION DISPLAY - COHERENCE THRESHOLD ESTIMATION*
MAIN SCRIPT
___________________________________________________________________________________________________________________

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 03-10-2021
last updated:  01-19-2023 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Millisecond Software thanks Dr. Aaron Seitz for his generous help with Random Dot Motion Displays!

___________________________________________________________________________________________________________________
BACKGROUND INFO
___________________________________________________________________________________________________________________

This script runs a double staircase procedure to find coherence thresholds for random moving dot displays.
Some parameters can be selected during runtime (dotPositionDuration needs to set under section
Editable Parameters)

STAIRCASE PROCEDURE:

The implemented double staircase procedure is as follows:
- staircase1 starts at coherence = 0.15
- staircase2 starts at coherence = 0.05
- angle (=> direction) of signal dot movement is randomly selected from 24 possible values (list.angle)

- two directional, orthogonal axes are provided and participant has to select the one that corresponds to the movement of the signal dots
- after 3 consecutive correct responses/selections (for the same staircase) the dot coherence for this staircase gets adjusted down
by = coherence * 0.9
- after 1 incorrect response the dot coherence for this staircase gets adjusted up
by = coherence/0.9

Stopping points:
- after 7 reversal points a staircase stops
- if a participant reaches the extreme value coherence = 0.1 and gets it correct 3 times in a row, the staircase stops and coherence value for this staircase = 0.1
- if a participant reaches the extreme value coherence = 1.0 and gets it incorrect 3 times in a row, the staircase stops and coherence value for this staircase = 1
- the staircase procedure stops after 300 trials whether or not a threshold for each staircase has been found. In that case the last coherence tested is taken as the threshold for this staircase.

Threshold calculation per staircase:
- if a participant reaches the extreme value coherence = 0.1 and gets it correct 3 times in a row, coherence value for this staircase = 0.1
- if a participant reaches the extreme value coherence = 1.0 and gets it incorrect 3 times in a row, coherence value for this staircase = 1
- the staircase procedure stops after 300 trials whether or not a threshold has been found. In that case the last coherence tested
is taken as the threshold for this staircase.
- otherwise: mean of the 7 (or fewer) reversal points

Final Threshold:
- mean of the two staircase thresholds

DOT DISPLAYS: general info
Each dot (example: 100 dots) hops through 121 positions and
for each of those 121 positions a certain number of these 100 dots are randomly selected to be signal dots (move coherently)
and the remaining dots are assigned to be noise dots (are randomly placed).

A dot that moves as a signal dot from position2 to position3 might randomly be selected to be a random noise dot
for position4 (see Pilly & Seitz, 2009, figure1, p.3: "signal dots are recruited afresh from each frame to the next").
However, for each position, the same number of dots are recruited to be signal dots.

The number of signal vs. noise dots per position depends on the currently tested coherence.

Reference
Pilly, P.K. & Aaron R. Seitz, A.R (2009)
What a difference a parameter makes: A psychophysical comparison of random dot motion algorithms,
Vision Research, 49, 1599-1612,
https://doi.org/10.1016/j.visres.2009.03.019.

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

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

(1) Raw data file: 'staircase_rdkt_main_dynamicdots_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.
///Settings:
numberOfDots:					the number of dots in the dot display
dotSize:						the proportional sizing of the dot (proportional to canvas height)
radius:							the proportional radius (to canvas height) of the background circle (max: 0.5)
speed:							movement 'speed' (as calculated as %screen height displacement per 'frame')
dotPositionDuration:			the duration (in ms) that a dot stays in one place
animationDuration:				the entire duration (in ms) of the animation (121*dotPositionDuration)

///TrialData:
trialCounter:					tracks the number of staircases trial run (max: 300)

staircase:						1 vs. 2 (the current staircase run)
angle:							the angle (clockwise) of the directional movement of the signal dots
coherence:						the currently tested coherence
reversal:						1 = reveral detected; 0 = no reversal

//per staircase
staircase1_direction:			the coherence direction of the current staircase (1 = down, 2 = up)
staircase1_coherence:			the last tested coherence of staircase1
staircase1_newCoherence:		the next coherence to be tested for staircase1
staircase1_reversalCount:		the number of reversals for staircase1
staircase1_maxCoherenceCount:	the number of consecutive max (1.0) coherence tests for staircase1
staircase1_minCoherenceCount:	the number of consecutive min (0.1) coherence tests	for staircase1
staircase1_consecutiveCorrect:	the number of consecutive correct responses for staircase1
staircase1_stop:				1 = staircase1 has reached stopping point; 0 = staircase1 has not reached a stopping point yet

//DVs:
response:						the participant's response:
correctAxis
incorrectAxis

correct:						accuracy of response: 1 = correct response; 0 = otherwise
latency: 						the response latency (in ms); measured from: onset of axes display

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

///Settings:
numberOfDots:					the number of dots in the dot display
dotSize:						the proportional sizing of the dot (proportional to canvas height)
radius:							the proportional radius (to canvas height) of the background circle (max: 0.5)
speed:							movement 'speed' (as calculated as %screen height displacement per 'frame')
dotPositionDuration:			the duration (in ms) that a dot stays in one place
animationDuration:				the entire duration (in ms) of the animation (121*dotPositionDuration)

///Data:
threshold_staircase1:			the calculated coherence threshold for staircase1
threshold_staircase2:			the calculated coherence threshold for staircase2
threshold:						the mean of the two calculated thresholds

* separate data files: to change to one data file for all participants (on Inquisit Lab only), go to section