___________________________________________________________________________________________________________________
Millisecond Box Task
___________________________________________________________________________________________________________________
Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 10-04-2022
last updated: 04-03-2023 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC
Script Copyright © 04-03-2023 Millisecond Software
___________________________________________________________________________________________________________________
BACKGROUND INFO
___________________________________________________________________________________________________________________
This script implements Millisecond Software's version of the 'Box Task' by Kessels & Postma (2018).
The 'Box Task' is a Visuospatial Memory Task originally written in Microsoft Visual Basic and
runs on Windows machines. It allows the computation of different error scores that measure
specific working memory processes (i.e., the number of within-search and between-search errors).
The original Box Task program by Kessels & Postma provides a stimulus set and a default
experimental setup but also allows further customizations of the task.
DISCLAIMER: The Inquisit implementation is based on Kessel & Postma's (2017) description of the 'Box Task'.
Millisecond Software attempts to replicate the general memory task but differences between the
implementations will exist.
The Inquisit implementation runs on Windows, Macs, Androids and Ios and can be run online. It thus
expands the number of devices/platforms the Box Task can be run on.
As the original 'Box Task', the Inquisit implementation provides stimuli and a default setup and allows
for some customization of the task via parameter settings.
The default setup for the Millisecond Software Box Task is optimized for touchscreen devices
sized like an ipad but adapts to mouse use on non-touchscreens. By default, the stimuli are
absolutely sized if the current screen size is big enough - if not, the script uses the
largest 4:3 portion ofthe current screen (e.g. smartphone screen) that it can find.
Absolute sizing of stimuli can easily be turned off or fine-tuned via parameter settings.
Reference:
Kessels RPC, Postma A. The Box Task: A tool to design experiments for assessing visuospatial working memory.
Behav Res Methods. 2018 Oct;50(5):1981-1987. doi: 10.3758/s13428-017-0966-7. PMID: 28916951.
___________________________________________________________________________________________________________________
TASK DESCRIPTION
___________________________________________________________________________________________________________________
N-objects are hidden in N boxes and participants have to find them by opening boxes.
Participants are told which specific object to look for next ('target'). If the target box is opened, the program
shows the target object for a short period of time before closing the box again. Once found, all objects stay in
their boxes, but all boxes will be closed during the search. Thus, if a box is opened that does not contain
the target object, it either shows one of the already found objects or it appears empty.
Box locations stay the same throughout each run.
The default setup of this Inquisit script runs 2 practice rounds (with 3 boxes each), followed by two rounds of
4, 6 and 8 boxes each. The maximum number of boxes that can be run is 10 in the Inquisit script.
The individual objects and boxes as well as box locations are randomly determined for each round in this script.
Note: the script provides 42 different objects to run with the default set-up without repeating
any objects.
___________________________________________________________________________________________________________________
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: 'ms_boxtask_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: with the current subject id
group: with the current group id
session: with the current session id
//Screen Setup:
(parameter) runAbsoluteSizes: true (1) = should run absolutely sized canvas (see parameters- canvasHeight_inmm)
false (0) = should use proportionally sized canvas (uses width = 43*screenHeight)
canvasAdjustments: NA: not applicable => parameters- runAbsoluteSize was set to 'false'
0: parameters- runAbsoluteSize was set to 'true' and screen size was large enough
1: parameters- runAbsoluteSize was set to 'true' BUT screen size was too small and
adjustments had to be made
activeCanvasHeight_inmm: the width of the active canvas (by default: lightGray area) in mm
activeCanvasWidth_inmm: the height of the active canvas in mm
display.canvasHeight: the height of the active canvas in pixels
display.canvasWidth: the width of the active canvas in pixels
px_per_mm: the conversion factor to convert pixel data into mm-results for the current monitor
(Note: the higher resolution of the current monitor
the more pixels cover the same absolute screen distance)
This factor is needed if you want to convert pixel data into absolute mm data or the other way around
//built-in Inquisit variables:
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.
Note: trial.searchEnd currently stores the summary of a target search.
response: the response of participant during current trial
correct: correctness of response (1 = correct, 0 = error)
latency: response latency (in ms)
//custom variables:
phase: "practice" vs. "test"
roundCounter: a counter that tracks how many rounds have been run in the current phase
setSize: the currently tested setsize
selectBoxImage: the itemnumber of the current box image
targetBoxes: a variable that stores all the target boxes used per round
(in the order the target box was selected)
newTarget: 1 = a new target was chosen for the last search; 0 = participant continued a target search
countTargets: counter that updates the number of targets searched for per round
countAttempts_perTarget: counter that updates how many boxes were opened to find current target
targetObject: stores the image file for the current target object
targetBox: stores the number of the box that currently hides the target object
//custom DVs
selectedBox: stores the number of the last box that was selected to open
success: 1 = target object was found in the last selected box; 0 = otherwise
selectionOrder: stores the order in which the boxes were opened
searchACC: 1 = the current target object was found without making any within or between errors
0 = otherwise
countErrors_between: counts the number of times participant selected a box that contained
an 'old' target (one previously found) and thus could not contain the
current target object
(reset for each new target object)
countErrors_within: counts the number of times participants opened a non-target box
already checked (and rejected) for the current target
(reset for each new target object)
Note: repeatedly opening the same non-target box that contains an old target
is counted as both a 'between' error AND a 'within' error.
TotalErrors_between_perRound: sums up all between-errors made during the current round
TotalErrors_within_perRound: sums up all within-errors made during the current round
searchTime_ins: stores the search time spent on this round (in s)
selectionTimestamps: a storage variable that stores the search timestamps of all selected boxes
relative to start of current round
Example: '1@1.70 2@3.70'
=> box1 was opened at 1.7s after roundstart
=> box2 was opened at 3.7s after roundstart
//only relevant for timed out runs:
timedOut: timed out rounds record 1 during trial.timedoutFeedback (otherwise the column should be empty)
roundTimeout: the current round timeout (in ms)
//placement violation flag
boxPlacementViolation: 1 (true) = at least one box violated the placement constraint (overlap possible)
0 (false) = no placement violations detected
(2) Summary data file: 'ms_boxtask_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)
//Screen Setup:
(parameter) runAbsoluteSizes: true (1) = should run absolutely sized canvas (see parameters- canvasHeight_inmm)
false (0) = should use proportionally sized canvas (uses width = 43*screenHeight)
canvasAdjustments: NA: not applicable => parameters- runAbsoluteSize was set to 'false'
0: parameters- runAbsoluteSize was set to 'true' and screen size was large enough
1: parameters- runAbsoluteSize was set to 'true' BUT screen size was too small and
adjustments had to be made
activeCanvasHeight_inmm: the width of the active canvas (by default: lightGray area) in mm
activeCanvasWidth_inmm: the height of the active canvas in mm
display.canvasHeight: the height of the active canvas in pixels
display.canvasWidth: the width of the active canvas in pixels
px_per_mm: the conversion factor to convert pixel data into mm-results for the current monitor
(Note: the higher resolution of the current monitor
the more pixels cover the same absolute screen distance)
This factor is needed if you want to convert pixel data into absolute mm data or the other way around
//////summary data/////
meanNumberCorrectSearches_practice: mean number of correct target searches per practice round (default setup run setsize = 3)
correct = the search for a target was conducted without between or within errors
//by set size//
meanNumberCorrectSearches_setsize1: mean number of correct target searches per round testing setsize1
correct = the search for a target was successful
and no between, within or timeout errors were made
count_TO_setsize1: the number of timed out (TO) rounds for setsize1 (if task was run without timeout this should be 0)
Note: within and between errors counts are only conducted for non-timed out rounds:
meanErrorCount_Within_setsize1: mean number of Within errors per non-timed out setsize1 rounds
meanErrorCount_Between_setsize1: mean number of Between errors per non-timed out setsize1 rounds
same for setsizes 2-10
___________________________________________________________________________________________________________________
EXPERIMENTAL SET-UP
___________________________________________________________________________________________________________________
////////////////////////////////////////////////////////////////////////
Default Setup
////////////////////////////////////////////////////////////////////////
The default setup of the Millisecond Box Task runs
(1) Intro Block: repeatable if necessary
(2) Practice Block: runs 2 practice rounds with 3 objects each
(3) Test Block: runs 6 rounds with
- 2 rounds for 4 objects
- 2 rounds for 6 objects
- 2 rounds for 8 objects (Note: the highest setsize the Millisecond Box Task can run is 10)
////////////////////////////////////////////
Absolute Canvas Sizing
////////////////////////////////////////////
By default, the script runs with an absolutely sized canvas using a frame to anchor the active canvas
on the current screen. The stimuli thus appear absolutely sized (aka are the same size) across screens.
The default active canvassize is based on ipad size.
See section Editable Parameters for relevant settings that can easily be adjusted
////////////////////////////////////////////
Screen Colors
////////////////////////////////////////////
The default screen color is lightblue, the default active canvas appears in lightGray,
and the active area used to place the boxes ('boxPlacementArea') appears in white.
The default text color is set to black.
See section Editable Parameters for relevant settings that can easily be adjusted
////////////////////////////////////////////
Box Placement Algorithm
////////////////////////////////////////////
This script randomly selects the position of the boxes in the dedicated 'boxPlacementArea'
ensuring that no overlap of boxes happens (at least it should not happen - if it does, values.boxPlacementViolation
will flag the data file).
The fewer boxes are placed onto the area, the greater the general distance btw. boxes to
avoid accidental clumps.
////////////////////////////////////////////
Object Selection
////////////////////////////////////////////
This script provides 42 objects which is enough to run the default setup without
object repetition (3+3+4+4+6+6+8+8 = 42). More objects can be
added under section Editable Stimuli.
The default setup of this script randomly selects the order of the objects.
////////////////////////////////////////////
Target Box Selection
////////////////////////////////////////////
The targetboxes are randomly (without replacement) assigned during each round.
There are three box types which are selected randomly without replacement
with repeats once all three box image types have run.
////////////////////////////////////////////
Timed Test
////////////////////////////////////////////
The default setup does not impose a time limit for the target searches.
Check section Editable Parameters for relevant parameters that allow to
impose a timeout for each search round and to present a timer.
////////////////////////////////////////////
Round Trial Sequence
////////////////////////////////////////////
Each round starts with a "next round" alert and a Start button that needs to be pressed
to initiate the next round.
Target1: the object for target1 as well as the targetbox is randomly determined.
The boxes are presented in the BoxPlacementArea and the targetobject is shown under
the BoxPlacementArea. If no response occurs within 5s, a red reminder appears next
to the target object.
If an empty box is opened, the empty box is revealed for 1000ms (editable parameter).
If the target box is opened, the target object as well as a 'next' button is presented.
Once pressed, the next target is presented until all targets have been found.
If the search is timed out (only happens if parameter settings are changed to run a timed search),
the round ends and a message is flashed onto the screen.
___________________________________________________________________________________________________________________
STIMULI
___________________________________________________________________________________________________________________
provided by Millisecond Software - can be edited under section 'Editable Stimuli'
////Images:
All object and box stimuli downloaded from: https://pixabay.com/
under the Pixabay license of "Free for commercial use - No attribution required"
The script provides 42 object stimuli to run the default setup without object
repetition.
////Sounds:
success.wav: https://freesound.org/people/grunz/sounds/109662/ licensed under the Attribution 3.0 License
and edited in Audacity
failure.wav: created in Audacity
___________________________________________________________________________________________________________________
INSTRUCTIONS
___________________________________________________________________________________________________________________
provided by Millisecond Software - can be edited under section 'Editable Instructions'
The instructions use some of the suggested instructions by Kessels & Postma (2018)
___________________________________________________________________________________________________________________
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:
