User Manual for Inquisit's Adaptive Reading Span


___________________________________________________________________________________________________________________	

								*Adaptive Composite Complex Span Test (ACCES)*
								Subtest: Reading Span Test (RSPAN)
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 05-29-201904
last updated: 03-24-2022 by K.Borchert (katjab@millisecond.com) for Millisecond Software LLC

Script Copyright © 03-24-2022 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	

This script implements the Reading Span Test subtest of the Adaptive Composite Complex Span Test (ACCES); 
an adaptive test of working memory with visuospatial ("symmetry span test"), mathematical ("operation span test")
and verbal subtests ("reading span test").
 
The ACCES was developed by Gonthier et al (2018). According to the authors "the test presents a fixed number 
of trials to all participants, allows for partial credit scoring, and can be used with children regardless
of ability level. The ACCES demonstrated satisfying psychometric properties in a sample of 268 children 
aged 8–13 years." (p.910)

All materials for the ACCES – including the stimuli, an open source implementation
of the task script under PsychoPy (Peirce, 2007), and all validation data – can be accessed via the Open Science
Framework platform at https://osf.io/bk7pm/.

Norms in this script (based on grade level) use the data provided by Gonthier et al (2018) 
collected with a sample of French students.

Reference:
Gonthier, C., Thomassin, N., & Roulin, J.-L. (2016). The Composite Complex Span: 
French validation of a short working memory task. Behavior Research Methods, 48(1), 233-242. 
doi:10.?3758/?s13428-015-0566-3

Gonthier C, Aubry A, Bourdin B. (2018). Measuring working memory capacity in children using adaptive tasks: 
Example validation of an adaptive complex span. Behav Res Methods. Jun;50(3):910-921. 
doi: 10.3758/s13428-017-0916-4. PMID: 28643158.

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	

Participants work on 6 reading span test trials. Levels for each trial (after the first) are adapted
based on performance.

Reading Span Test: a dual task involving the evaluation of simple sentences while
also recalling a sequence of digits for a later recall test:
Evaluation of Sentence -> Digit Learning -> Evaluation of Sentence -> Digit Learning.....-> Digit Recall

The number of 'sentence-evaluations/digit learning' combos  depends on the level of difficulty (=span size) 
of the current test trial. All participants start at level 4. Depending on performance they move up, 
stay on the same level,  or go down a level. The lowest level tested is level 2; the highest level tested 
is level 8.

The task provides 3 practice session before the actual 6 test trials are run:
Practice 1: training of the digit recall task
Practice 2: training of the sentence evaluation task
Practice 3: dual training of the combined task

___________________________________________________________________________________________________________________	
DURATION 
___________________________________________________________________________________________________________________	
the default set-up of the script takes appr. 9 minutes to complete
___________________________________________________________________________________________________________________	
DATA FILE INFORMATION 
___________________________________________________________________________________________________________________		
The default data stored in the data files are:

(1) Raw data file: 'acces_rspan_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. 
										
										
age:				the entered age of the participant 
gradeLevel:			the entered grade level of the participant 
gender:				the entered gender of the participant

phase:				stores the name of the current task phase										
RoundCount:			counts the rounds ("trials") run in the current phase										
currentLevel:		stores the levelspansize tested in the current round

***************************************
Processing Task Variables:
***************************************
ProcessingTaskProblem:		stores the current processing task problem (e.g. sentence evaluation) presented
correctResponse:			stores the correct response to the current processing task problem	(TRUE vs. FALSE)	
processingTaskResponse:		stores the given response to the current processing task problem	(TRUE vs. FALSE)

processingTaskACC:			stores the accuracy of the processing task response
										1 = correct
										0 = error
										
processingTaskCumACC:		stores the number of correct processing task responses		

***************************************
Memory Task Variables:
***************************************
stim:						stores the current recall stim (e.g. digit) presented								
currentStims:				stores the collected recall stims of the current round in the order presented
recallResponse:				stores the recall stims of the current round in the order selected on the recall matrix									
numberStimsRecalled:		stores the number of correctly recalled stims of the current round
Total_StimsRecalled:		stores the total number of correctly recalled stims during the current task

										
stimulusitem:				the presented stimuli in order of trial presentation of the currently recorded trial
response:					the participant's response (scancode of response buttons) of the currently recorded trial
correct:					accuracy of response: 1 = correct response; 0 = otherwise of the currently recorded trial
latency: 					the response latency (in ms) of the current trial


(2) Summary data file: 'acces_rspan_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)	
								
								
age:						the entered age of the participant 
gradeLevel:					the entered grade level of the participant 
gender:						the entered gender of the participant								
									
rs_duration_ins:			the RSPAN task duration in seconds

rs_Total_StimsRecalled:		the total number of digits recalled across all 6 RSPAN test rounds
rs_zScore:					the calculated z-score of the total number of recalled digits across all 6 RSPAN test rounds
rs_percentile:				the calculated percentile of the z-score of the total number of recalled digits across all 6 RSPAN test trials
										Note: mean and standard deviation used to calculate z-scorespercentile ranks are based on published data
										by Gonthier et al (2018) using a sample of French students. For more detail see Gonthier et al (2018).

list.rs_processingACC_overall.mean: 	the mean proportion correct Processing Task ('sentence problems') performance across all 6 RSPAN test rounds
														
rs_processingTaskFlag:			1 = the mean proportion correct RSPAN Processing Task ('sentence problems') performance is below 70% correct 
									(RSPAN performance is flagged)
								0 = otherwise (RSPAN performance is not flagged)

list.rs_currentLevels.mean:		the average RSPAN span size worked on
list.rs_currentLevels.minimum:	the minimum RSPAN span size worked on (lowest possible span size tested: 2)
list.rs_currentLevels.maximum:	the maximum RSPAN span size worked on (highest possible span size tested: 8)
 
rs_Level2Count:					number of times span size 2 was run during the RSPAN 
rs_Level3Count:					number of times span size 3 was run during the RSPAN 
rs_Level4Count:					number of times span size 4 was run during the RSPAN 
rs_Level5Count:					number of times span size 5 was run during the RSPAN  
rs_Level6Count:					number of times span size 6 was run during the RSPAN 
rs_Level7Count:					number of times span size 7 was run during the RSPAN 
rs_Level8Count:					number of times span size 8 was run during the RSPAN 

***************************************
RSPAN Descriptive Statistics by Round:
***************************************
rs_level_Round1:					RSPAN span size tested during Round 1 (by default: 4)
rs_problemCumACC_Round1:			number of correctly answered RSPAN Processing Task ('sentence evaluation task') problems during Round 1
rs_processingACC_Round1:			proportion correct RSPAN Processing Task ('sentence evaluation task') performance during Round 1		
rs_stims_Round1: 					the presented RSPAN recall stims ('digits') during Round 1 (in the order presented)
rs_recallResponse_Round1:			the recalled RSPAN stims ('digits') during Round 1 (in the order selected)
rs_numberStimsRecalled_Round1:		the number of correctly recalled RSPAN stims ('digits') during Round 1

rs_level_Round2:					RSPAN span size tested during Round 2 
rs_problemCumACC_Round2:			number of correctly answered RSPAN Processing Task ('sentence evaluation task') problems during Round 2
rs_processingACC_Round2:			proportion correct RSPAN Processing Task ('sentence evaluation task') performance during Round 2		
rs_stims_Round2: 					the presented RSPAN recall stims ('digits') during Round 2 (in the order presented)
rs_recallResponse_Round2:			the recalled RSPAN stims ('digits') during Round 2 (in the order selected)
rs_numberStimsRecalled_Round2:		the number of correctly recalled RSPAN stims ('digits') during Round 2

