User Manual: Inquisit Permuted Rules Operation Task (PRO)


___________________________________________________________________________________________________________________	

								*Permuted Rules Operation Task*
								(Test Script - use the same groupnumber as with the practice script)
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 02-03-2021
last updated: 09-11-2023 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 09-11-2023 Millisecond Softwaretware

Millisecond Software thanks Dr. Todd Braver and the Braver Lab for collaboration on this script!

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	

This script implements the Permuted Rules Operation Task by Cole et al (2018).
The Permuted Rules Operation Task is used to investigate whether 
goal-relevant information that is learned for a 'rapid instructed task learning' (RITL) type task
is actively maintained (from training) in preparation for anticipated high control 
tasks later on.

The implemented procedure is based on the original e-prime script (generously shared by the Braver Lab)
which intermixes Novel and Practiced trials, and uses self-paced preparation 
(see Experiment 3 in Cole et al, 2018). 

This Inquisit script implements the TEST session only.


References

task:
Cole, M.W., Patrick, L.M., Meiran, N., & Braver, T.S. (2018).
A role for proactive control in rapid instructed task learning,
Acta Psychologica, 184, 20-30,
https://doi.org/10.1016/j.actpsy.2017.06.004.

stimuli
Cole, M. W., Bagic, A., Kass, R., & Schneider, W. (2010). 
Prefrontal dynamics underlying
rapid instructed task learning reverse with practice. 
Journal of Neuroscience, 30(42), 14245–14254. 
http://dx.doi.org/10.1523/JNEUROSCI.1662-10.2010.

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	

The basic task of the Permuted Rules Operation Task is as follows:
Participants are presented with two words (e.g. "computer" and "bunny") and have to respond to the 2 words 
as fast as they can according to three rules presented to them beforehand.

The three rules come from the following three rule dimensions (each with four rules => 12 rules total):

Sensory Semantic Rules: question to ask oneself for each of the two words
a) "is it GREEN?" 
b) "is it SOFT?"
c) "is it SWEET?"
d) "is it LOUD?"

Logical Rules: evaluate the words according to the following rules
a) "is your answer the SAME for both words? Then press the current yes-key (otherwise press the current no-key)"
b) "is your answer DIFFERENT for both words? Then press the current yes-key (otherwise press the current no-key)"
c) "is your answer true for the SECOND word? Then press the current yes-key (otherwise press the current no-key)"
d) "is your answer false for the SECOND word? Then press the current yes-key (otherwise press the current no-key)"

Motor Response: the possible motor responses (defines the yes-key and the no-key; Note: only the yes-key is explicitly provided)
a) yes-key: respond with left index finger (F); no-key: respond with left middle finger (D)
b) yes-key: respond with left middle finger (D); no-key: respond with left index finger (F)
c) yes-key: respond with right index finger (J); no-key: respond with right middle finger (K)
D) yes-key: respond with right middle finger (K); no-key: respond with right index finger (J)

Example: the rules provided to evaluate the pair "computer/bunny" are:
SOFT 
left-index finger
SAME

=> correct response is to press the left-MIDDLE finger (the implicit no-key) since the answer
to both probe words is, in fact, not the same: computer = not soft, bunny = soft


There are 64 (4x4x4) total rule-combinations. 
In a previous practice session (permutedrulesoperationtask_practice.iqjs) participants were assigned
4 of these to practice (assignment is done by groupnumber). 
The assigned 4 rule combinations practiced each of the 12 rules exactly one time  
(so participants get familiar with each of the 12 rules).

This script briefly 'reminds' participants of the practiced rule combinations*.
Afterwards participants work through several blocks in which practiced and novel rule combinations are tested
within a mixed format.

*Note: both the practice and test script have to be run with the same groupnumber!
___________________________________________________________________________________________________________________	
DURATION 
___________________________________________________________________________________________________________________	
the default set-up of the script takes appr. 1.5 hours.

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

(1) Raw data file: 'permutedrulesoperationtask_test_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. 
										
practiceCombinationA:			the assigned index of practice Combination A  (refers to index (=position) in: list.rulecombinations)
practiceCombinationB:			the assigned index of practice Combination B  (refers to index (=position) in: list.rulecombinations) 
practiceCombinationC:			the assigned index of practice Combination C  (refers to index (=position) in: list.rulecombinations) 
practiceCombinationD:			the assigned index of practice Combination D  (refers to index (=position) in: list.rulecombinations)

