Return to the Spatial Processing Task page
___________________________________________________________________________________________________________________	

								SPATIAL PROCESSING TASK
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 06-02-2014
last updated:  03-10-2020 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 03-10-2020 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________
This script runs a Spatial Processing Task designed to target spatial orientation rotation and short-term memory.
The implemented procedure is based on:

Englund, C.E., Reeves. D.L., Shingledecker, C.A., Thorne, D.R., Wilson, K.P., & Hegge. F.W. (1987).
Unified Tri-Service Cognitive Performance Assessment Battery (UTC-PAB) I. Design and Specification of the Battery. 
Report No. 87-10, Naval Health Research Center, P 0 BOX 85122, San Diego, CA 92138
Naval Medical Research and Development Command, Bethesday, MD (task description: p.26)

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	
Participants are presented sequentially with two 2,4, or 6 bar histograms. The first histogram is the target
histogram. It is always presented in the vertical, upright position. The second histogram is the comparison
histogram. It can be rotated clockwise 0deg, 90/270deg, or 180deg.
The task is to decide as fast as possible if the comparison histogram is congruent or incongruent to the target.
Englund et al (1987) run:
- 2bar histograms rotated by 0 degrees as a low cognitive demand condition
- 6bar histograms rotated by 90/270 degrees as a medium cognitive demand condition
- 2bar histograms rotated by 180 degrees as the a cognitive demand condition

The default setup of this script conforms with this setup. However, by changing parameter settings
any bar histogram (2, 4, 6 bars) can be run in the 0degree, 90degree or 180degree rotation condition.
Check out section Editable Parameters.

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

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

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

/training:						1 = training block; 0 = test block

/nr_bars:						2, 4, or 6 histogram bars
/rotation:					 	0 (same), 
								90 (counterclockwise rotation by 90 degrees), 
								270 (clockwise rotation by 90 degrees), 
								180
								
/congruence:					1 = target and comparison histogram are congruent; 
								2 = target and comparison histogram are incongruent
								
/counttrials_2bars_0:			counts the number of trials presenting 2 bar histograms rotated by 0 degrees
/counttrials_2bars_90:			counts the number of trials presenting 2 bar histograms rotated by 90 degrees counterclockwise
/counttrials_2bars_270:			counts the number of trials presenting 2 bar histograms rotated by 90 degrees clockwise
/counttrials_2bars_180:			counts the number of trials presenting 2 bar histograms rotated by 180 degrees
/counttrials_4bars_0:			counts the number of trials presenting 4 bar histograms rotated by 0 degrees
/counttrials_4bars_90:			counts the number of trials presenting 4 bar histograms rotated by 90 degrees counterclockwise
/counttrials_4bars_270:			counts the number of trials presenting 4 bar histograms rotated by 90 degrees clockwise
/counttrials_4bars_180:			counts the number of trials presenting 4 bar histograms rotated by 180 degrees
/counttrials_6bars_0:			counts the number of trials presenting 6 bar histograms rotated by 0 degrees
/counttrials_6bars_90:			counts the number of trials presenting 6 bar histograms rotated by 90 degrees counterclockwise
/counttrials_6bars_270:			counts the number of trials presenting 6 bar histograms rotated by 90 degrees clockwise
/counttrials_6bars_180:			counts the number of trials presenting 6 bar histograms rotated by 180 degrees
									
response:						the participant's response (scancode of response key)
								30 = A
								38 = L
								
/resp:							the pressed response key indicates: "congruent", "incongruent", "no response" (= trial timed out before active response was given)
								
correct:						the correctness of the response: 1 = correct; 0 = otherwise (incorrect key responses + no responses)

/responseACC:					"correct response", 
								"incorrect response",
								"no response" (= trial timed out before active response was given)
								
latency: 						the response latency in ms; measured from: onset of second histogram
/nr_boxes1_1 -
/nr_boxes6_1:					number of boxes (=height) of bars used for 2, 4, and 6 bar target histograms

/nr_boxes1_2 -
/nr_boxes6_2:					number of boxes (=height) of bars used for 2, 4, and 6 bar comparison histograms
/valid:							debug helper variable that stores whether the incongruent comparison stimuli is really

								incongruent (1 = incongruent; 0 = accidentally congruent for incongruent trial 
								=> the trial should be considered invalid)
									Note: the algorithm used to determine bar heights for incongruent comparison histograms (see EXPRESSIONS) 
									should prevent that accidental congruent histograms are used for incongruent histograms. 
		
									
