User Manual: Inquisit Two-Step Decision Task


___________________________________________________________________________________________________________________	

									*Two-Step Decision Task ('Aliens')*
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
last updated:  10-26-2023 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 10-26-2023 Millisecond Software

Millisecond Software thanks Dr. Nathaniel Daw for permission to publish this script
in the Millisecond Software library!

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	

This script implements a batch script for the Two-step Decision task ('Alien Task') by Decker et al (2016).
The Two-step Decision task is a child-friendly task to study decision making in children using
a two-stage reinforcement learning task.

This batch script controls the assignment of 4 different payoff schedules by groupnumber assignment.


Reference:
Decker JH, Otto AR, Daw ND, Hartley CA. From Creatures of Habit to Goal-Directed Learners: 
Tracking the Developmental Emergence of Model-Based Reinforcement Learning. 
Psychol Sci. 2016 Jun;27(6):848-58. doi: 10.1177/0956797616639301. 
Epub 2016 Apr 15. PMID: 27084852; PMCID: PMC4899156.

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	

Decision Step 1:
Participants are asked to select btw two spaceships that travel to two planets with different probabilities
(e.g. spaceship1 travels to planet1 with p = 0.7 and to planet2 with p = 0.3).

Decision Step 2:
On each planet, they encounter two aliens that work in mines. Aliens retrieve treasure with 'drifting'
probabilities. Participants are asked to select one of the aliens. If the selected alien happens to retrieve
treasure from the mine, it shares it with the participant.

The goal is to collect as much treasure as possible.

___________________________________________________________________________________________________________________
TASK DURATION	
___________________________________________________________________________________________________________________
The default duration of this task is app. 25 minutes (for 200 test trials)



___________________________________________________________________________________________________________________	

									*Two-Step Decision Task ('Aliens')*
									- Touch (mouse) Version-
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
last updated:  11-18-2024 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 11-18-2024 Millisecond Software

Millisecond Software thanks Dr. Nathaniel Daw for permission to publish this script
in the Millisecond Software library!

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	

This script implements the Two-step Decision task ('Alien Task') by Decker et al (2016).
The Two-step Decision task is a child-friendly task to study probabilistic decision making in children using
a two-stage reinforcement learning task.
Original Age Group: 8-12 years.

The Inquisit implementation uses touch (mouse) input.

Reference:
Decker JH, Otto AR, Daw ND, Hartley CA. From Creatures of Habit to Goal-Directed Learners: 
Tracking the Developmental Emergence of Model-Based Reinforcement Learning. 
Psychol Sci. 2016 Jun;27(6):848-58. doi: 10.1177/0956797616639301. 
Epub 2016 Apr 15. PMID: 27084852; PMCID: PMC4899156.

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	

Decision Step 1:
Participants are asked to select btw two spaceships that travel to two planets with different probabilities
(e.g. spaceship1 travels to planet1 with p = 0.7 and to planet2 with p = 0.3).

Decision Step 2:
On each planet, they encounter two aliens that work in mines. Aliens retrieve treasure with 'drifting'
probabilities. Participants are asked to select one of the aliens. If the selected alien happens to retrieve
treasure from the mine, it shares it with the participant.

The goal is to collect as much treasure as possible.

___________________________________________________________________________________________________________________	
TASK DURATION
___________________________________________________________________________________________________________________

Practice/Training: ~10 minutes
Test (200 trials): ~15 minutes
_________________________________
Total:	~25 minutes

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

(1) Raw data file: 'twostepdecisiontaskRaw*.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. 
										
stimulusItem:						the presented stimuli in order of trial presentation
response:							the participant's response 								
										
latency: 							the response latency (in ms); measured from: onset of trial


//custom variables:
(parameter) payOff_Version			the current payOff version run (1-4)
									version 1/4 only run for up to 200 trials
									version 2/3 can run for up to 400 trials

countTrials:						counts the number of trials started

alien1payOff:						the payoff (win probability) for selecting alien1 (left alien on green/red planet) in this trial
alien2payOff:						the payoff (win probability) for selecting alien2 (right alien on green/red planet) in this trial 
alien3payOff:						the payoff (win probability) for selecting alien3 (left alien on yellow/purple planet) in this trial 
alien4payOff:						the payoff (win probability) for selecting alien4 (right alien on yellow/purple planet) in this trial


selectedRocket:						1 = the left rocket was selected
									2 = the right rocket was selected
									(or empty if no rocket was selected)
									
rtRocket:							response time (in ms) of selecting a rocket (empty if no rocket was selected)
 
planet:								1 = red planet was assigned; (practice: green planet)
									2 = purple planet was assigned (practice: yellow planet)
									(or empty if no planet was selected)