phase:							"demo" vs. "practice"

blockCounter:					a counter that tracks the number of blocks run per phase
								demo: 8 blocks run (each block runs 4 trials)
								practice: 16 blocks run (each block runs 72 trials)

trialCounter:					a counter that tracks the number of trials run
								Note: for phase 'test' the counter does NOT reset after each block
									
trialCounterPerBlock:			a counter that tracks the number of trials run per block	
									
trialType:						1 = practiced rule combination; 2 = novel rule combination									

selectedCombination:			stores the currently selected practice rule combination index (out of 64 possible)

probeType:						the selected probe type: 1-4 (see values.probe1SemAnswer/values.probe2SemAnswer)
								1 = yes-yes
								2 = no-no
								3 = yes-no
								4 = no-yes
 
probe1Stim: 					the selected stimulus for the first probe
probe1Num: 						the itemnumber of the selected first stimulus (on its respective item list -> depends on values.sensorySemanticCue)
											NOTE: the itemnumbers are 0-based
probe2Stim: 					the selected stimulus for the second probe 
probe2Num: 						the itemnumber of the selected second stimulus (on its respective item list -> depends on values.sensorySemanticCue)
											NOTE: the itemnumbers are 0-based
											
sensorySemanticCue:				SWEET, LOUD, GREEN, SOFT 
logicalDecisionCue:				SAME, DIFFERENT, second Stim, not second Stim 
motorResponseCue:				left middle, left index, right index, right middle 
yesResponseKey:				the assigned key for the 'yes' response (for the currently displayed probes)
noResponseKey:					the assigned key for the 'no' response (for the currently displayed probes)

probe1SemAnswer:				'yes' or 'no' 
probe2SemAnswer:				'yes' or 'no' 

iti:							the variable intertrial duration (in ms) 

correctResponseKey:				the response button assigned to the correct response for the currently presented probes

//custom DVs:
resp:							stores the pressed response button (NR = no response)
answeredYes:					1 = participant pressed the assigned yes-key; 0 = participant did not press the assigned yes-key (also applies to NR)
wrongHand:						1 = participant responded with keys from the wrong hand; 0 = participant did not respond with keys from the wrong hand (also applies to NR) 
answerCorrect:					1 = the response was correct; 0 = the response was incorrect (also applies to NR)
rt:								the response time (in ms); measured from onset of probes (NR = no response)
prepRT:							the response time (in ms) during self-paced instruction trials during the test (Note: timeout response = 10s)

list.accPerBlock.mean:			the current proportionCorrect responses in the given practice block (Note: not meaningful for demo blocks)										


feedback:						1 = correct
								2 = incorrect
								3 = wrong hand 
								4 = correct but too slow
								5 = no response
									
respRecogPracticedRules:		Y(es) vs. N(o)	 
rtRecogPracticedRules:			response time (in ms)
																				
//built-in DVs:										
response:						the participant's response (scancode of response buttons)
correct:						accuracy of response: 1 = correct response; 0 = otherwise
latency: 						the response latency (in ms)


(2) Summary data file: 'permutedrulesoperationtask_test_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)
									
practiceCombinationA:			the assigned index of practice Combination A  (refers to index (=position) in: list.rulecombinations)
practiceCombinationB:			the assigned index of practice Combination B  (refers to index (=position) in: list.rulecombinations) 
practiceCombinationC:			the assigned index of practice Combination C  (refers to index (=position) in: list.rulecombinations) 
practiceCombinationD:			the assigned index of practice Combination D  (refers to index (=position) in: list.rulecombinations)

propCorrectOverall:			proportionCorrect responses across all test blocks and trials
countNROverall:				the number of no responses across all test blocks and trials
meanCorrRTOverall:				the mean response time (in ms) of correct responses across all test blocks and trials

propCorrectOverallP:			proportionCorrect responses for Practiced rule combinations across all test blocks 
countNROverallP:				the number of no responses for Practiced rule combinations across all test blocks   
meanCorrRTOverallP:			the mean response time (in ms) of correct responses for Practiced rule combinations across all test blocks 

