User Manual for Inquisit's Automated Operation Span

													
___________________________________________________________________________________________________________________	

								*Automated Operation Span Task (AOSPAN)*
___________________________________________________________________________________________________________________	

Main Inquisit programming: David Nitz (dave@millisecond.com) for Millisecond Software, LLC.
Additional Inquisit programming: Jerry Grenard (grenard@ucla.edu), Sean Draine (seandr@millisecond.com)

last updated:  02-25-2022 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 02-25-2022 Millisecond Software
Task Copyright © 2005 by Dr. Randall Engle (http://psychology.gatech.edu/renglelab/)

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	

This script implements the Automated Operation Span Task (AOSPAN), a measure of working memory.

Working Memory Span Tasks Reference:
CONWAY, A.R.A., KANE, M.J.,BUNTING, M.F., D. ZACH HAMBRICK, D.Z., WILHELM, O., & ENGLE, R.W. (2005).
Working memory span tasks: A methodological review and user’s guide. Psychonomic Bulletin & Review
2005, 12 (5), 769-786.

___________________________________________________________________________________________________________________
TASK DESCRIPTION
___________________________________________________________________________________________________________________	
Participants are presented a visual sequences of letters ranging from 3-7 letters (default) that need to be 
recalled at the end.
Each letter in the sequence in preceded by a math problem ("(8*2) - 8 = ?") followed by a proposed solution ("e.g. 9") 
and participants have to decide whether the proposed solution is correct or not. 
Letter recall is tested by asking participants to selecte letters from a provided letter matrix.	

___________________________________________________________________________________________________________________	
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: 'aospan_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. 
											
stimulusitem.1:					the presented stimuli in order of trial presentation
response:						the participant's response (scancode of response buttons)
correct:						accuracy of response: 1 = correct response; 0 = otherwise
latency: 						the response latency (in ms)

currentsetsize: 				the number of letters to recall for the current problem
text.letters.currentitem: 		the currently presented letter
mathproblemcount: 				counts the number of math problems in a given block
text.MathProblem.currentitem: 	the currently presented math problem
mathtrueanswer:					the correct math answer
mathanswer:						the math response given

mathcorrect:					1 = correct math response; 
								0 = incorrect math response
									
mathaccuracy: 					percentage of correctly solved math problems within the current block
mathtotalerrors: 				counts number of any errors (speed or accuracy) made during math problems within the current block
mathaccerrors: 					counts the number of incorrectly solved math problems within the current block
mathspeederrors: 				counts the number of times participant ran out of time when solving the math problems within the current block

mathtimeout:					duration (in ms) after which the math problem disappears 
								(for test block: calculated for each participant based on average performance during practice) 

recalledletters: 				the number of letters recalled of the current problem
totalcorrectletters: 			the total number of letters recalled in the correct position.
totalrecalledsets: 				the number of correctly recalled sets

ospan:							The OSPAN score, uses the traditional "absolute ospan" scoring method. 
								It is the sum of all perfectly recalled sets. 
								So, for example, if an individual recalled correctly 2 letters in a set size of 2,
								3 letters in a set size of 3, and 3 letters in a set size of 4,
								their OSPAN score would be 5 (2 + 3 + 0).
								
								
//trial data (summary at the end of each complete ' test trial' stored under trial 'letter_feedback')
trialCount:						trial counter
recalledLetters_perTrial:		the number of recalled letters for the current trial only
recalledLettersACC_perTrial:	proportion correct recalled letters for the current trial only
correctMath_perTrial:			the number of correctly categorized math problems for the current trial only
mathACC_perTrial:				proportion correctly categorized math problems for the current trial only								


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

ospan:							The OSPAN score, uses the traditional "absolute ospan" scoring method. 
								It is the sum of all perfectly recalled sets. 
								So, for example, if an individual recalled correctly 2 letters in a set size of 2,
								3 letters in a set size of 3, and 3 letters in a set size of 4,
								their OSPAN score would be 5 (2 + 3 + 0).	
										
totalcorrectletters: 			the total number of letters recalled in the correct position.
mathtotalerrors: 				counts number of any errors (speed or accuracy) made during math problems within the current block
mathspeederrors: 				counts the number of times participant ran out of time when solving the math problems within the current block
mathaccerrors: 					counts the number of times participant ran out of time when solving the math problems within the current block

___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________
1 Practice Session (default):
	a) Practice of recalling sequences of letters of set sizes 2-3 in ascending order (4 trials)
	b) Practice of math task (15 trials)
	c) Combined practice of recalling sequence of letters (set size 2 only) and math problem: each letter is 
	preceded by a math problem (3 trials)
	Letter recall is done by picking out letters from a provided letter matrix.

Test Session (default):
	15 Trials (15 = 3 repetitions of 5 set sizes; order of set sizes is randomly determined): 
	Recalling sequences of letters (set size 3-7): each letter is preceded by a math problem;
	Letter recall is done by picking out letters from a provided letter matrix.

Scoring:
The program reports five values at the conclusion of the experiment: 
	
The first, OSPAN score, uses the traditional "absolute ospan" scoring method. 
It is the sum of all perfectly recalled sets. 
So, for example, if an individual recalled correctly 2 letters in a set size of 2,
3 letters in a set size of 3, and 3 letters in a set size of 4,
their OSPAN score would be 5 (2 + 3 + 0).

Total number correct is the total number of letters recalled in the correct position
(2 + 3 + 4 = 9 in the above example). 
	
Math errors are reported as total number of errors, 
accuracy errors where the subject solved the operation incorrectly, 
and speed errors in which the subject ran out of time 
in attempting to solve a given operation.

___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________	
Letters: T, L, Q, N, F, H, Y, S, P, K, R, J
Math Problems (test): created on runtime; only math problems with a *true* result >= 0 are allowed in the task

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
see 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.

/ learninginterval:					duration (in ms) of the letter presentation trials

/ startmathtimeout:					start duration (in ms) of the math presentation trials
									Note: the duration is adjusted for the test trials based on practice performance
									
/ debugmode:						0 = testmode => no debug information is presented
									1 = debugmode => debug information is presented on screen