selectedAlien:						1 = left alien on red planet was selected
									2 = right alien on red planet was selected
									3 = left alien on purple planet was selected
									4 = right alien on purple planet was selected
									
rtAlien:							response time (in ms) of selecting an alien (empty if no alien was selected)

winProbability:						the current win-probability (payoff) associated with the selected alien
loseProbability:					the current lose-probability associated with the selected alien 

treasure:							1 = treasure is won 
									2 = NO treasure is won 

//summary variables (across trials):
rocket1SelectionCount:		counts the number of times participant selected rocket1 (left rocket) 
rocket2SelectionCount:		counts the number of times participant selected rocket2 (the leftright rocket)

alien1SelectionCount:		counts the number of times participant selected alien1 (left alien on red planet) 
alien2SelectionCount:		counts the number of times participant selected alien2 (right alien on red planet)  
alien3SelectionCount:		counts the number of times participant selected alien3 (left alien on purple planet)  
alien4SelectionCount:		counts the number of times participant selected alien4 (left alien on purple planet) 

countTreasure:				counts the number of treasures won
 
treasureCountAlien1:		counts the number of treasures won from alien1 (left alien on red planet)   
treasureCountAlien2:		counts the number of treasures won from alien2 (right alien on red planet)  
treasureCountAlien3:		counts the number of treasures won from alien3 (left alien on purple planet)  
treasureCountAlien4:		counts the number of treasures won from alien4 (right alien on purple planet) 
									
									
(2) Summary data file: 'twostepdecisiontask_summary*.iqdat' (a separate file for each participant)*

inquisit.version:					the 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)
									
(parameters) payOff_Version			the current payOff version run (1-4)
									version 1/4 only run for up to 200 trials
									version 2/3 can run for up to 400 trials									
																		
rocket1SelectionCount:		counts the number of times participant selected rocket1 (left rocket) 
rocket2SelectionCount:		counts the number of times participant selected rocket2 (the leftright rocket)

alien1SelectionCount:		counts the number of times participant selected alien1 (left alien on red planet) 
alien2SelectionCount:		counts the number of times participant selected alien2 (right alien on red planet)  
alien3SelectionCount:		counts the number of times participant selected alien3 (left alien on purple planet)  
alien4SelectionCount:		counts the number of times participant selected alien4 (left alien on purple planet)
 
countTreasure:				counts the number of treasures won 

treasureCountAlien1:		counts the number of treasures won from alien1 (left alien on red planet)   
treasureCountAlien2:		counts the number of treasures won from alien2 (right alien on red planet)  
treasureCountAlien3:		counts the number of treasures won from alien3 (left alien on purple planet)  
treasureCountAlien4:		counts the number of treasures won from alien4 (right alien on purple planet) 

propRocketSelections:		proportion of trials (to total number) that a rocket was selected
countRocketSelections:		the total number of rocket selections made 
countNoRocketSelections:	the number of times no rocket was selected 
meanRocketSelectionRT:		the mean response time (in ms) of selecting a rocket (when a rocket was selected)

propAlienSelections:				proportion of trials (to number of alien selection trials) that an alien was selected
propAlienSelectionsTotalTrials:	proportion of trials (to totalTrials) that an alien was selected
countAlienSelections:				the total number of alien selections made 
countNoAlienSelections:			the number of times no alien was selected 
meanAlienSelectionRT:				the mean response time (in ms) of selecting an alien (when an alien was selected)
									
							
								

___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	

(1) Training
- selecting an alien
- retrieving treasure (or not) after selecting an alien (with a certain win probability)
- choosing btw. two aliens (one with a higher win probability) and retrieving (or not) treasures

(2) Practice (of full game; with green/yellow planets): 20 trials (editable parameter)
a. Rocket Selection (max selection time: 3s)
rocket1 (left) vs. rocket2 (right)
Note: by default:
rocket1 flies to the green planet with p=0.7 and to the yellow planet with p=0.3 (editable parameters)
rocket2 flies to the green planet with p=0.3 and to the yellow planet with p=0.7 (editable parameters)

b. Alien Selection (max. selection time: 3s)
green Planet: alien1 (left) vs. alien2 (right)
yellow Planet: alien3 (left) vs. alien4 (right)

Note:
The payoff probabilities associated with each alien for each trial are currently randomly pre-generated
using a random start payoff probability (btw. 0.25 and 0.75) which is 'drifted' for each subsequent trial
by: newpayoff = previouspayoff + randgaussian(0, 1)* dsigma (with drift speed dsigma = 0.025)
(constraint: payoffs are always btw. 0.25 <= payoff <= 0.75)

c. Treasure Feedback