propCorrectOverallN:			proportionCorrect responses for Novel rule combinations across all test blocks 
countNROverallN:				the number of no responses for Novel rule combinations across all test blocks   
meanCorrRTOverallN:			the mean response time (in ms) of correct responses for Novel rule combinations across all test blocks 

meanPrepRTOverall:				the mean response time (in ms) for the rule cue presentation trials across Practice and Novel pairs
meanPrepRTOverallP:			the mean response time (in ms) for the rule cue presentation trials across Practice pairs
meanPrepRTOverallN:			the mean response time (in ms) for the rule cue presentation trials across Novel pairs
								(Note: timeout responses (10s) are included)

//per test block:

acc1P:						proportionCorrect responses in first test block for Practiced Rule Combinations
nr1P:							number of no responses in first test block  for Practiced Rule Combinations
corrRT1P:						the mean response time (in ms) of correct responses in first test block	for Practiced Rule Combinations 

acc1N:						proportionCorrect responses in first test block for Novel Rule Combinations
nr1N:							number of no responses in first test block  for Novel Rule Combinations
corrRT1N:						the mean response time (in ms) of correct responses in first test block	for Novel Rule Combinations
							
(the same for all 10 test blocks)							

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

This script counterbalances the assigment of the 4 practice rule combinations by groupnumber assignment (16 groups).
Each groupnumber runs a unique combination of rules so that each of the 12 rules is practiced exactly one time.
The practice rule combinations are assigned under the 'expt'- elements (see section EXPERIMENT):
values.practiceCombinationA, values.practiceCombinationB, values.practiceCombinationC, values.practiceCombinationD.
NOTE: the groupnumber should be the same as used during practice!


(1) Practice Reminder Phase: 4 blocks of 2 trials each (= 8 trials total)
- each of the four practice rules are run with 2 trials
- Feedback is provided after each trial (if response is incorrect, the same probe combination is repeated)
- trial sequence is completely self-paced (no timing restrictions imposed)
- participants are asked whether the rules were the same as the ones practiced

(2) Mixed Test Phase: 10 blocks of 36 trials each

- per block: half the trials are PRACTICED trials; half the trials are NOVEL trials

-PRACTICED trials:
- the next practiced rule is selected randomly WITHOUT replacement from the 4 possible practice combinations
- the selected combination canNOT repeat the last presented PRACTICED rule

-NOVEL trials:.
- the next practiced rule is selected randomly WITHOUT replacement from the 60* possible novel combinations
- the selected combination canNOT repeat the last presented NOVEL rule
* There are 64 (4x4x4) total rule-combinations of which 4 are the practiced rule combinations => 60 novel ones

=> across 10 blocks:
-180 PRACTICED trials: each of the PRACTICED rules is presented 45 times
-180 NOVEL trials: each of the NOVEL rules is presented 3 times


TEST TRIALS:
- each test trial randomly selects its probes from the assigned stimuli lists (item.probeStimLoud/item.probeStimSoft/item.probeStimColor/item.probeStimSweet)
- a break is provided every 2 blocks
- block accuracy feedback is provided

Trial Sequence: (note: durations are editable parameters)
-> trial rules presented in black frame, self-paced by spacebar press
-> probes presented in blue frame (1500ms) with response window (2000ms)
-> fixation cross for 1000ms (feedback delay period)
-> accuracy feedback for 1000ms
-> fixation cross during iti (variable duration btw. 1000 and 2000ms)

___________________________________________________________________________________________________________________
STIMULI
___________________________________________________________________________________________________________________

Stimuli used (see Cole et al., 2010): 180 concrete semantic nouns, selected based on their
clear selectivity into the tested semantic categories.

The stimuli were selected during a previous norming study, such that each word can
be used by only 2 rules (so each word appears twice across 
item.probeStimLoud/item.probeStimSoft/item.probeStimColor/item.probeStimSweet)
This was to ensure that each word is not 100% associated with a particular semantic category 
while at the same time avoiding ambiguous semantic situations, 
such as whether an apple is green (sometimes it is, sometimes it is not).

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
provided by original e-prime script - 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.

The parameters you can change are: