User Manual: Inquisit Prisoner's Dilemma Task with Outcome Matrices

													
___________________________________________________________________________________________________________________	

											*Prisoner's Dilemma*
									PDG matrix presentation procedure*
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 10-13-2017
last updated:  02-25-2022 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 02-25-2022 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________	

This script implements a computer version of the Prisoner's Dilemma Task; a decision making task about cooperation 
and competition in resource allocation in the absence of knowing what the other party's decision will be. 
The Prisoner's Dilemma Task is a non-zero-sum game where the rewards are not a straightforward 'I win what you lose
(or vice versa)' but rather a more varied pattern of resource allocation depending on the cooperative vs. 
competitive choices of both parties. The dilemma is to decide between cooperation and competition (aka self-interest)
when competition might yield the highest (immediate) reward but loses to cooperation if both parties decide to compete.

The implemented procedur is based on a generic matrix presentation procedure
described by:

Lyn Ellett , Rhani Allen-Crooks , Adele Stevens , Tim Wildschut & Paul
Chadwick (2013) A paradigm for the study of paranoia in the general population: The Prisoner's
Dilemma Game, Cognition and Emotion, 27:1, 53-62, DOI: 10.1080/02699931.2012.689757

___________________________________________________________________________________________________________________
TASK DESCRIPTION
___________________________________________________________________________________________________________________	
Participants play a 'game' for points with a co-player (computer).
An outcome matrix is presented that outlines the gains in points if participant and co-player choose
cooperative (simply labeled as "strategy X") or competitive (simply labeled "strategy Y")
strategies.

All numbers in the outcome matrix follow the general pattern 
(= Prisoner's Dilemma Game Matrix or short: PDG Matrix):

Cooperation loss (participant cooperates, computer competes) <
Competitive loss (participant AND computer compete) <
Cooperation win (participant AND computer cooperate) <
Competitive win (participant competes, computer cooperates)

Participant has to make a decision without knowing which strategy the co-player will choose.
Number of games played as well as strategy selection of computer can be set by experimenter.
By default, only one game is played (to change, go to section Editable Parameters).
Default instructions are used that imply that 'up to 6 games' may be played.
These instructions can also easily be edited (to change, go to section Editable Parameters).

In this script, following the procedure described by Ellett et al (2013), no contextual 
game story is provided along with the PDG matrix nor are explicit instructions such as 
"maximize your gains" given. The words 'cooperative' vs. 'competitive' are NOT mentioned
to participant. This, however, can all be edited by changing the provided instruction html-files.

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

___________________________________________________________________________________________________________________	
DATA FILE INFORMATION 
___________________________________________________________________________________________________________________
The default data stored in the data files are:

(1) Raw data file: 'prisonerdilemma_pdgmatrix_raw*.iqdat' (a separate file for each participant)*

build:							The specific Inquisit version used (the 'build') that was run
computer.platform:				the platform the script was run on (win/mac/ios/android)
date, time: 					date and time script was run 
subject, group, 				with the current subject/groupnumber
session:						with the current session id

blockcode, blocknum:			the name and number of the current block (built-in Inquisit variable)
trialcode, trialnum: 			the name and number of the currently recorded trial (built-in Inquisit variable)
									Note: trialnum is a built-in Inquisit variable; it counts all trials run; even those
									that do not store data to the data file such as feedback trials. Thus, trialnum 
									may not reflect the number of main trials run per block.
										
(parameter) computerStrategy:	the strategy the computer uses to make its choice (determined by experimenter)
								1 = 'cooperation': selects the cooperative strategy X on every round									
								2 = 'competition': simply defects on every round of every game by choosing the non-cooperative strategy Y
								3 = 'random': selects randomly
								4 = 'tit-for-tat': cooperates on first round then mirrors the players choices from the previous rounds
								5 = 'tit-for-two-tats': computer cooperates until 2 defects in a row and does not cooperate again until player does
								6 = 'probabilistic': cooperates on first round, then selects the strategy that is most often used by player
								(Note: if player has selected the cooperative strategy exactly 50% of the time, computer selects cooperative strategy)
																		
countRounds:					counts the number of game roun
ds played
pattern:						this script uses 3 formulas to calculate the PDG matrix values (1-3)
								see below (section Experimental SetUp to get more information on the patterns)

player1Xplayer2X:				stores the points won by participant if participant (player1 ) chooses X and computer (player2) chooses X
player2Xplayer1X:				stores the points won by computer if participant chooses X and computer chooses X

player1Xplayer2Y:				stores the points won by participant if participant chooses X and computer chooses Y
player2Yplayer1X:				stores the points won by computer if participant chooses X and computer chooses Y

player1Yplayer2Y:				stores the points won by participant if participant chooses Y and computer chooses Y
player2Yplayer1Y:				stores the points won by computer if participant chooses Y and computer chooses Y

player1Yplayer2X:				stores the points won by participant if participant chooses Y and computer chooses X
player2Xplayer1Y:				stores the points won by computer if participant chooses Y and computer chooses X									
																		
response:						the participant's response (response box selected: X vs. Y)
correct:						accuracy of response: 1 = correct response; 0 = otherwise
list.practiceACC.mean:			proportion correct during the current practice block
latency: 						the response latency (in ms); measured from: onset of PDG matrix

selectedStrategy:				stores the participant selected strategy (X or Y) on the current trial
coplayerStrategy:				stores the computer strategy selected on the current trial (X or Y)
totalPlayer:					stores the total points won by participant at the end of the current trial
totalCoPlayer:					stores the total points won by computer at the end of the current trial
countConsecutiveY:				counts the number of consecutive selections of competitive strategy (Y)
previousPlayerStrategy:			stores the strategy participant selected on the previous trial (X or Y)
previousCoplayerStrategy:		stores the computer strategy selected on the previous trial (X or Y)
propCooperation:				proportion of cooperation strategy (X) selections
propCompetition:				proportion of competition strategy (Y) selections

(2) Summary data file: 'prisonerdilemma_pdgmatrix_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)

(parameter) computerStrategy:	the strategy the computer uses to make its choice (determined by experimenter)
								1 = 'cooperation': selects the cooperative strategy X on every round									
								2 = 'competition': simply defects on every round of every game by choosing the non-cooperative strategy Y
								3 = 'random': selects randomly
								4 = 'tit-for-tat': cooperates on first round then mirrors the players choices from the previous rounds
								5 = 'tit-for-two-tats': computer cooperates until 2 defects in a row and does not cooperate again until player does
								6 = 'probabilistic': cooperates on first round, then selects the strategy that is most often used by player
								(Note: if player has selected the cooperative strategy exactly 50% of the time, computer selects cooperative strategy)

countPracticeBlocks:			number of practice blocks run
list.practiceACC.mean:			proportion correct during the last practice block

countRounds:					the number of games played
totalPlayer:					stores the total points won by participant
totalCoPlayer:					stores the total points won by computer
numberCooperation:				absolute number of selecting cooperation strategy (X)
propCooperation:				proportion of cooperation strategy (X) selections
numberCompetition:				absolute number of selecting competition strategy (Y)
propCompetition:				proportion of competition strategy (Y) selections

meanRT:							mean overall response time (in ms)
meanRT_Cooperation:				mean response time (in ms) of selecting cooperation strategy (X)
meanRT_Competition:				mean response time (in ms) of selecting cooperation strategy (Y)

countResponses_afterCompetition:		number of responses made after the computer previously chose competition 
propCooperation_afterCompetition:		proporation cooperation after the computer previously chose competition
numberCooperation_afterCompetition: 	absolute number of cooperations after the computer previously chose competition
meanRT_afterCompetition:				mean response time (in ms) after the computer previously chose competition
meanRT_cooperation_afterCompetition:	mean response time (in ms) of cooperative responses after the computer previously chose competition
meanRT_competition_afterCompetition): 	mean response time (in ms) of competitive responses after the computer previously chose competition

countResponses_afterCooperation:		number of responses made after the computer previously chose cooperation
propCooperation_afterCooperation:		proporation cooperation after the computer previously chose cooperation
numberCooperation_afterCooperation: 	absolute number of cooperations after the computer previously chose cooperation
meanRT_afterCooperation:				mean response time (in ms) after the computer previously chose cooperation
meanRT_cooperation_afterCooperation:	mean response time (in ms) of cooperative responses after the computer previously chose cooperation
meanRT_competition_afterCooperation: 	mean response time (in ms) of competitive responses after the computer previously chose cooperation


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

1. Instructions
The instruction blocks gives general information about the task and walks participants through
the PDG outcome matrix.

2. Practice
The practice blocks practices and tests participant's understanding of the value matrix.
(Note: In this script, values used during practice can either follow the PDG pattern (default) or can be
assigned randomly. See section Editable Parameters)
Each practice blocks presents 4 trials that pose a question regarding each of the 4 matrix quadrants:
"If you select strategy: A and your co-player selects strategy: B
How many points will {you/co-player} get?"
Participants have to get all four questions of a practice block correct before moving on to the test block.
Practice is repeated until all 4 questions are answered correctly or 10 practice blocks have run.
After 10 practice blocks the script aborts if participant does not provide perfect understanding of the matrix set-up.

3. Test
The test runs as many games as specified by parameters.numberOfGames (default: 1, see Ellett et al, 2013)
Participant are told they are paired with a co-player. By default, the 'pairing' takes 5s (editable parameter).
For each round a new PDG matrix is presented and participants have to make a choice.
After they make their choice, a random delay is introduced that simulates the decision time of the coplayer
(sometimes the co-player takes more time, sometimes less).
Once both decisions are 'known', feedback is provided and the participant is told what strategy the co-player chose,
and how many points they both won. The feedback also includes an update of the total number of points won across all games played.

PDG Matrix Values:
This script implements three patterns to calculate the values presented in the PDG matrices. By default, the pattern is
selected randomly without replacement by list.patterns (see section Editable Lists)
pattern 1 => 
COOPERATION LOSS = COOP - 2* 1/3COOP
COMPETITION LOSS = COOP - 1* 1/3COOP 
COOPERATION WIN = COOP
COMPETITION WIN = COOP + 1* 1/3COOP

pattern2 =>
COOPERATION LOSS = COOP - 2* 1/2COOP = 0
COMPETITION LOSS = COOP - 1* 1/2COOP
COOPERATION WIN = COOP
COMPETITION WIN = COOP + 1* 1/2COOP

pattern3 =>
COOPERATION LOSS = COOP - 3.5* 1/4COOP
COMPETITION LOSS = COOP - 3* 1/4COOP
COOPERATION WIN = COOP
COMPETITION WIN = COOP + 3* 1/4COOP

The cooperation win number (COOP) is randomly selected by list.cooperativeWinNumber (see section Editable List).
By default, numbers from 1-100 are selected randomly without replacement.

___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________	
provided by Millisecond Software - can be edited under section Editable Stimuli

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
Instructions are not original to the task. They are provided by Millisecond Software
as htm/html pages can be edited either by changing the provided htm/html files.
To edit htm/html-files: open the respective documents in simple Text Editors such as TextEdit (Mac)
or Notepad (Windows).
___________________________________________________________________________________________________________________	
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:

/maxPracticeBlocks:				the maximum number of times participants have to go through the matrix practice block before
									the script aborts due to low understanding (participants move on from practice only with 100% correct
									understanding of matrix) (default: 10)
								
/usePDGmatrix_practice:			true (1): the practice session uses PDG outcome matrices (default)
								false (0): the practice session uses randomly outcome matrices

/numberOfGames:					the number of games played (see also expressions.numberGamesInstruct) (default: 1)

/computerStrategy:				the strategy the computer uses to make its choice
									1 = 'cooperation': selects the cooperative strategy X on every round									
									2 = 'competition': simply defects on every round of every game by choosing the non-cooperative strategy Y
									3 = 'random': selects randomly
									4 = 'tit-for-tat': cooperates on first round then mirrors the players choices from the previous rounds
									5 = 'tit-for-two-tats': computer cooperates until 2 defects in a row and does not cooperate again until player does
									6 = 'probabilistic': cooperates on first round, then selects the strategy that is most often used by player
									(Note: if player has selected the cooperative strategy exactly 50% of the time, computer selects cooperative strategy)
									
/waitDuration:					the duration (in ms) that participant has to wait to get 'paired' (default: 5000ms)									
/iti:							intertrial interval (in ms) (default: 1000ms)