(3) Test (with red/purple planets): 200 trials (editable parameter BUT: current payoff probability are only available for 201 trials)
a. Rocket Selection (max selection time: 3s)
rocket1 (left) vs. rocket2 (right)
Note: by default:
rocket1 flies to the red planet with p=0.7 and to the purple planet with p=0.3 (editable parameters)
rocket2 flies to the red planet with p=0.3 and to the purple planet with p=0.7 (editable parameters)

b. Alien Selection (max. selection time: 3s)
green Planet: alien1 (left) vs. alien2 (right)
yellow Planet: alien3 (left) vs. alien4 (right)

Note:
The payoff probabilities associated with each alien for each trial are pregenerated.
There are 4 different payoff-probability versions to select from: see parameters.payOff_Version

The algorithm used to generate these "drifted" payoff probabilities is as follows:
- generate a random start probability: 0.25 <= p <= 0.75
- for 200 subsequent trials generate: 
newpayoff = previouspayoff + randgaussian(0, 1)* dsigma (with drift speed dsigma = 0.025)
(constraint: payoffs are always btw. 0.25 <= payoff <= 0.75)

c. Treasure Feedback

(Note: all animations run for 1s - hardcoded; cannot be changed easily)

___________________________________________________________________________________________________________________
STIMULI
___________________________________________________________________________________________________________________
based on original mathlab script for the Alien Game

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
based on original mathlab script for the Alien Game

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


___________________________________________________________________________________________________________________	

									*Two-Step Decision Task ('Aliens')*
									- Touch (mouse) Version-
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
last updated:  11-18-2024 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 11-18-2024 Millisecond Software

Millisecond Software thanks Dr. Nathaniel Daw for permission to publish this script
in the Millisecond Software library!

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	

This script implements the Two-step Decision task ('Alien Task') by Decker et al (2016).
The Two-step Decision task is a child-friendly task to study probabilistic decision making in children using
a two-stage reinforcement learning task.
Original Age Group: 8-12 years.

The Inquisit implementation uses touch (mouse) input.

Reference:
Decker JH, Otto AR, Daw ND, Hartley CA. From Creatures of Habit to Goal-Directed Learners: 
Tracking the Developmental Emergence of Model-Based Reinforcement Learning. 
Psychol Sci. 2016 Jun;27(6):848-58. doi: 10.1177/0956797616639301. 
Epub 2016 Apr 15. PMID: 27084852; PMCID: PMC4899156.

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	

Decision Step 1:
Participants are asked to select btw two spaceships that travel to two planets with different probabilities
(e.g. spaceship1 travels to planet1 with p = 0.7 and to planet2 with p = 0.3).

Decision Step 2:
On each planet, they encounter two aliens that work in mines. Aliens retrieve treasure with 'drifting'
probabilities. Participants are asked to select one of the aliens. If the selected alien happens to retrieve
treasure from the mine, it shares it with the participant.

The goal is to collect as much treasure as possible.

___________________________________________________________________________________________________________________	
TASK DURATION
___________________________________________________________________________________________________________________

Practice/Training: ~10 minutes
Test (200 trials): ~15 minutes
_________________________________
Total:	~25 minutes

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

(1) Raw data file: 'twostepdecisiontaskRaw*.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. 
										
stimulusItem:						the presented stimuli in order of trial presentation
response:							the participant's response 								
										
latency: 							the response latency (in ms); measured from: onset of trial


//custom variables:
(parameter) payOff_Version			the current payOff version run (1-4)
									version 1/4 only run for up to 200 trials
									version 2/3 can run for up to 400 trials

countTrials:						counts the number of trials started

alien1payOff:						the payoff (win probability) for selecting alien1 (left alien on green/red planet) in this trial
alien2payOff:						the payoff (win probability) for selecting alien2 (right alien on green/red planet) in this trial 
alien3payOff:						the payoff (win probability) for selecting alien3 (left alien on yellow/purple planet) in this trial 
alien4payOff:						the payoff (win probability) for selecting alien4 (right alien on yellow/purple planet) in this trial


selectedRocket:						1 = the left rocket was selected
									2 = the right rocket was selected
									(or empty if no rocket was selected)
									
rtRocket:							response time (in ms) of selecting a rocket (empty if no rocket was selected)
 
planet:								1 = red planet was assigned; (practice: green planet)
									2 = purple planet was assigned (practice: yellow planet)
									(or empty if no planet was selected)

selectedAlien:						1 = left alien on red planet was selected
									2 = right alien on red planet was selected
									3 = left alien on purple planet was selected
									4 = right alien on purple planet was selected
									
rtAlien:							response time (in ms) of selecting an alien (empty if no alien was selected)

winProbability:						the current win-probability (payoff) associated with the selected alien
loseProbability:					the current lose-probability associated with the selected alien 

treasure:							1 = treasure is won 
									2 = NO treasure is won 