rs_level_Round3:					RSPAN span size tested during Round 3 
rs_problemCumACC_Round3:			number of correctly answered RSPAN Processing Task ('sentence evaluation task') problems during Round 3
rs_processingACC_Round3:			proportion correct RSPAN Processing Task ('sentence evaluation task') performance during Round 3		
rs_stims_Round3: 					the presented RSPAN recall stims ('digits') during Round 3 (in the order presented)
rs_recallResponse_Round3:			the recalled RSPAN stims ('digits') during Round 3 (in the order selected)
rs_numberStimsRecalled_Round3:		the number of correctly recalled RSPAN stims ('digits') during Round 3
 
rs_level_Round4:					RSPAN span size tested during Round 4 
rs_problemCumACC_Round4:			number of correctly answered RSPAN Processing Task ('sentence evaluation task') problems during Round 4
rs_processingACC_Round4:			proportion correct RSPAN Processing Task ('sentence evaluation task') performance during Round 4		
rs_stims_Round4: 					the presented RSPAN recall stims ('digits') during Round 4 (in the order presented)
rs_recallResponse_Round4:			the recalled RSPAN stims ('digits') during Round 4 (in the order selected)
rs_numberStimsRecalled_Round4:		the number of correctly recalled RSPAN stims ('digits') during Round 4

rs_level_Round5:					RSPAN span size tested during Round 5 
rs_problemCumACC_Round5:			number of correctly answered RSPAN Processing Task ('sentence evaluation task') problems during Round 5
rs_processingACC_Round5:			proportion correct RSPAN Processing Task ('sentence evaluation task') performance during Round 5		
rs_stims_Round5: 					the presented RSPAN recall stims ('digits') during Round 5 (in the order presented)
rs_recallResponse_Round5:			the recalled RSPAN stims ('digits') during Round 5 (in the order selected)
rs_numberStimsRecalled_Round5:		the number of correctly recalled RSPAN stims ('digits') during Round 5

rs_level_Round6:					RSPAN span size tested during Round 6 
rs_problemCumACC_Round6:			number of correctly answered RSPAN Processing Task ('sentence evaluation task') problems during Round 6
rs_processingACC_Round6:			proportion correct RSPAN Processing Task ('sentence evaluation task') performance during Round 6		
rs_stims_Round6: 					the presented RSPAN recall stims ('digits') during Round 6 (in the order presented)
rs_recallResponse_Round6:			the recalled RSPAN stims ('digits') during Round 6 (in the order selected)
rs_numberStimsRecalled_Round6:		the number of correctly recalled RSPAN stims ('digits') during Round 6

*******************************
RSPAN Training Performance:
*******************************
rs_spanTaskTrainingCount:			the number of times the RSPAN span task training was run (RSPAN practice 1)
rs_processingTaskTrainingCount:		the number of times the RSPAN processing task training was run (RSPAN practice 2)
rs_dualTaskTrainingCount:			the number of times the RSPAN span task training was run (RSPAN practice 3)


*******************************
RSPAN Processing Task duration:
*******************************
rs_processingTaskMaxDuration:		the maximum duration (in ms) that RSPAN processing Task problems ('sentence problems')
										are presented during the Dual Task Training block (=practice3) and the actual Test rounds.
										This duration was calculated based on the Median Processing Task Duration during
										the Processing Task Training (=practice2):
										'RS ProcessingTask medianRT' + 2.5 x 'RS Processing Task MAD RT'
									
rs_processingRT_median:				the median response latency answering RSPAN processing task problems ('sentence problems') during practice2
rs_processingRT_MAD:				Median Absolute Deviation (MAD) of response latencies answering RSPAN processing task problems during practice2

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

Note: level = span size

4 phases:

PHASE 1: Practice 1 -Digit Recall Training ("Memory Task")
Participants work on 2 trials (level 2, followed by level 3) with a fixed set of stimuli for each round.
During this phase, they only work on the digit recall task (no sentences are presented)

Trial Sequence:
blank (700ms)->Start Fixation Cross (presented for 1200ms) -> blank (for 500ms) ->
Digit (800ms) -> Blank (800ms) -> Digit (800ms) -> Blank (800ms) -> .......-> Blank (700ms) 
-> Recall Screen (as long as needed, corrections possible) -> Feedback (3000ms)