(2) Summary data file: 'spatialprocessingtask_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)

/propcorrect_2bars_0:			proportion correct responses to 2-bar histograms rotated at 0degrees
/propCongruent_2bars_0:         proportion congruent 2-bar histograms rotated at 0degrees
/meanRT_2bars_0:				mean latency of correct responses to 2-bar histograms rotated at 0degrees			         
/propcorrect_2bars_90:			proportion correct responses to 2-bar histograms rotated at 90degrees
/propCongruent_2bars_90:        proportion congruent 2-bar histograms rotated at 90degrees
/meanRT_2bars_90:				mean latency of correct responses to 2-bar histograms rotated at 90degrees
/propcorrect_2bars_180:			proportion correct responses to 2-bar histograms rotated at 180degrees
/propCongruent_2bars_180:       proportion congruent 2-bar histograms rotated at 180degrees
/meanRT_2bars_180:				mean latency of correct responses to 2-bar histograms rotated at 180degrees

/propcorrect_4bars_0:			proportion correct responses to 4-bar histograms rotated at 0degrees
/propCongruent_4bars_0:         proportion congruent 4-bar histograms rotated at 0degrees
/meanRT_4bars_0:				mean latency of correct responses to 4-bar histograms rotated at 0degrees			         
/propcorrect_4bars_90:			proportion correct responses to 4-bar histograms rotated at 90degrees
/propCongruent_4bars_90:        proportion congruent 4-bar histograms rotated at 90degrees
/meanRT_4bars_90:				mean latency of correct responses to 4-bar histograms rotated at 90degrees
/propcorrect_4bars_180:			proportion correct responses to 4-bar histograms rotated at 180degrees
/propCongruent_4bars_180:       proportion congruent 4-bar histograms rotated at 180degrees
/meanRT_4bars_180:				mean latency of correct responses to 4-bar histograms rotated at 180degrees

/propcorrect_6bars_0:			proportion correct responses to 6-bar histograms rotated at 0degrees
/propCongruent_6bars_0:         proportion congruent 6-bar histograms rotated at 0degrees
/meanRT_6bars_0:				mean latency of correct responses to 6-bar histograms rotated at 0degrees			         
/propcorrect_6bars_90:			proportion correct responses to 6-bar histograms rotated at 90degrees
/propCongruent_6bars_90:        proportion congruent 6-bar histograms rotated at 90degrees
/meanRT_6bars_90:				mean latency of correct responses to 6-bar histograms rotated at 90degrees
/propcorrect_6bars_180:			proportion correct responses to 6-bar histograms rotated at 180degrees
/propCongruent_6bars_180:       proportion congruent 6-bar histograms rotated at 180degrees
/meanRT_6bars_180:				mean latency of correct responses to 6-bar histograms rotated at 180degrees


___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________

Number of bars (2, 4, 6) are tested blockwise. Each of the 3 bar condition runs:
1. Practice: 1 practice block
2. Test: 1 test block

* Each training/test block lasts 3min by default (Editable Value). Number of training and test blocks
can be set under Editable Values.
* Congruence is randomly sampled (with replacement) with the same probability for congruent and incongruent histograms
(controlled via list.congruence)
* Congruence key assignment can be counterbalanced via groupnumber (odd and even groupnumbers run
the opposite key assignment)

Trial Set-Up:
1) Target Histogram presented for 3s (default, Editable Value) with the label '1' under it
2) followed by an interstimulus blank screen of 1s (default, Editable Value)
3) Comparison Histogram presented with the label '2' under it
	a) Training: 15s duration
	b) Test: 1.5s (2 bars), 2.5s (4 bars) and 3.5s (6bars) durations
	Only responses that are given within those time limits are accepted. A valid response
	immediately ends the histogram presentation.
4) Any left-over time (response was given before time limit was up) is added to a blank screen acting as an 
intertrial interval (iti)
(for training: for iti purposes the time limits used for the test are used to determine the iti duration)

___________________________________________________________________________________________________________________
STIMULI
___________________________________________________________________________________________________________________
2, 4, 6 bar Histograms presented in an (invisible) 6 x 6 matrix
The height of each bar (1-6) is determined randomly with the constraint that no 
height can be repeated for a given histogram.

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
Instructions are not original to the task. They are provided by Millisecond Software
as htm pages and simple page elements and can be edited either by changing
the provided html files or directly under Editable Instructions.