//summary variables (across trials):
rocket1SelectionCount:		counts the number of times participant selected rocket1 (left rocket) 
rocket2SelectionCount:		counts the number of times participant selected rocket2 (the leftright rocket)

alien1SelectionCount:		counts the number of times participant selected alien1 (left alien on red planet) 
alien2SelectionCount:		counts the number of times participant selected alien2 (right alien on red planet)  
alien3SelectionCount:		counts the number of times participant selected alien3 (left alien on purple planet)  
alien4SelectionCount:		counts the number of times participant selected alien4 (left alien on purple planet) 

countTreasure:				counts the number of treasures won
 
treasureCountAlien1:		counts the number of treasures won from alien1 (left alien on red planet)   
treasureCountAlien2:		counts the number of treasures won from alien2 (right alien on red planet)  
treasureCountAlien3:		counts the number of treasures won from alien3 (left alien on purple planet)  
treasureCountAlien4:		counts the number of treasures won from alien4 (right alien on purple planet) 
									
									
(2) Summary data file: 'twostepdecisiontask_summary*.iqdat' (a separate file for each participant)*

inquisit.version:					the 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)
									
(parameters) payOff_Version			the current payOff version run (1-4)
									version 1/4 only run for up to 200 trials
									version 2/3 can run for up to 400 trials									
																		
rocket1SelectionCount:		counts the number of times participant selected rocket1 (left rocket) 
rocket2SelectionCount:		counts the number of times participant selected rocket2 (the leftright rocket)

alien1SelectionCount:		counts the number of times participant selected alien1 (left alien on red planet) 
alien2SelectionCount:		counts the number of times participant selected alien2 (right alien on red planet)  
alien3SelectionCount:		counts the number of times participant selected alien3 (left alien on purple planet)  
alien4SelectionCount:		counts the number of times participant selected alien4 (left alien on purple planet)
 
countTreasure:				counts the number of treasures won 

treasureCountAlien1:		counts the number of treasures won from alien1 (left alien on red planet)   
treasureCountAlien2:		counts the number of treasures won from alien2 (right alien on red planet)  
treasureCountAlien3:		counts the number of treasures won from alien3 (left alien on purple planet)  
treasureCountAlien4:		counts the number of treasures won from alien4 (right alien on purple planet) 

propRocketSelections:		proportion of trials (to total number) that a rocket was selected
countRocketSelections:		the total number of rocket selections made 
countNoRocketSelections:	the number of times no rocket was selected 
meanRocketSelectionRT:		the mean response time (in ms) of selecting a rocket (when a rocket was selected)

propAlienSelections:				proportion of trials (to number of alien selection trials) that an alien was selected
propAlienSelectionsTotalTrials:	proportion of trials (to totalTrials) that an alien was selected
countAlienSelections:				the total number of alien selections made 
countNoAlienSelections:			the number of times no alien was selected 
meanAlienSelectionRT:				the mean response time (in ms) of selecting an alien (when an alien was selected)
									
							
								

___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	

(1) Training
- selecting an alien
- retrieving treasure (or not) after selecting an alien (with a certain win probability)
- choosing btw. two aliens (one with a higher win probability) and retrieving (or not) treasures

(2) Practice (of full game; with green/yellow planets): 20 trials (editable parameter)
a. Rocket Selection (max selection time: 3s)
rocket1 (left) vs. rocket2 (right)
Note: by default:
rocket1 flies to the green planet with p=0.7 and to the yellow planet with p=0.3 (editable parameters)
rocket2 flies to the green planet with p=0.3 and to the yellow planet with p=0.7 (editable parameters)

b. Alien Selection (max. selection time: 3s)
green Planet: alien1 (left) vs. alien2 (right)
yellow Planet: alien3 (left) vs. alien4 (right)

Note:
The payoff probabilities associated with each alien for each trial are currently randomly pre-generated
using a random start payoff probability (btw. 0.25 and 0.75) which is 'drifted' for each subsequent trial
by: newpayoff = previouspayoff + randgaussian(0, 1)* dsigma (with drift speed dsigma = 0.025)
(constraint: payoffs are always btw. 0.25 <= payoff <= 0.75)

c. Treasure Feedback

(3) Test (with red/purple planets): 200 trials (editable parameter BUT: current payoff probability are only available for 201 trials)
a. Rocket Selection (max selection time: 3s)
rocket1 (left) vs. rocket2 (right)
Note: by default:
rocket1 flies to the red planet with p=0.7 and to the purple planet with p=0.3 (editable parameters)
rocket2 flies to the red planet with p=0.3 and to the purple planet with p=0.7 (editable parameters)

b. Alien Selection (max. selection time: 3s)
green Planet: alien1 (left) vs. alien2 (right)
yellow Planet: alien3 (left) vs. alien4 (right)

Note:
The payoff probabilities associated with each alien for each trial are pregenerated.
There are 4 different payoff-probability versions to select from: see parameters.payOff_Version

The algorithm used to generate these "drifted" payoff probabilities is as follows:
- generate a random start probability: 0.25 <= p <= 0.75
- for 200 subsequent trials generate: 
newpayoff = previouspayoff + randgaussian(0, 1)* dsigma (with drift speed dsigma = 0.025)
(constraint: payoffs are always btw. 0.25 <= payoff <= 0.75)

c. Treasure Feedback

(Note: all animations run for 1s - hardcoded; cannot be changed easily)

___________________________________________________________________________________________________________________
STIMULI
___________________________________________________________________________________________________________________
based on original mathlab script for the Alien Game

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
based on original mathlab script for the Alien Game

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


___________________________________________________________________________________________________________________	

									*Two-Step Decision Task ('Aliens')*
									- Touch (mouse) Version-
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
last updated:  11-18-2024 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 11-18-2024 Millisecond Software

Millisecond Software thanks Dr. Nathaniel Daw for permission to publish this script
in the Millisecond Software library!

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	

This script implements the Two-step Decision task ('Alien Task') by Decker et al (2016).
The Two-step Decision task is a child-friendly task to study probabilistic decision making in children using
a two-stage reinforcement learning task.
Original Age Group: 8-12 years.

The Inquisit implementation uses touch (mouse) input.

Reference:
Decker JH, Otto AR, Daw ND, Hartley CA. From Creatures of Habit to Goal-Directed Learners: 
Tracking the Developmental Emergence of Model-Based Reinforcement Learning. 
Psychol Sci. 2016 Jun;27(6):848-58. doi: 10.1177/0956797616639301. 
Epub 2016 Apr 15. PMID: 27084852; PMCID: PMC4899156.

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	

Decision Step 1:
Participants are asked to select btw two spaceships that travel to two planets with different probabilities
(e.g. spaceship1 travels to planet1 with p = 0.7 and to planet2 with p = 0.3).

Decision Step 2:
On each planet, they encounter two aliens that work in mines. Aliens retrieve treasure with 'drifting'
probabilities. Participants are asked to select one of the aliens. If the selected alien happens to retrieve
treasure from the mine, it shares it with the participant.

The goal is to collect as much treasure as possible.

___________________________________________________________________________________________________________________	
TASK DURATION
___________________________________________________________________________________________________________________

Practice/Training: ~10 minutes
Test (200 trials): ~15 minutes
_________________________________
Total:	~25 minutes

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

(1) Raw data file: 'twostepdecisiontaskRaw*.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. 
										
stimulusItem:						the presented stimuli in order of trial presentation
response:							the participant's response 								
										
latency: 							the response latency (in ms); measured from: onset of trial


//custom variables:
(parameter) payOff_Version			the current payOff version run (1-4)
									version 1/4 only run for up to 200 trials
									version 2/3 can run for up to 400 trials

countTrials:						counts the number of trials started

alien1payOff:						the payoff (win probability) for selecting alien1 (left alien on green/red planet) in this trial
alien2payOff:						the payoff (win probability) for selecting alien2 (right alien on green/red planet) in this trial 
alien3payOff:						the payoff (win probability) for selecting alien3 (left alien on yellow/purple planet) in this trial 
alien4payOff:						the payoff (win probability) for selecting alien4 (right alien on yellow/purple planet) in this trial


selectedRocket:						1 = the left rocket was selected
									2 = the right rocket was selected
									(or empty if no rocket was selected)
									
rtRocket:							response time (in ms) of selecting a rocket (empty if no rocket was selected)
 
planet:								1 = red planet was assigned; (practice: green planet)
									2 = purple planet was assigned (practice: yellow planet)
									(or empty if no planet was selected)

selectedAlien:						1 = left alien on red planet was selected
									2 = right alien on red planet was selected
									3 = left alien on purple planet was selected
									4 = right alien on purple planet was selected
									
rtAlien:							response time (in ms) of selecting an alien (empty if no alien was selected)

winProbability:						the current win-probability (payoff) associated with the selected alien
loseProbability:					the current lose-probability associated with the selected alien 

treasure:							1 = treasure is won 
									2 = NO treasure is won 

//summary variables (across trials):
rocket1SelectionCount:		counts the number of times participant selected rocket1 (left rocket) 
rocket2SelectionCount:		counts the number of times participant selected rocket2 (the leftright rocket)

alien1SelectionCount:		counts the number of times participant selected alien1 (left alien on red planet) 
alien2SelectionCount:		counts the number of times participant selected alien2 (right alien on red planet)  
alien3SelectionCount:		counts the number of times participant selected alien3 (left alien on purple planet)  
alien4SelectionCount:		counts the number of times participant selected alien4 (left alien on purple planet) 

countTreasure:				counts the number of treasures won
 
treasureCountAlien1:		counts the number of treasures won from alien1 (left alien on red planet)   
treasureCountAlien2:		counts the number of treasures won from alien2 (right alien on red planet)  
treasureCountAlien3:		counts the number of treasures won from alien3 (left alien on purple planet)  
treasureCountAlien4:		counts the number of treasures won from alien4 (right alien on purple planet) 
									
									
(2) Summary data file: 'twostepdecisiontask_summary*.iqdat' (a separate file for each participant)*

inquisit.version:					the 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)
									
(parameters) payOff_Version			the current payOff version run (1-4)
									version 1/4 only run for up to 200 trials
									version 2/3 can run for up to 400 trials									
																		
rocket1SelectionCount:		counts the number of times participant selected rocket1 (left rocket) 
rocket2SelectionCount:		counts the number of times participant selected rocket2 (the leftright rocket)

alien1SelectionCount:		counts the number of times participant selected alien1 (left alien on red planet) 
alien2SelectionCount:		counts the number of times participant selected alien2 (right alien on red planet)  
alien3SelectionCount:		counts the number of times participant selected alien3 (left alien on purple planet)  
alien4SelectionCount:		counts the number of times participant selected alien4 (left alien on purple planet)
 
countTreasure:				counts the number of treasures won 

treasureCountAlien1:		counts the number of treasures won from alien1 (left alien on red planet)   
treasureCountAlien2:		counts the number of treasures won from alien2 (right alien on red planet)  
treasureCountAlien3:		counts the number of treasures won from alien3 (left alien on purple planet)  
treasureCountAlien4:		counts the number of treasures won from alien4 (right alien on purple planet) 

propRocketSelections:		proportion of trials (to total number) that a rocket was selected
countRocketSelections:		the total number of rocket selections made 
countNoRocketSelections:	the number of times no rocket was selected 
meanRocketSelectionRT:		the mean response time (in ms) of selecting a rocket (when a rocket was selected)

propAlienSelections:				proportion of trials (to number of alien selection trials) that an alien was selected
propAlienSelectionsTotalTrials:	proportion of trials (to totalTrials) that an alien was selected
countAlienSelections:				the total number of alien selections made 
countNoAlienSelections:			the number of times no alien was selected 
meanAlienSelectionRT:				the mean response time (in ms) of selecting an alien (when an alien was selected)
									
							
								

___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	

(1) Training
- selecting an alien
- retrieving treasure (or not) after selecting an alien (with a certain win probability)
- choosing btw. two aliens (one with a higher win probability) and retrieving (or not) treasures

(2) Practice (of full game; with green/yellow planets): 20 trials (editable parameter)
a. Rocket Selection (max selection time: 3s)
rocket1 (left) vs. rocket2 (right)
Note: by default:
rocket1 flies to the green planet with p=0.7 and to the yellow planet with p=0.3 (editable parameters)
rocket2 flies to the green planet with p=0.3 and to the yellow planet with p=0.7 (editable parameters)

b. Alien Selection (max. selection time: 3s)
green Planet: alien1 (left) vs. alien2 (right)
yellow Planet: alien3 (left) vs. alien4 (right)

Note:
The payoff probabilities associated with each alien for each trial are currently randomly pre-generated
using a random start payoff probability (btw. 0.25 and 0.75) which is 'drifted' for each subsequent trial
by: newpayoff = previouspayoff + randgaussian(0, 1)* dsigma (with drift speed dsigma = 0.025)
(constraint: payoffs are always btw. 0.25 <= payoff <= 0.75)

c. Treasure Feedback

(3) Test (with red/purple planets): 200 trials (editable parameter BUT: current payoff probability are only available for 201 trials)
a. Rocket Selection (max selection time: 3s)
rocket1 (left) vs. rocket2 (right)
Note: by default:
rocket1 flies to the red planet with p=0.7 and to the purple planet with p=0.3 (editable parameters)
rocket2 flies to the red planet with p=0.3 and to the purple planet with p=0.7 (editable parameters)

b. Alien Selection (max. selection time: 3s)
green Planet: alien1 (left) vs. alien2 (right)
yellow Planet: alien3 (left) vs. alien4 (right)

Note:
The payoff probabilities associated with each alien for each trial are pregenerated.
There are 4 different payoff-probability versions to select from: see parameters.payOff_Version

The algorithm used to generate these "drifted" payoff probabilities is as follows:
- generate a random start probability: 0.25 <= p <= 0.75
- for 200 subsequent trials generate: 
newpayoff = previouspayoff + randgaussian(0, 1)* dsigma (with drift speed dsigma = 0.025)
(constraint: payoffs are always btw. 0.25 <= payoff <= 0.75)

c. Treasure Feedback

(Note: all animations run for 1s - hardcoded; cannot be changed easily)

___________________________________________________________________________________________________________________
STIMULI
___________________________________________________________________________________________________________________
based on original mathlab script for the Alien Game

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
based on original mathlab script for the Alien Game

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


___________________________________________________________________________________________________________________	

									*Two-Step Decision Task ('Aliens')*
									- Touch (mouse) Version-
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
last updated:  11-18-2024 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 11-18-2024 Millisecond Software

Millisecond Software thanks Dr. Nathaniel Daw for permission to publish this script
in the Millisecond Software library!

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	

This script implements the Two-step Decision task ('Alien Task') by Decker et al (2016).
The Two-step Decision task is a child-friendly task to study probabilistic decision making in children using
a two-stage reinforcement learning task.
Original Age Group: 8-12 years.

The Inquisit implementation uses touch (mouse) input.

Reference:
Decker JH, Otto AR, Daw ND, Hartley CA. From Creatures of Habit to Goal-Directed Learners: 
Tracking the Developmental Emergence of Model-Based Reinforcement Learning. 
Psychol Sci. 2016 Jun;27(6):848-58. doi: 10.1177/0956797616639301. 
Epub 2016 Apr 15. PMID: 27084852; PMCID: PMC4899156.

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	

Decision Step 1:
Participants are asked to select btw two spaceships that travel to two planets with different probabilities
(e.g. spaceship1 travels to planet1 with p = 0.7 and to planet2 with p = 0.3).

Decision Step 2:
On each planet, they encounter two aliens that work in mines. Aliens retrieve treasure with 'drifting'
probabilities. Participants are asked to select one of the aliens. If the selected alien happens to retrieve
treasure from the mine, it shares it with the participant.

The goal is to collect as much treasure as possible.

___________________________________________________________________________________________________________________	
TASK DURATION
___________________________________________________________________________________________________________________

Practice/Training: ~10 minutes
Test (200 trials): ~15 minutes
_________________________________
Total:	~25 minutes

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

(1) Raw data file: 'twostepdecisiontaskRaw*.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. 
										
stimulusItem:						the presented stimuli in order of trial presentation
response:							the participant's response 								
										
latency: 							the response latency (in ms); measured from: onset of trial


//custom variables:
(parameter) payOff_Version			the current payOff version run (1-4)
									version 1/4 only run for up to 200 trials
									version 2/3 can run for up to 400 trials

countTrials:						counts the number of trials started

alien1payOff:						the payoff (win probability) for selecting alien1 (left alien on green/red planet) in this trial
alien2payOff:						the payoff (win probability) for selecting alien2 (right alien on green/red planet) in this trial 
alien3payOff:						the payoff (win probability) for selecting alien3 (left alien on yellow/purple planet) in this trial 
alien4payOff:						the payoff (win probability) for selecting alien4 (right alien on yellow/purple planet) in this trial


selectedRocket:						1 = the left rocket was selected
									2 = the right rocket was selected
									(or empty if no rocket was selected)
									
rtRocket:							response time (in ms) of selecting a rocket (empty if no rocket was selected)
 
planet:								1 = red planet was assigned; (practice: green planet)
									2 = purple planet was assigned (practice: yellow planet)
									(or empty if no planet was selected)

selectedAlien:						1 = left alien on red planet was selected
									2 = right alien on red planet was selected
									3 = left alien on purple planet was selected
									4 = right alien on purple planet was selected
									
rtAlien:							response time (in ms) of selecting an alien (empty if no alien was selected)

winProbability:						the current win-probability (payoff) associated with the selected alien
loseProbability:					the current lose-probability associated with the selected alien 

treasure:							1 = treasure is won 
									2 = NO treasure is won 

//summary variables (across trials):
rocket1SelectionCount:		counts the number of times participant selected rocket1 (left rocket) 
rocket2SelectionCount:		counts the number of times participant selected rocket2 (the leftright rocket)

alien1SelectionCount:		counts the number of times participant selected alien1 (left alien on red planet) 
alien2SelectionCount:		counts the number of times participant selected alien2 (right alien on red planet)  
alien3SelectionCount:		counts the number of times participant selected alien3 (left alien on purple planet)  
alien4SelectionCount:		counts the number of times participant selected alien4 (left alien on purple planet) 

countTreasure:				counts the number of treasures won
 