At the end of Practice1, recall performance is analyzed and the practice block is repeated 
IF mean recall performance is under 70% correct.
(recall performance: the number of digits correctly recalled in the exact position of presentation)

PHASE 2: Practice 2 - Sentence Evaluation Training ("Processing Task")
Participants work on 10 sentences (e.g. "Fish live on land") and evaluate them to be 'true' or 'false'.
The sentences are the same for each participant and are presented in fixed order. 
No digit recall task is run.

Trial Sequence:
blank (700ms)->Start Fixation Cross (presented for 1200ms) -> blank (for 500ms) ->
Sentence (max. 8000ms) -> Feedback (3000ms) -> Blank (150ms) -> Sentence (max. 8000ms) -> Feedback (3000ms)....

At the end of this practice round, evaluation performance is analyzed and the practice block is repeated
if the proportion correctly evaluated sentences is under 70% correct.
Furthermore, the duration of the sentence presentation for the test trials is calculated:
median time (in ms) the problems were answered + 2.5 x Median Absolute Deviation (MAD).
(Range: 2000ms - 8000ms)

PHASE 3: Practice 3 - Dual Task Training
Participants work on 2 combined trials (level 2, level 3). The stimuli are the same for all participants
and are presented in fixed order.

Trial Sequence:
blank (700ms)->Start Fixation Cross (presented for 1200ms) -> blank (for 500ms) ->
Sentence (calculated presentation time during practice 2) -> Blank (150ms) ->
Digit (800ms) -> Blank (800ms) -> 
Sentence (calculated presentation time during practice 2) -> Blank (150ms) ->
Digit (800ms) -> Blank (800ms) -> .....

Digit (800ms) -> Blank (700ms) -> Recall Screen

At the end of this practice round, performance is analyzed and feedback is provided.


PHASE 4: Test (Dual Task) 
Participants work on 6 combined trials (starting level = 4; levels are adjusted based on performance
thereafter). Each trial (1-6) presents the stimuli from the same stimuli lists in the same order 
(though not all participants will work on all the possible stimuli of a particular trial as this is
level dependent). No more feedback is provided.

Trial Sequence:
blank (700ms)->Start Fixation Cross (presented for 1200ms) -> blank (for 500ms) ->
Sentence (calculated presentation time during practice 2) -> Blank (150ms) ->
Digit (800ms) -> Blank (800ms) -> 
Sentence (calculated presentation time during practice 2)  -> Blank (150ms) ->
Digit (800ms) -> Blank (800ms) -> .....

Digit (800ms) -> Blank (700ms) -> Recall Screen

During each round, the computer calculates
a. processing task performance (here: sentence evaluation performance)
b. recall performance
		- the number of correctly recalled digits 
		- the total number of correctly recalled digits
		
At the end of each round, the next level is determined based on recall performance:
1. levels goes down by 1 for recall performance less than 60%
2. levels stay the same for 60% <= recall performance < 100%
3. levels go up by 1 for perfect recall performance (100% correct)

___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________	
All original French stimuli are provided by Gonthier et al (2018)

All materials for the ACCES – including the stimuli, an open source implementation
of the task script under PsychoPy (Peirce, 2007), and all validation data – can be accessed via the Open Science
Framework platform at https://osf.io/bk7pm/.

IMPORTANT NOTE:
This script uses English sentences provided by Millisecond Software.
The sentences are similar to the original French ones by Gonthier et al (2018); however,
they are untested. The sentences can easily be exchanged under section Editable Stimuli.

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	

Instructions are modelled after the ones used in the e-prime script provided
by Gonthier et al (2018).

The instructions in this script are provided by as htm/html pages  and can be edited by changing the 
provided htm/html files. To edit htm/html-files: open the respective documents in simple Text Editors 
such as TextEdit (Mac) or Notepad (Windows).

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: see below