User Manual: Inquisit Wolf and Sheep Task


___________________________________________________________________________________________________________________	

								Wolf and Sheep Task
___________________________________________________________________________________________________________________	


Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 12-13-2023
last updated:  01-05-2024 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 01-05-2024 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________
This script implements Millisecond Software's version of the Wolf and Sheep Task,
a visual search task used to study agency attribution. The Millisecond script is based on 
Lisøy (2018).

References:	

Lisøy, R.S. (2018). Seeing minds: a signal detection study of agency attribution in autism and psychosis. NTNU.
(Dissertation)

Lisøy RS, Biegler R, Haghish EF, Veckenstedt R, Moritz S, Pfuhl G. Seeing minds - a signal detection study of 
agency attribution along the autism-psychosis continuum. 
Cogn Neuropsychiatry. 2022 Sep;27(5):356-372. 
doi: 10.1080/13546805.2022.2075721. Epub 2022 May 17. PMID: 35579601.

Lisøy, R.S., Pfuhl, G., Hope, W.N & Biegler, R. Seeing Minds: A Signal Detection Study of Agency Attribution 
in Autism and Psychosis
downloaded from: https://osf.io/preprints/osf/6yn89
License: CC-By Attribution 4.0 International										

Gao, T., Newman, G. E., & Scholl, B. J. (2009). The psychophysics of chasing: 
A case study 603 in the perception of animacy. 
Cogn Psychol, 59(2), 154-179. 604 doi:10.1016/j.cogpsych.2009.03.001

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________

Participants watch videos with 16 red balls (the 'wolves') and one yellow ball (the 'sheep') moving around the
screen. The task is to decide whether the sheep is hunted ('stalked') by one of the wolves.
If participant reply 'yes' to the question of whether 'the sheep was hunted', they are further asked to identify
the hunting wolf by selecting the letter printed on the red ball that represents the 'hunting wolf'.
___________________________________________________________________________________________________________________	
DURATION 
___________________________________________________________________________________________________________________	
the default set-up of the script takes appr. 10 minutes to complete

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

(1) Raw data file: 'wolfandsheeptask_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:					with the current subject id
group: 						with the current group id
session:					with the current session id

//Screen Setup:
(parameter) runAbsoluteSizes:	true (1) = should run absolutely sized canvas (see parameters- canvasHeight_inmm)
								false (0) = should use proportionally sized canvas (uses width = 43*screenHeight)
								
canvasAdjustments:				NA: not applicable => parameters- runAbsoluteSize was set to 'false'
								0: parameters- runAbsoluteSize was set to 'true' and screen size was large enough
								1: parameters- runAbsoluteSize was set to 'true' BUT screen size was too small and 
								adjustments had to be made

activeCanvasHeight_inmm:		the width of the active canvas (by default: lightGray area) in mm 
activeCanvasWidth_inmm:			the height of the active canvas in mm 
display.canvasHeight:			the height of the active canvas in pixels
display.canvasWidth:			the width of the active canvas in pixels

px_per_mm:						the conversion factor to convert pixel data into mm-results for the current monitor
								(Note: the higher resolution of the current monitor 
								the more pixels cover the same absolute screen distance)
								This factor is needed if you want to convert pixel data into absolute mm data or the other way around



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. 
								
phase:						"practice" vs. "test" 
trialCounterPerBlock:		trialCounter for the current practice or test block 
itemnumber: 				the itemnumber of the currently presented video
video: 						stores the presented video
wolfPresent: 				0 = no wolf; 1 = wolf present
sheepCaught: 				0 = sheep is not caught by the wolf; 1 = sheep is caught by the wolf
actualWolf:					the letter assigned to the current wolf (if any)

//custom DVs:
agencyRsp: 					"yes" or "no" (response to: )
selectedID: 				the selected letter ID of the wolf
							
agencyACC: 					1 = agency response was correct (answer to question "is the sheep being hunted?")
							0 = agency response was incorrect
							
agencyRT: 					latency (in ms) of agency response; measured from onset of question "is the sheep being hunted?" 
					
idACC: 						1 = wolf identity was correctly identified (only relevant if participant chose 'yes' for agency response)
							0 = wolf was not correctly identified
							
idRT:						latency (in ms) of identity response (measure from onset of question until 'submit' button is selected)																						

//built-in DVs:
response:					the response of participant for the current trial
correct:					correctness of response (1 = correct, 0 = error)
latency:					response latency (in ms);

!!!Note: the final trial data is recorded by trial.end

(2) Summary data file: 'wolfandsheeptask_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)
							
//Screen Setup:
(parameter) runAbsoluteSizes:	true (1) = should run absolutely sized canvas (see parameters- canvasHeight_inmm)
								false (0) = should use proportionally sized canvas (uses width = 43*screenHeight)
								
canvasAdjustments:				NA: not applicable => parameters- runAbsoluteSize was set to 'false'
								0: parameters- runAbsoluteSize was set to 'true' and screen size was large enough
								1: parameters- runAbsoluteSize was set to 'true' BUT screen size was too small and 
								adjustments had to be made

activeCanvasHeight_inmm:		the width of the active canvas (by default: lightGray area) in mm 
activeCanvasWidth_inmm:			the height of the active canvas in mm 
display.canvasHeight:			the height of the active canvas in pixels
display.canvasWidth:			the width of the active canvas in pixels

