User Manual: Inquisit Magic Cups Task


___________________________________________________________________________________________________________________	

								Magic Cups Task
								(German instructions)
___________________________________________________________________________________________________________________	


Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 01-24-2023
last updated:  09-30-2024 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 09-30-2024 Millisecond Software

German instructions provided by K. Borchert for Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________
This script runs Millisecond Software's implementation of the Magic Cups Task (Rahman et al, 2021), 
a 'Theory of Mind' (ToM) paradigm to study people's ability to infer another person's thoughts and beliefs.

This Inquisit script is based on the publicly available eprime script by the original authors.
Any intentional alterations to the original procedure (e.g. adding an optional instruction block) are explained
below.

The original eprime script can be accessed at: https://osf.io/wy5cm/ (last checked: 26 Jan 2023)
Additional information is located at: https://osf.io/br9v8/ (last checked: 26 Jan 2023)
The project is licensed under: CC-By Attribution 4.0 International 

DISCLAIMER:
While we try to stay as faithful as possible to the original eprime script,
the Inquisit implementation of the Magic Cups Task may still differ from it.


*Reference*											
Rahman, F., Kessler, K., Apperly, I. A., Hansen, P. C., Javed, S., Holland, C. A., & Hartwright, C. E. (2021). 
Sources of Cognitive Conflict and Their Relevance to Theory-of-Mind Proficiency in Healthy Aging: 
A Preregistered Study. Psychological Science, 32(12), 1918–1936. 
https://doi.org/10.1177/09567976211017870

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________

A ball is hidden in one of three cups. Participants see three events (in random order):
1. some information about where the ball is (a green ball is presented in the target cup's location)
OR isn't (a green X is presented in a cup's location) -> REALITY INFORMATION
2. the GUESS/BELIEF of a blue player
3. the GUESS/BELIEF of a red player

At the end of each trial, participants get one of three probe questions:
1. Where do YOU think the ball is? (reality/attention check questions) (FILLER TRIALS)
2. Where does blue player think the ball is? (TARGET TRIALS)
3. Where does red player think the ball is? (TARGET TRIALS)

For each trial, participants have to keep track of the 'reality' information and the
information they receive about each player's belief and be ready to switch perspective
depending on the probe question.

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

___________________________________________________________________________________________________________________	
DATA OUTPUT DICTIONARY
___________________________________________________________________________________________________________________
The fields in the data files are:

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

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. 
																								
blockExpt:					p1 (practice), 1-4 (testblock1-4)
testBlockCounter: 			tracks the number of testblocks run
trialCounter:				tracks the number trials run across the testblocks (resets after practice)

itemNumber:					the currently selected itemnumber
stimulusItem:				stores the first item presented in the current trial

//the following (IV) variables are taken from the eprime script//
event3:						the image presented as event3 (scene1) 
event5:						the image presented as event5 (scene2) 
event7:						the image presented as event7 (scene3) 
event9:						the image presented as event9 (probe) 

trialID:					the assigned trial ID
variantID:					the assigned variant ID of the current trial combination (out of 48 possible)

trialType:					T = true trial (agent is one of the two 'players'), 
							F = filler/catch trial (agent is participant)

eventCode2:					the event code (settings of the three main IVs), see settings of realityKnowledge, OOC, SIC

realityKnowledge:			Y(es) = participant knows exactly where ball is located (sees a green ball)
							N(o) = participant does not know exactly where the ball is located (sees a green X)
							
ooc:						Other-other Conflict:
							Y(es), there is a conflict = the two player agents make different predictions (OOC incongruent)
							N(o), there is no conflict = the two player agents make the same prediction (OOC congruent)

soc:						Self-other Conflict
							Y(es), there is a conflict = participant knowledge and target agent are in conflict -> participant's response requires a selection that is incongruent with reality (SOC incongruent)
							N(o), there is no conflict  = participant knowledge and target agent are in agreement (SOC congruent)
								Note from Millisecond: for Filler/Catch trials the categorization done by the
								eprime script seems 'artifically forced' (probably done for balancing)
								as there cannot really be a conflict btw. participant
								and self-agent (participant) knowledge, yet some Filler trials code the SOC as 'Y'.

order:						the eprime assigned order ID for the given trial (depends on occurence of reality scene)
							Blue/Red Agent -> Red/Blue Agent -> Reality: 1 (reality is scene3)
							Blue/Red Agent -> Reality -> Red/Blue Agent: 2 (reality is scene2)						
							Reality -> Blue/Red Agent -> Red/Blue Agent: 3 (reality is scene1)

agentReferent:				Interpretation Millisecond: likely the 'guess'/knowledge of the target agent where the ball is
							(though coding of filler trials - where participant is target agent- does not always seem to coincide
							with the numbers)
							
participantReferent:		Interpretation Millisecond: likely refers to the knowledge participant has about one of the three cups
							1 = participant knows something about cup1 (ball either is under cup1 or is NOT under cup1)
							2 = participant knows something about cup2
							3 = participant knows something about cup3
							
correctResponse: 			the correct response
							double digits refer to filler trials in which there are two possibly correct answers
///////////////
//////DVs//////							
///////////////

response: 					the scancode of the pressed response key (Note that scancodes look confusing for number keys)
							scancode2 -> key1 was pressed
							scancode3 -> key2 was pressed
							scancode4 -> key3 was pressed

responseText: 				converts the scancode into the label of the pressed key
rsp:						Inquisit custom response variable
correct:					correctness of response (1 = correct, 0 = error, including omissions)
latency:					response latency (in ms); measured from: onset of probe (for probe trials)


(2) Summary data file: 'magiccubstask_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)	
							
Note: summary variables provided by Millisecond Software. They are not part of the
original eprime script.							

////////////////////////////////////////
///////////filler trials////////////////
filler trial = participant is agent
////////////////////////////////////////
propCorrectFiller:			proportion correct responses given in filler trials across all test blocks
meanCorrRTFiller:			mean correct response time (in ms) of responses in filler trials across all test blocks

////////////////////////////////////////
///////////target trials////////////////
target trial = players are agent
important: The following variables ONLY refer to target trials

Explanation of nan: nan stands for 'not a number'
you may see this result if there is not enough data in a condition to compute the 
requested variable (e.g if there are no correct responses in a condition, you will see 
nan for corrRT in that particular condition)
////////////////////////////////////////
propCorrect:			proportion correct responses given across all test blocks
meanCorrRT:				mean correct response time (in ms) of responses across all test blocks

/////proportion corrects for each of the 8 experimental conditions:

koR: knowledge of reality. 
Level 0 = participants has NO knowledge of reality (participant saw a green X) 
Level 1 = explicit knowledge of reality (participant saw a green dot)

ooc: Other-Other Conflict
Level 0 = No other-other conflict (congruent) - both players agree on the same response
Level 1 = other-other conflict (incongruent) - players differ in their responses

soc: Self-Other Conflict 
Level 0 = No self-other conflict (congruent) - agent player's response is NOT in conflict with what participant knows
Level 1 = self-other conflict (incongruent) - agent player's response IS in conflict with what participant knows

propCorrectKoR0OOC0SOC0:		proportion correct responses in condition KoR0_OOC0_SOC0 (NNN)
propCorrectKoR0OOC0SOC1:		proportion correct responses in condition KoR0_OOC0_SOC1 (NNY)
propCorrectKoR0OOC1SOC0:		proportion correct responses in condition KoR0_OOC1_SOC0 (NYN)
propCorrectKoR0OOC1SOC1:		proportion correct responses in condition KoR0_OOC1_SOC1 (NYY)
propCorrectKoR1OOC0SOC0:		proportion correct responses in condition KoR1_OOC0_SOC0 (YNN)
propCorrectKoR1OOC0SOC1:		proportion correct responses in condition KoR1_OOC0_SOC1 (YNY)
propCorrectKoR1OOC1SOC0:		proportion correct responses in condition KoR1_OOC1_SOC0 (YYN)
propCorrectKoR1OOC1SOC1:		proportion correct responses in condition KoR1_OOC1_SOC1 (YYY)

//untrimmed correct response times for each of the 8 experimental conditions + their standard deviations
meanCorrRTKoR0OOC0SOC0:		mean correct UNTRIMMED response time (in ms) in condition KoR0_OOC0_SOC0 (NNN)
sdKoR0OOC0SOC0:				standard deviation of response times (in ms) in condition KoR0_OOC0_SOC0 (NNN)

meanCorrRTKoR0OOC0SOC1:		mean correct UNTRIMMED response time (in ms) in condition KoR0_OOC0_SOC1 (NNY)
meanCorrRTKoR0OOC1SOC0:		mean correct UNTRIMMED response time (in ms) in condition KoR0_OOC1_SOC0 (NYN)
meanCorrRTKoR0OOC1SOC1:		mean correct UNTRIMMED response time (in ms) in condition KoR0_OOC1_SOC1 (NYY)
meanCorrRTKoR1OOC0SOC0:		mean correct UNTRIMMED response time (in ms) in condition KoR1_OOC0_SOC0 (YNN)
meanCorrRTKoR1OOC0SOC1:		mean correct UNTRIMMED response time (in ms) in condition KoR1_OOC0_SOC1 (YNY)
meanCorrRTKoR1OOC1SOC0:		mean correct UNTRIMMED response time (in ms) in condition KoR1_OOC1_SOC0 (YYN)
meanCorrRTKoR1OOC1SOC1:		mean correct UNTRIMMED response time (in ms) in condition KoR1_OOC1_SOC1 (YYY)

