User Manual for Inquisit's Überball


___________________________________________________________________________________________________________________	

									Überballberball: 4 PLAYERS
___________________________________________________________________________________________________________________	

last updated:  02-21-2022 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

This script is generously shared with the Millisecond library by Dr. S.Dandeneau
(contact email: dandeneau.stephane@uqam.ca).
The original Überball script is adapted from the following Cyberball Inquisit 4 script: 
SCRIPT INFO: last updated 04-02-2014 by K. Borchert (katjab@millisecond.com) for Millisecond Software 

Millisecond software updated the user manual and added several Inquisit 6 variables to the
data file as well as added a sizing parameter for the video size.

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________
Überball runs a preferential social inclusion condition which increases fundamental needs fulfillment
in contrast to the exclusion game played by traditional cyberball games.

Überball is based on: 

Simard, V., & Dandeneau, S. (2018). Revisiting the Cyberball inclusion condition: Fortifying fundamental needs 
by making participants the target of specific inclusion. 
Journal of Experimental Social Psychology, 74, 38-42. https://doi.org/10.1016/j.jesp.2017.08.002

And on Cyberball: 

Williams, K. D., Cheung, C. K. T., & Choi, W. (2000). CyberOstracism: Effects of being ignored over 
the Internet. Journal of Personality and Social Psychology, 79, 748-762.

Williams, K. D., & Jarvis, B. (2006). Cyberball: A program for use in research on ostracism and interpersonal 
acceptance. Behavior Research Methods, Instruments, and Computers, 38, 174-180.

see also: http://www1.psych.purdue.edu/~willia55/Announce/cyberball.htm

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________
Participant plays ball with 3 other participants (= the computer). 

___________________________________________________________________________________________________________________	
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: 'uberball_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
trialcode, trialnum: 			the name and number of the currently recorded trial
								(Note: not all trials that are run might record data) 
								Trialcode Explanation: 
								Examples:
									"1to2" => in this trial player 2 (participant) throws the ball AFTER getting it from player 1
									"1to3" => in this trial player 3 throws the ball AFTER getting it from player 1 (random selection decides whether player 3 throws to player 1)

player:							stores the current player
recipient:						stores the recipient of the current ball toss (1, 2, 3, 4)								
response:						the (participant's) response
latency: 						the response latency (for trials in which player 1 and 3 "play", the latency
								is the randomly selected trialduration)
count_ignore2:					counts how often player 2 (participant) was "ignored" before a throw (resets every time
								player 2 gets to throw the ball)


(2) Summary data file: 'uberball_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 settings:
showpictures:						true = pictures of players are onscreen (default)
									false = no pictures are presented
									
showlabels:							true = labels of players are onscreen (default)
									false = no labels are presented

item.player1.1-
item.player4label.1:				images and labels used for the various players

////data:
max_trialcount:						maximum number of trials (= passes between all players) played		

ignore2_streak1: 					the number of times player 2 (participant) was ignored before player2 (participant) 
									gets to respond for the first time
									
max_ignore2:						the longest streak of ignoring player 2 (participant) in the game that participant experienced
									before being able to respond

count_player2throws:				counts the number of times that player 1 gets to throw the ball
count_player2throws:				counts the number of times that player 3 gets to throw the ball
count_player2throws:				counts the number of times that player 2 (participant) gets to throw the ball
meanRT_player2:						mean latency (in ms) of player 2 (participant)

count_12:							counts the number of times that player 1 throws to player 2 (participant)
perc_12:							percentage of player 1 throws that play to player 2 (participant)
count_21:							counts the number of times that player 2 (participant) throws to player 1
perc_21:							percentage of player 2 throws (participant) that play to player 1
meanRT_21:							mean latency (in ms) of player 2 (participant) decisions to throw to player 1

(same for player 3 and 4)

perc_sameplayer:					percentage of player 2 (participant) throws when player 2 throws the ball back to the player who threw the ball to participant
										Note: random selection -> 1/3 times of all player 2 throws
perc_otherplayer:					percentage of player 2 (participant) throws when player 2 throws ball to the player who didn't threw the ball to participant
										Note: random selection -> 2/3 times of all player 2 throws
meanRT_sameplayer:					mean latencies (in ms) of trials in which player2 (participant) throws ball back to the player who threw the ball to participant
meanRT_otherplayer:					mean latencies (in ms) of trials in which player2 (participant) throws ball to a player who didn't threw the ball to participant


___________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________
* Participant plays ball with 3 other players for 50 trials.
The number of trials can be edited under EDITABLE PARAMETERS/EXPRESSIONS.

* By default, all players are represented by names. 
Names and pictures can be edited under EDITABLE STIMULI.
To change names or pictures go to EDITABLE PARAMETERS/EXPRESSIONS.

* By default, player 1 and player 4 throws the ball to participant (=player2) AND DO NOT throw to player 3.
Go to EDITABLE LISTS for further instructions.

* Decision Times for Player 1,3 and 4 are controlled by expressions.cyberdecisiontime under
EDITABLE PARAMETERS/EXPRESSIONS.

* Instructions can be edited under EDITABLE INSTRUCTIONS

___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________	
picture examples are provided by Millisecond Software. They can easily be edited under section
Editable Stimuli

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________
can be edited under section Editable Instructions

___________________________________________________________________________________________________________________	
EDITABLE CODE 
___________________________________________________________________________________________________________________	
check below for (relatively) easily editable parameters, stimuli, instructions etc. 
Keep in mind that you can use this script as a template and therefore always "mess" with the entire code 
to further customize your experiment.

The parameters you can change are:

/max_trialcount:	maximum number of trials (= passes between the players) played		
/showpictures:		true = pictures of players are onscreen
					false = no pictures are presented (default)
/showlabels:		true = labels of players are onscreen (default)
					false = no labels are presented
						
NOTE: parameters.showpictures and parameters.showlabels cannot be set to false at the same time.

/videoSize:			sets the size of the video relative to canvas