Note: in order for the instructions to reflect alternative parameter settings,
some of the conditionalized code used in the htm files can be found in the script itself.

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

/nr_trainingblocks_2bars_:				Number of training blocks to be run for 2-bar condition (default: 1)
											!Note: if set to 0 2 bar histograms are not run											
/nr_testblocks_2bars_:					Number of test blocks to be run for the for 2-bar condition (default: 1)

/nr_trainingblocks_4bars_:				Number of training blocks to be run for 4-bar condition (default: 1)
											!Note: if set to 0 4 bar histograms are not run											
/nr_testblocks_4bars_:					Number of test blocks to be run for the for 4-bar condition (default: 1)

/nr_trainingblocks_6bars_:				Number of training blocks to be run for 6-bar condition (default: 1)
											!Note: if set to 0 6 bar histograms are not run											
/nr_testblocks_6bars_:					Number of test blocks to be run for the for 6-bar condition (default: 1)

Note: if any of the trainingblocks are set to 0, the following settings will be ignored for that condition

/run_2bars_0:							true (1): blocks with 2 bars run 0-rotation histograms (default)
										false (0): blocks with 2 bars do not run 0-rotation histograms
										
/run_2bars_90:							true (1): blocks with 2 bars run 90/270-rotation histograms 
										false (0): blocks with 2 bars do not run 90/270-rotation histograms (default)
										
/run_2bars_180:							true (1): blocks with 2 bars run 180-rotation histograms
										false (0): blocks with 2 bars do not run 180-rotation histograms (default)
									

/run_4bars_0:							true (1): blocks with 4 bars run 0-rotation histograms
										false (0): blocks with 4 bars do not run 0-rotation histograms (default)
										
/run_4bars_90:							true (1): blocks with 4 bars run 90/270-rotation histograms (default)
										false (0): blocks with 4 bars do not run 90/270-rotation histograms
										
/run_4bars_180:							true (1): blocks with 4 bars run 180-rotation histograms
										false (0): blocks with 4 bars do not run 180-rotation histograms (default)										
										
/run_6bars_0:							true (1): blocks with 6 bars run 0-rotation histograms 
										false (0): blocks with 6 bars do not run 0-rotation histograms (default)
										
/run_6bars_90:							true (1): blocks with 6 bars run 90/270-rotation histograms 
										false (0): blocks with 6 bars do not run 90/270-rotation histograms (default)
										
/run_6bars_180:							true (1): blocks with 6 bars run 180-rotation histograms (default)
										false (0): blocks with 6 bars do not run 180-rotation histograms 									
	
Note: the original study used the 
- 2-bar 0deg rotation as a 'low cognitive load condition"
- 4 bar 90/279deg rotation as a 'medium cognitive load condition"
- 6-bar 180deg rotation as a 'high cognitive load condition"

The default set-up of this script runs only those 3 combinations: 2 bars at 0deg, 4 bars at 90deg, 6 bars at 180deg

Response keys:							
/responsekeyleft:					the left response key (default: "A")
/responsekeyright:					the right response key (default: "L")
											Note: response keys are counterbalanced by groupnumber, see section EXPERIMENT

Appearance of Histograms:
/boxheight:							sets the size of the 36 boxes (default: 10%)

/showindividualboxes:				true: individual boxes are shown (horizontal spacing as well as vertical spacing is shown)
									false: only bars are shown (only vertical spacing is shown) (default)
/x_matrix-							 
/y_matrix:							top/left coordinates of the matrix 
/spacing:							manipulates the space between bars (default: 0.4)
/boxcolor:							the color of the histogram bars (default: blue)
/fontsize:							fontsize of the histogram label (default: 3%)


Duration Parameters:
/targetduration:					presentation time of the target histogram (default: 3000ms)

/comparisonduration_2bars:			presentation time of the 2-bar comparison histogram (default: 1500ms)
/comparisonduration_4bars:			presentation time of the 4-bar comparison histogram (default: 2500ms)
/comparisonduration_6bars:			presentation time of the 6-bar comparison histogram (default: 3500ms)

/responseduration_training:			the presentation time of the comparison histogram during training (default: 15000ms)
/isi:								empty screen between offset of target and onset of comparison stimuli (default: 1000ms)

/iti:								default empty screen between offset of comparison stimuli and onset of new target stimuli (default: 500ms)
											Note: if participant responds before the current comparisonduration is done, the 'missing'
											time is added to the iti
											
/blockduration:						the duration of a block (default: 180000ms = 3min)
											Note: after 3 min the block stops