px_per_mm:						the conversion factor to convert pixel data into mm-results for the current monitor
								(Note: the higher resolution of the current monitor 
								the more pixels cover the same absolute screen distance)
								This factor is needed if you want to convert pixel data into absolute mm data or the other way around
							
							

propCorrectAgency:				proportion correct agency responses (out of 50 trials)
numberIdentityResponses:		number of YES responses to agency question (= number of identity responses)
propCorrectID:					proportion correct identity responses (out of numberIdentityResponses)
propCorrectID_transformed:		arcsine square root transformed propCorrectID (see )
meanCorrAgencyRT:				average correct agency response time (in ms)
meanCorrIdRT:					average correct identity response time (in ms)

hitRate:					hitrate (= saying 'yes' when the sheep was hunted)
faRate:						false alarm rate (= saying 'yes' when the sheep was NOT hunted)
z_hitRate:					calculates the z-score for the hitrate. Adjustments are made if the hitrate = 0 (increased to 0.005) or 1 (decreased to 0.995)*
z_faRate:					calculates the z-score for the false alarm rate. Adjustments are made if the  FArate = 0 (increased to 0.005) or 1 (decreased to 0.995)*

dprime:						Computes d' (parametric measure of discriminability btw. signals and noise)
							=> Range (in this script): 
							-5.1516586840152740479 <= dprime <= 5.1516586840152740479 (=perfect performance)
							=> The higher the value, the better signals ('wolf present') were overall distinguished from noise ('wolf absent')
							(d' = 0: chance performance; negative d-primes: participant treated noise as signals and signals as noise)
							=> Note: Lisøy et al target a d-prime around '1' to get enough false alarms for a meaningful c-value
							(aka avoiding ceiling/floor effects)

c:							c-criterion in signal detection:The absolute value of c provides an indication of the strength of
							the subject bias (Anderson, 2015)
							=> Response bias c in this case 'reflects the participants’ propensity to perceive the wolf as present or absent'
							(Lisøy et al)
							=> negative when participant is more likely to report that signal ('wolf present') 
							is present (propensity towards seeing agency), positive for favoring caution ('wolf absent')
							
*Adjustments to z-scores as recommended by:
Gregg, A. & Sedikides, C. (2010). Narcissistic Fragility:
Rethinking Its Links to Explicit and Implicit Self-esteem, Self and Identity, 9:2, 142-161 (p.148)
							
__________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________	

(1) Practice: 
- 2 warm-up trials (practice trials only run 10 wolves instead of 16)
- by default, the two videos are run in fixed sequence 
	1. video: no wolf
	2. video: wolf (letter 'L')
In this script, participants get to watch the video again if they make a mistake for either the
'agency' and the 'identification' questions during practice

(2) Test:
- 50 videos (16 wolves)
- by default, the videos are presented in a fixed sequence
- half the videos present a wolf

Trial Sequence (Test)
-> get ready (2000)
-> video (until video is done running), about 5seconds for each
-> agency question: 'was the sheep being hunted?' until response (yes or no)
-> if YES: identification question: the 16 letters are presented in a 4x4 matrix in the center of the screen
	and participants can select the letter. They can change their answer until they press the 'submit' button
	
-> if NO: start of next trial sequence

Note: there is no performance feedback given during test
___________________________________________________________________________________________________________________	
STIMULI
___________________________________________________________________________________________________________________

provided by Lisøy et al (2018) under the CC-By Attribution 4.0 International License:
https://osf.io/qaeyu/
___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________

the instructions are not original to Lisøy et al (2018);
they are provided by Millisecond Software - 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:

//color parameter
/ canvascolor = black			//Display color of the actively used portion of the screen (the 'canvas')	
									//Note: if set to a color other than the screencolor, the active canvas
									//appears 'anchored' on the screen regardless of monitor size
/ screencolor = gray 			//Color of the screen not used by the canvas ('inactive screen')
/ defaultTextColor = white		//Default color of text items presented on active canvas

//CANVAS SIZING PARAMETERS
//Screen Sizes		
/ runAbsoluteSizes = true		//true = runs absolutely sized canvas (see parameters.canvasHeight_inmm)
								//false = uses proportionally sized canvas (uses width = 4/3*screenHeight)
								//the script will look for the larges 4:3 area it can find on the current screen
																			
//the setting of the active canvas in absolute mm is only relevant if parameters.runAbsoluteSizes = true (1)
//=> IF the screen is not sufficiently big to allow for the absolute canvassize
//the script will run a default width:height=4:3 and make a note in the data files
//the default absolute sizes provided here are optimized for ipad use																																						
/ canvasHeight_inmm = 144				//the height (H) of the active canvas in mm (default: 144mm ~ ipad screen height)
										//Note: the width of the active canvas (W) is automatically set at
										//ratio: W:H ~ 4:3 => W= 4/3*canvasHeight_inmm = 144mm*4/3=192mm (default)

//sizing Parameters in RELATIVE measurements
//the remaining items are sized relative to CANVAS HEIGHT
//=> Result: 
//for absolute canvassizes: you achieve the same absolutely sized stimuli on all screens
//for relative canvassizes: stimuli are proportionally sized on all screens	

/ videoSize = 100%				//the proportional size of the video relative to active canvas
								//by default: covers the entire active canvas

//timing parameters
/ getreadyDuration = 2000		//duration (in ms) of the get ready trials
/ feedbackDuration = 1000		//duration (in ms) of the practice feedback stims