//trimmed correct response times for each of the 8 experimental conditions:
numberRemovedRTDataPointsOverall: the number of removed RT data points across all target trials

trMeanCorrRTKoR0OOC0SOC0:		mean correct TRIMMED response time (in ms) in condition KoR0_OOC0_SOC0 (NNN)
trMeanCorrRTKoR0OOC0SOC1:		mean correct TRIMMED response time (in ms) in condition KoR0_OOC0_SOC1 (NNY)
trMeanCorrRTKoR0OOC1SOC0:		mean correct TRIMMED response time (in ms) in condition KoR0_OOC1_SOC0 (NYN)
trMeanCorrRTKoR0OOC1SOC1:		mean correct TRIMMED response time (in ms) in condition KoR0_OOC1_SOC1 (NYY)
trMeanCorrRTKoR1OOC0SOC0:		mean correct TRIMMED response time (in ms) in condition KoR1_OOC0_SOC0 (YNN)
trMeanCorrRTKoR1OOC0SOC1:		mean correct TRIMMED response time (in ms) in condition KoR1_OOC0_SOC1 (YNY)
trMeanCorrRTKoR1OOC1SOC0:		mean correct TRIMMED response time (in ms) in condition KoR1_OOC1_SOC0 (YYN)
trMeanCorrRTKoR1OOC1SOC1:		mean correct TRIMMED response time (in ms) in condition KoR1_OOC1_SOC1 (YYY)

////////////////////////////////////////////////////////////////////////////////////
Response Times Trimming: used algorithm in this script

steps: done for each of the 8 conditions 
1) calculate the mean and SD (standard deviation) for each condition separately
2) trimm RTS from each condition so that:
mean - 2*SD <= RT <= mean + 2*SD 
(2 = number of standarddeviations away from the mean)

////////////////////////////////////////////////////////////////////////////////////
							
___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	

/////////////////////////
Design
/////////////////////////

2x2x2 (3 factor) repeated measures design => 8 different experimental conditions
The 3 factors manipulate 3 different 'conflicts'

•	Factor 1: Knowledge of Reality – manipulates whether the participant has definite knowledge 
about the ball's location
Level1: NO/low conflict- does not exactly know where the ball is (is shown the green X)
Level2: YES/high conflict - does exactly know where the ball is (is shown the green ball)

•	Factor 2: Other-Other Conflict (OOC) – manipulates whether the two Players beliefs about the 
location of the ball are the same (congruent) or different (incongruent) from one another’s.
Level 1: NO/low conflict - there is no conflict -> the players believe the same (congruent)
Level 2: YES/high conflict - there is conflict -> the players make different guesses (incongruent)

•	Factor 3: Self-Other Conflict (SOC) – manipulates whether the participant’s knowledge of 
reality is the same (congruent) or different (incongruent) from the target agent
target agent = perspective player has to take to answer the probe question
Level 1: NO/low conflict- target agent's and participant's knowledge of reality is the same (congruent)
Level 2: YES/high conflict - target agent and participant's knowledge of reality is NOT the same (incongruent)

/////////////////////////
Procedure
/////////////////////////

(1) Optional Instruction Block:
This script provides an optional instruction block which is NOT part of the original
eprime script. To turn off/on the instruction block, check section Editable parameters.
By default, the script runs with the instruction block.

(2) Practice Block:
12 practice trials with audio error and correct feedback

(3) Test: 4 blocks 
- 54 trials per block (18 filler trials, 36 target trials) 
- with rest trial at the end of each block (except block4)
- the trial make up of each block is fixed (see eprime script) BUT the order in which these trials are called
is randomized for each participant.

Across all 4 blocks, the script runs:
Filler Trials: 72 (9 trials per experimental condition)
Test Trials: 144 (18 trials per experimental condition)

Trial Sequence: 10 events
-> Shuffle Cups (1000ms) -> Blank screen (500ms)
-> scene1 (1000ms)* -> Blank screen (500ms)
-> scene2 (1000ms)* -> Blank screen (500ms)
-> scene3 (1000ms)* -> Blank screen (500ms)
-> Probe (1000ms with 3000ms responsewindow) -> ISI (presents a small black dot) for 3000ms

Note: all responsetimes can be edited under section Editable Parameters.
___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________

All images downloaded from: 
https://osf.io/wy5cm/ (last checked: 26 Jan 2023)

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________

The instructions used in the optional intro block are provided by Millisecond Software.
They can be edited under section Editable Instructions.
The remaining instructions were downloaded with the original eprime script.
___________________________________________________________________________________________________________________	
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: