User Manual: Inquisit Prisoner's Dilemma Task with Reciprocity

						
__________________________________________________________________________________________________________________	

										*Prisoner Dilemma Game*
										- Reciprocity Design - 
___________________________________________________________________________________________________________________	

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 01-04-2018
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 Prisoner Dilemma Game within a reciprocity design.
The Prisoner Dilemma Task is 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 procedure uses an 'investment framework' in which participants have the opportunity
to play the game with the same 'partners' after a practice phase during which the participants are forced
to always invest (aka cooperate).

The implemented procedure is based on:

Bell R, Mieth L, Buchner A (2017). Separating conditional and unconditional cooperation in a 
sequential Prisoner's Dilemma game. PLoS ONE 12(11): e0187952. https://doi.
org/10.1371/journal.pone.0187952

Note: by default, multiple partners are used in the script

__________________________________________________________________________________________________________________
TASK DESCRIPTION
___________________________________________________________________________________________________________________	
Participants play an investment prisoner dilemma game. Each round they are paired with a 
different partner (introduced via images) and have to decide to invest money into a shared
fund or not. For each investment/cooperation decision, the computer adds a certain amount of money to 
the fund (e.g. if participant decides to cooperate and invests money, the computer adds money.
If the partner decides to invest money, the computer adds additional money.). At the end of each
round the money in the shared fund gets equally divided between the two people.
Thus:
a) Partner cooperates-participant does not: participant makes net gain
b) Mutual cooperation: participant makes a net gain (as high as the incentive amount provided by computer)
c) Mutual non-cooperation: participant neither wins nor loses any money
d) Participant cooperates-partner does not: participant makes a net loss

The game is divided into two phases:
1. Exposure phase: During the exposure phase, participants get to know their different partners via their images
and 'practice' the game (though they will be forced to always cooperate, their 'partners' will not)
2. Test phase: During the test phase, participants are again paired with the same partners as well
as a couple of new ones. This time participants are free to cooperate or compete.

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

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

(1) Raw data file: 'prisonerdilemma_reciprocity_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.
									If (parameter) predeterminedExposureDecisions is set to 'true', the selected strategy is overwritten
									and the assigned exposureComputerDecision is used instead during the exposure phase.
								
									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)

phase:								"exposure" vs. "test"
countRounds:						tracks the number of round played per phase (resets after practice)
partnerGender:						"female" vs. "male"
facialExpression:					"happy" vs. "angry" (facial expression of current partner image)
familiarity:						"old" (images used during exposure) vs. "new" (images used only during the test phase)
faceStim:							stores the image file of the current partner

exposurePartnerDecision:			1 = cooperative decision during exposure of this partner; 
									2 = non-cooperative decision during exposure of this partner
									"N/A" (for new items)
									
previous_partnerdecision:			the partner decision from the previous round: 1 = cooperative; 2 = noncooperative								
partnerdecision:					1 = cooperative partner decision; 
									2 = non-cooperative partner decision
									
response:							default variable to capture the response recorded during the current trial									

decision:							1 = cooperative participant decision; 
									2 = non-cooperative participant decision
									
latency:							latency (in ms) of currently recorded trial																	
rt_decision:						latency of decision (in ms)

countConsecutiveNonCooperative:		counts the number of consecutive non-cooperative decisions made by participant
startBalance:						stores the balance at the start of each round
endBalance:							stores the balance at the end of each round
fundMoney:							stores the total money in the shared fund
(parameter) investmentAmount:		the amount (in cents) participants are asked to invest per round (default: 30cents)


(2) Summary data file: 'prisonerdilemma_reciprocity_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.
									If (parameter) predeterminedExposureDecisions is set to 'true', the selected strategy is overwritten
									and the assigned exposureComputerDecision is used instead during the exposure phase.
								
									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)

(parameter) predeterminedExposureDecisions:		true (1) = the computer uses pre-assigned cooperation vs. non-cooperation decisions
												that are carefully balanced by gender x facial expression during the exposure phase.
												During the test phase, the computer generates the partner's decision based on (parameter) computerStrategy. (default)
												false (0) = the computer generates the partner's decision based on (parameter) computerStrategy
												during exposure and test phase.
							
propCooperation:				proportion cooperation selections during the test rounds

propReciprocity:				proportion reciprocity during the test rounds
								reciprocity = selecting cooperation during the test round for partners who
								cooperated during the exposure phase.
					
propRetaliation:				proportion retaliation during the test rounds
								retaliation = selecting non-cooperation during the test round for partners who
								did not cooperate during the exposure phase.
									
propReciprocity_angry:			proportion reciprocity during the test rounds for 'famkliar' partners with angry expressions
								reciprocity = selecting cooperation during the test round for partners who
								cooperated during the exposure phase.
									
propReciprocity_happy:			proportion reciprocity during the test rounds for 'old' partners with happy expressions
								reciprocity = selecting cooperation during the test round for partners who
								cooperated during the exposure phase.									
					
propRetaliation_angry:			proportion retaliation during the test rounds for 'old' partners with angry expressions
								retaliation = selecting non-cooperation during the test round for partners who
								did not cooperate during the exposure phase.

propRetaliation_happy:			proportion retaliation during the test rounds for 'old' partners with happy expressions
								retaliation = selecting non-cooperation during the test round for partners who
								did not cooperate during the exposure phase.	
									
mRT:							mean decision latency (in ms) during the test phase

mRT_cooperative:				mean decision latency (in ms) of cooperative decisions during the test phase
mRT_noncooperative:				mean decision latency (in ms) of cooperative decisions during the test phase

mRT_reciprocity:				mean decision latency (in ms) of reciprocity decisions (see propReciprocity)
mRT_retaliation: 				mean decision latency (in ms) of retaliation decisions (see propRetaliation)

mRT_cooperativeAfterCooperative:		mean decision latency (in ms) of cooperative decisions made after the last partner made a non-cooperative decision 
mRT_cooperativeAfterNoncooperative:		mean decision latency (in ms) of cooperative decisions made after the last partner made a cooperative decision 
mRT_noncooperativeAfterCooperative:		mean decision latency (in ms) of non-cooperative decisions made after the last partner made a non-cooperative decision 
mRT_noncooperativeAfterNoncooperative:	mean decision latency (in ms) of non-cooperative decisions made after the last partner made a cooperative decision 


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

Stimuli-Assignment:
- the script automatically randomly selects 6 of each genderxemotion category to be used during the
exposure phase. 
- computer balances the number of cooperation and non-cooperation 'decisions' across genders and facial expressions

1. Exposure Phase:
- 24 trials: participant plays the game with 12 female partners (6 look angry, 6 look happy) and 12 male partners
(6 look angry, 6 look happy)
- by default, the computer assigns to each partner image its investment decision (cooperation vs. non-cooperation)
(the number of cooperation and non-cooperation 'decisions' is balanced across genders and facial expressions;
given these constraints, the assignment is randomly done for each participant)
- the order of the images is selected at random for each participant
- by default, participant is forced to cooperate during the first round

2. Test Phase:
- 36 trials: participants play the game with the 24 exposure-phase partners and 12 new ones 
(6 females: 3 happy, 3 angry; 6 males: 3 happy and 3 angry)
- the order of the images is selected at random for each participant
- by default, the investment decision of the partners is decided randomly by the computer
- by default, participant is forced to cooperate during the first round

Trial Sequence:
- presentation of current start balance (5000ms)
- presentation of current partner image and the cooperation question (until response)
- decision delay (1000ms)
- participant decision feedback (1000ms)
- partner decision delay (5000ms)
- partner decision feedback (5000ms)
- presentation of gain/loss outcome (5000ms)
- presentation of end balance (5000ms)

Round Duration (default settings): 27s + response time

___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________	
Bell et al (2017) used the AR database: http://www2.ece.ohio-state.edu/~aleix/ARdatabase.html
This database is free to use for academic research

The stimuli used in this script are images collected from the internet and should be 
treated as placeholders. They can be exchanged under section Editable Stimuli.

There are 4 x 9 = 36 stimuli provided.

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________	
Instructions are not original to the task. They are provided by Millisecond Software
as htm/html pages and can be edited 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:
/startCapital:					the amount (in cents) participants receive at the start of the practice and test session
								(default: 100 cents)
								
/investmentAmount:				the amount (in cents) participants are asked to invest per round (default: 30cents)

/bonusAmount:					the bonus amount (in cents) added to the shared fund for each cooperation decision
								(either from participant or partner) (default: 10cents)

/predeterminedExposureDecisions		true (1) = the computer uses pre-assigned cooperation vs. non-cooperation decisions
											that are carefully balanced by gender x facial expression during the exposure phase.
											During the test phase, the computer generates the partner's decision based on parameters.computerStrategy. (default)
									false (0) = the computer generates the partner's decision based on parameters.computerStrategy
											during exposure and test phase.
											
/computerStrategy:				the strategy the computer uses to make its choice.
								If parameters.predeterminedExposureDecisions is set to 'true', the selected strategy is overwritten
								and the assigned values.exposureComputerDecision is used instead during the exposure phase.
								Furthermore, some of these strategies may not make sense given the experimental design used.
								(e.g. 'tit-for-tat' only makes sense if the same partner is used repeatedly)
								
									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)

/presentBalance_test:			true (1) = the balance is presented at start and end of each test trial (default)
								false (0) = the balance is not presented at start and end of each test trial
									Note: if the default is changed, you might have to change instructions accordingly
							
/presentPartnerDecision_test:	true (1) = the participant receives feedback in regard to the partner's decision (same as in practice)
								false (0) = no feedback in regard to partner decision is given during test (default)
									Note: if the default value is changed, change the instructions accordingly