treasureCountAlien1:		counts the number of treasures won from alien1 (left alien on red planet)   
treasureCountAlien2:		counts the number of treasures won from alien2 (right alien on red planet)  
treasureCountAlien3:		counts the number of treasures won from alien3 (left alien on purple planet)  
treasureCountAlien4:		counts the number of treasures won from alien4 (right alien on purple planet) 
									
									
(2) Summary data file: 'twostepdecisiontask_summary*.iqdat' (a separate file for each participant)*

inquisit.version:					the 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)
									
(parameters) payOff_Version			the current payOff version run (1-4)
									version 1/4 only run for up to 200 trials
									version 2/3 can run for up to 400 trials									
																		
rocket1SelectionCount:		counts the number of times participant selected rocket1 (left rocket) 
rocket2SelectionCount:		counts the number of times participant selected rocket2 (the leftright rocket)

alien1SelectionCount:		counts the number of times participant selected alien1 (left alien on red planet) 
alien2SelectionCount:		counts the number of times participant selected alien2 (right alien on red planet)  
alien3SelectionCount:		counts the number of times participant selected alien3 (left alien on purple planet)  
alien4SelectionCount:		counts the number of times participant selected alien4 (left alien on purple planet)
 
countTreasure:				counts the number of treasures won 

treasureCountAlien1:		counts the number of treasures won from alien1 (left alien on red planet)   
treasureCountAlien2:		counts the number of treasures won from alien2 (right alien on red planet)  
treasureCountAlien3:		counts the number of treasures won from alien3 (left alien on purple planet)  
treasureCountAlien4:		counts the number of treasures won from alien4 (right alien on purple planet) 

propRocketSelections:		proportion of trials (to total number) that a rocket was selected
countRocketSelections:		the total number of rocket selections made 
countNoRocketSelections:	the number of times no rocket was selected 
meanRocketSelectionRT:		the mean response time (in ms) of selecting a rocket (when a rocket was selected)

propAlienSelections:				proportion of trials (to number of alien selection trials) that an alien was selected
propAlienSelectionsTotalTrials:	proportion of trials (to totalTrials) that an alien was selected
countAlienSelections:				the total number of alien selections made 
countNoAlienSelections:			the number of times no alien was selected 
meanAlienSelectionRT:				the mean response time (in ms) of selecting an alien (when an alien was selected)
									
							
								

___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	

(1) Training
- selecting an alien
- retrieving treasure (or not) after selecting an alien (with a certain win probability)
- choosing btw. two aliens (one with a higher win probability) and retrieving (or not) treasures

(2) Practice (of full game; with green/yellow planets): 20 trials (editable parameter)
a. Rocket Selection (max selection time: 3s)
rocket1 (left) vs. rocket2 (right)
Note: by default:
rocket1 flies to the green planet with p=0.7 and to the yellow planet with p=0.3 (editable parameters)
rocket2 flies to the green planet with p=0.3 and to the yellow planet with p=0.7 (editable parameters)

b. Alien Selection (max. selection time: 3s)
green Planet: alien1 (left) vs. alien2 (right)
yellow Planet: alien3 (left) vs. alien4 (right)

Note:
The payoff probabilities associated with each alien for each trial are currently randomly pre-generated
using a random start payoff probability (btw. 0.25 and 0.75) which is 'drifted' for each subsequent trial
by: newpayoff = previouspayoff + randgaussian(0, 1)* dsigma (with drift speed dsigma = 0.025)
(constraint: payoffs are always btw. 0.25 <= payoff <= 0.75)

c. Treasure Feedback

(3) Test (with red/purple planets): 200 trials (editable parameter BUT: current payoff probability are only available for 201 trials)
a. Rocket Selection (max selection time: 3s)
rocket1 (left) vs. rocket2 (right)
Note: by default:
rocket1 flies to the red planet with p=0.7 and to the purple planet with p=0.3 (editable parameters)
rocket2 flies to the red planet with p=0.3 and to the purple planet with p=0.7 (editable parameters)

b. Alien Selection (max. selection time: 3s)
green Planet: alien1 (left) vs. alien2 (right)
yellow Planet: alien3 (left) vs. alien4 (right)

Note:
The payoff probabilities associated with each alien for each trial are pregenerated.
There are 4 different payoff-probability versions to select from: see parameters.payOff_Version

The algorithm used to generate these "drifted" payoff probabilities is as follows:
- generate a random start probability: 0.25 <= p <= 0.75
- for 200 subsequent trials generate: 
newpayoff = previouspayoff + randgaussian(0, 1)* dsigma (with drift speed dsigma = 0.025)
(constraint: payoffs are always btw. 0.25 <= payoff <= 0.75)

c. Treasure Feedback

(Note: all animations run for 1s - hardcoded; cannot be changed easily)

___________________________________________________________________________________________________________________
STIMULI
___________________________________________________________________________________________________________________
based on original mathlab script for the Alien Game

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
based on original mathlab script for the Alien Game

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