User Manual: Inquisit Psychomotor Vigilance Test

															
___________________________________________________________________________________________________________________	

										*PSYCHOMOTOR VIGILANCE TEST*
___________________________________________________________________________________________________________________	


Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 06-07-2017
last updated:  08-13-2024 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 08-13-2024 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	
This script implements a Psychomotor Vigilance Test, a basic simple response time test. 

The implemented procedure is based on:
Thomann, J.; R. Baumann, C.R.; Landolt, H.-P.; & Werth, E (2014).
Psychomotor Vigilance Task Demonstrates Impaired Vigilance in Disorders with Excessive Daytime Sleepiness.
Journal of Clinical Sleep Medicine, Vol. 10, 1019-1024.

Mathias Basner, MD, PhD, MSc, David F. Dinges, PhD, Maximizing Sensitivity of the Psychomotor Vigilance Test 
(PVT) to Sleep Loss, Sleep, Volume 34, Issue 5, 1 May 2011, Pages 581–591, https://doi.org/10.1093/sleep/34.5.581

___________________________________________________________________________________________________________________
TASK DESCRIPTION
___________________________________________________________________________________________________________________	

Participants are instructed to press the <Spacebar> as fast as possible after a red stopwatch appears
on screen. A valid response (response occurs after stopwatch appears) is followed by reaction time 
feedback. An invalid response (response occurs before stopwatch appears) is followed by a 
brief error message.

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

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

(1) Raw data file: 'psychomotorvigilancetest_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 such as feedback trials. Thus, trialnum 
									may not reflect the number of main trials run per block.
										
ISI:							the currently randomly selected interstimulus interval in ms (randomly sampled from 2-10s)								
response:						the participant's response (scancode of response button): 57 = spacebar press

responseCategory:				"false start" (= response before target occurs) vs.
								"no lapse" (= valid response with latency <= 500ms)
								vs. "lapse" (= valid response with latency > 500ms)
								vs. "lapse-overrun" (= valid response with latency >= parameters.)
									
clock.target.stimulusonset:		the onset time of the clock measured from onset of trial (in ms)									
									
latency: 						the response latency (in ms); measured from onset of trial

rt:								stores the latency of the response measured from onset of target stim
									(calculated as the difference btw. latency - clock.target.stimulusonset)
																			
countFalseStarts:				counts the number of times an invalid (early) response is made in the current block


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

///Summary Variables for Test Block only (excludes Habituation Phase): (see Thoman et al, 2014, p.1020)

meanRT: 						mean valid response latency (in ms; measured from onset of target)
reciprocalMeanRT: 				its reciprocal (see Thoman et al, 2014, p.1020)
medianRT: 						median valid response latency (in ms; measured from onset of target)
maxRT: 							the maximum valid response latency (in ms; measured from onset of target)
minRT: 							the minimum valid response latency (in ms; measured from onset of target)

meanRT500: 						mean valid response latency of responses with latencies <= 500ms (in ms; measured from onset of target)
reciprocalMeanRT500: 			its reciprocal (see Thoman et al, 2014, p.1020)
medianRT500: 					median valid response latency of responses with latencies <= 500ms (in ms; measured from onset of target)
maxRT500: 						the maximum valid response latency of responses with latencies <= 500ms (in ms; measured from onset of target)
minRT500: 						the minimum valid response latency of responses with latencies <= 500ms (in ms; measured from onset of target)

10thpercentile: 				in this script: the 10th percentile RT is taken as the value that sits at the 10%index (rounded to the nearest integer)
								in the sorted RT list 
								Example: the sorted RT list (from slowest to fastest) contains 120 values; 
								the 10th percentile would be the value sitting at index 12 (120*10%) of this sorted list
									
90thpercentile: 				in this script: the 90th percentile RT is taken as the value that sits at the 90%index (rounded to the nearest integer)
								in the sorted RT list
								Example: the sorted RT list (from slowest to fastest) contains 120 values; 
								the 90th percentile would be the value sitting at index 108 (120*90%) of this sorted list									
									
rangeRT:						the difference in ms betw. 10th percentile RT and 90th percentile RT

10thpercentile500: 				in this script: the 10th percentile RT is taken as the value that sits at the 10%index (rounded to the nearest integer)
								in the sorted RT list of valid latencies <= 500ms
									
90thpercentile500: 				in this script: the 90th percentile RT is taken as the value value that sits at the 90%index (rounded to the nearest integer)
								in the sorted RT list of valid latencies <= 500ms
									
rangeRT500:						the difference in ms btw. 10th percentile RT and 90th percentile RT of valid latencies <= 500ms	 							

numberOfLapses:					stores the total number of lapses (responses with latencies > 500ms) during the test block
transformedNumberOfLapses:		numberOfLapses transformed with (sqrt(numberOfLapses) + sqrt(numberOfLapses+1)) (see Thoman et al, 2014, p.1020)

meanLapseRT:					the average lapse in ms (average ms above 500ms for lapses)
cumulativeLapseRT:				the sum of all lapse times during the test block 


countFalseStarts:				counts the number of false starts during the test block 

falseRT:						ratio of
								'number of times participant responded BEFORE target appeared' to 
								'the number of times participant responded AFTER target appeared'
								this ratio is presented as a percentage.
								
* separate data files: to change to one data file for all participants (on Inquisit Lab only), go to section
"DATA" and follow further instructions

___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	

1. Habituation Phase: ~1 min (Block is terminated after the last trial cycle within the designated timeframe)
- same task as actual test but performance is not used for summary statistics
Note: the Habituation Phase seamlessly turns into the Test Phase without giving participants any further warning.
During the first trial only, a reminder to press spacebar is presented on screen.

2. Test Phase: ~10 min (Block is terminated after the last trial cycle within the designated timeframe)

Trial Sequence:
ISI (randomly selected from 2-10s)-> target stim until response-> RT feedback (1000ms)

Note: If a response is made before the target stim appears, a short error message is flashed onto the screen
and a new trial is started.

___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________	
target stimulus is a red stopwatch counter (counts in milliseconds)

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