<usermanual>
___________________________________________________________________________________________________________________	

					DIFFERENCE THRESHOLD: ADJUSTMENT METHOD (Example: determine difference threshold for a red)
___________________________________________________________________________________________________________________

Script Author: Katja Borchert, Ph.D. (katjab@millisecond.com) for Millisecond Software, LLC
Date: 01-20-2014
last updated:  03-06-2020 by K. Borchert (katjab@millisecond.com) for Millisecond Software, LLC

Script Copyright © 03-06-2020 Millisecond Software

___________________________________________________________________________________________________________________
BACKGROUND INFO 	
___________________________________________________________________________________________________________________
This script implements the ADJUSTMENT METHOD to estimate the difference threshold for a particular color red

Reference: 
Ehrenstein, W.H. & and Addie Ehrenstein, A. (1999). Psychophysical Methods. In U. Windhorst & H. Johansson, Hakan (Eds.), 
Modern Techniques in Neuroscience Research (pp.1211-1241). Heidelberg: Springer.
(->http://uni-leipzig.de/~isp/isp/history/texts/PSYPHY-M.PDF)

___________________________________________________________________________________________________________________
TASK DESCRIPTION	
___________________________________________________________________________________________________________________	
Participants are asked to adjust a red Target color until the red color of the Target is as red as the given
red Base color. Adjustments are made with keyboard input (D = decrease red target color; L =  increase red target color)

___________________________________________________________________________________________________________________	
DURATION 
___________________________________________________________________________________________________________________	
the default set-up of the script takes appr. 2 minutes to complete

___________________________________________________________________________________________________________________	
DATA FILE INFORMATION 
___________________________________________________________________________________________________________________
The default data stored in the data files are:

(1) Raw data file: 'adjustmentmethod_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
script.sessionid:					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. 
										
values., values., values., values., values., response, latency,
values., values., expressions.										
									
adjustcycles:						stores the number of adjustment cycles run

baseline_value:						stores the color of the current base
target_value:						stores the color of the current target

direction:							1 = Down (sequence starts with targetvalue > baseline value)
									2 = Up (sequence starts with targetvalue < baseline value)

sequencecount:						counts how many adjustment sequences have been run
	
response:							the participant's response
latency: 							the response latency in ms
						
diffthreshold_up:					the estimated Difference threshold for the current UP sequence (= starting with
									target value < baseline value)
									
diffthreshold_down:					the estimated Difference threshold for the current DOWN sequence (= starting with
									target value > baseline value)
								
MeanDiffThreshold:					mean difference threshold for one adjustment cycle (up and down)


(2) Summary data file: 'adjustmentmethod_redcolor_summary*.iqdat' (a separate file for each participant)

computer.platform:					the platform the script was run on (win/mac/ios/android)
script.startdate:					date script was run
script.starttime:					time script was started
script.subjectid:					assigned subject id number
script.groupid:						assigned group id number
script.sessionid:					assigned session id number
script.elapsedtime:					time it took to run script (in ms); measured from onset to offset of script
script.completed:					0 = script was not completed (prematurely aborted); 
									1 = script was completed (all conditions run)

parameters.step:					the decrease in target value everytime participants adjusts (default: 1)
adjustcycles:						stores the number of adjustment cycles run				
parameters.baselinevalue1:			the default baseline value for the first adjustment cycle
diffthreshold1:						mean difference threshold for the first adjustment cycle (both up and down)

__________________________________________________________________________________________________________________	
EXPERIMENTAL SET-UP 
___________________________________________________________________________________________________________________
	
By default this scripts estimates the Difference Thresholds for 1 Base color (-> editable values), 
with 2 sequences (one where the targets starts out lighter and one where the target starts out darker, 
order randomly determined).
The thresholds are the red color components of the target when participants decide that they are the same (aka press 'ENTER').
The overall threshold is the mean of the "up" and "down" thresholds.

___________________________________________________________________________________________________________________	
INSTRUCTIONS 
___________________________________________________________________________________________________________________
see 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:

/baselinevalue1:					the baseline red value for the first adjustment cycle
									(0 -> black, 255 -> brightest red)
									Note: to add adjustment cycles with different basevalues
									add a value for each new baseline value you want to test and go to
									BLOCKS for further instructions.

/step:								the decrease in target value everytime participants adjusts (default: 1)
/initialdifference:					initial difference in the red component of target and base (default: 50)						

/interadjustmentpause:				pause after an adjustment sequence (default: 500ms)

</usermanual>


**************************************************************************************************************
**************************************************************************************************************
	EDITABLE PARAMETERS: change editable parameters here
**************************************************************************************************************
**************************************************************************************************************

<parameters>
/responsekey_up = "L"
/responsekey_down = "D"

/baselinevalue1= 80

/step = 1
/initialdifference = 50

/interadjustmentpause = 500
</parameters>

**************************************************************************************************************
**************************************************************************************************************
	EDITABLE STIMULI: change editable stimuli here
**************************************************************************************************************
**************************************************************************************************************

<item labels>
/1 = "BASE COLOR"
/2 = "TARGET COLOR"
</item>

**************************************************************************************************************
**************************************************************************************************************
	EDITABLE INSTRUCTIONS: change instructions here
**************************************************************************************************************
**************************************************************************************************************
<item instructions>
/1 = "Adjust the Target Color (right) so that it is the same color as the Base Color (left)"
/2 = "To lighten the red target component -> Press the '<%parameters.responsekey_up%>' <%expressions.buttoninstruct1%>
To darken the red target component  -> Press the '<%parameters.responsekey_down%>' <%expressions.buttoninstruct1%>

Press ENTER when both circles are the same red"
</item>


<instruct>
/ fontstyle = ("Arial", 2.80%, false, false, false, false, 5, 1)
</instruct>

<page generalintro>
^For the following task you will be presented two circles of different shades of red.
^^^The left circle is called the BASE.
^The right circle is called the TARGET.
^^^Your task is to adjust the red color of the TARGET so that it matches that of the BASE.
^^=>To lighten the red target component -> Press the '<%parameters.responsekey_up%>' <%expressions.buttoninstruct1%>
^=>To darken the red target component  -> Press the '<%parameters.responsekey_down%>' <%expressions.buttoninstruct1%>
^^^=>Press ENTER when both circles are the same red
</page>

<page end>
You have reached the end of the task.
^^Thank you!
</page>

****************************************************************************************************
general instruction expressions: adjust the instruction text depending on device used to run script
****************************************************************************************************
<expressions>
/buttoninstruct1 = if (computer.touch && !computer.haskeyboard) {"button";} else {"key on your keyboard";}
</expressions>


**************************************************************************************************************
**************************************************************************************************************
	EDITABLE LISTS: change editable lists here
**************************************************************************************************************
**************************************************************************************************************


**************************************************************************************************************
						!!!REMAINING CODE: Customize after careful consideration only!!!
**************************************************************************************************************


**************************************************************************************************************
**************************************************************************************************************
	DEFAULTS
**************************************************************************************************************
**************************************************************************************************************
script requires Inquisit 6.1.0.0 or higher

<defaults>
/canvasaspectratio = (4,3)
/minimumversion = "6.1.0.0"
/ fontstyle = ("Arial", 3%, false, false, false, false, 5, 1)
/txbgcolor = white
/ txcolor = black
</defaults>

*******************************************************************************************************************
*******************************************************************************************************************
	DATA: this section contains data file information
*******************************************************************************************************************
*******************************************************************************************************************

********************
raw data
********************

<data>
/ columns = (build, computer.platform, date, time, subject, group, script.sessionid, blockcode, blocknum, 
trialcode, trialnum,
values.adjustcycles, values.baseline_value, values.target_value, values.direction, values.sequencecount, response, latency,
values.diffthreshold_up, values.diffthreshold_down, expressions.MeanDiffThreshold)
</data>


********************
summary data
********************									
<summarydata>
/ columns = (computer.platform, script.startdate, script.starttime, script.subjectid, script.groupid, script.sessionid, script.elapsedtime, 
script.completed, 
parameters.step, values.adjustcycles, parameters.baselinevalue1, values.diffthreshold1)
</summarydata>

*******************************************************************************************************************
*******************************************************************************************************************
	VALUES: automatically updated
*******************************************************************************************************************
*******************************************************************************************************************

/adjustcycles:						stores the number of adjustment cycles run
/baseline_value:					stores the red color target value of the current base color
/target_value:						stores the red color target value of the current target color
/targetvalue_down:					stores the beginning targetvalue for the current down sequence
/targetvalue_up:					stores the beginning targetvalue for the current up sequence

/sequencecount:						counts how many adjustment sequences have been run per cycle		
/change:							changes in target value
/direction:							1 = Down sequence (sequence starts with targetvalue > baseline value)
									2 = Up sequence (sequence starts with targetvalue < baseline value)

/DiffThreshold_up:					the estimated Difference threshold for the current UP sequence (= starting with
									target value < baseline value)
/DiffThreshold_down:				the estimated Difference threshold for the current DOWN sequence (= starting with
									target value > baseline value)

/sum_DiffThreshold:					add the difference thresholds for the up and down sequences
/DiffThreshold1:					stores the total DiffThreshold of the first adjustment cycle						

<values>
/adjustcycles = 0
/baseline_value = 0
/target_value = 0
/targetvalue_down = 0
/targetvalue_up = 0

/sequencecount = 0

/change = 0

/direction = 0

/DiffThreshold_Up = 0
/DiffThreshold_Down = 0
/sum_DiffThreshold= 0
/DiffThreshold1 = 0
</values>

*******************************************************************************************************************
*******************************************************************************************************************
	EXPRESSIONS
*******************************************************************************************************************
*******************************************************************************************************************

/MeanDiffThreshold:	Average difference threshold for one adjustment cycle (up and down)

<expressions>
/MeanDiffThreshold = values.sum_DiffThreshold/2
</expressions>

*******************************************************************************************************************
*******************************************************************************************************************
	INSTRUCTIONS
*******************************************************************************************************************
*******************************************************************************************************************

<text taskinstruct1>
/items = instructions
/select = 1
/position = (50%, 10%)
/ fontstyle = ("Arial", 3%, true, false, false, false, 5, 1)
/ txcolor = black
/erase = false
</text>

<text taskinstruct2>
/items = instructions
/select = 2
/position = (50%, 20%)
/ fontstyle = ("Arial", 2%, false, false, false, false, 5, 1)
/ txcolor = black
/erase = false
</text>

*******************************************************************************************************************
*******************************************************************************************************************
	STIMULI
*******************************************************************************************************************
*******************************************************************************************************************
<shape base>
/shape = circle
/color = (155, 0, 0)
/size = (30%*3/4, 30%)
/position = (30%, 50%)
/erase = false
</shape>

<shape target>
/shape = circle
/color = (155, 0, 0)
/size = (30%*3/4, 30%)
/position = (70%, 50%)
/erase = false
</shape>

<text baselabel>
/items = labels
/select = 1
/ fontstyle = ("Arial", 3%, false, false, false, false, 5, 1)
/ txcolor = black
/hposition = shape.base.hposition
/vposition = shape.base.vposition + shape.base.height + 10%
/erase = false
</text>

<text targetlabel>
/items = labels
/select = 2
/ fontstyle = ("Arial", 3%, false, false, false, false, 5, 1)
/ txcolor = black
/hposition = shape.target.hposition
/vposition = shape.target.vposition + shape.target.height + 10%
/erase = false
</text>

<shape eraser>
/shape = rectangle
/color = white
/size = (100%, 100%)
/position = (50%, 50%)
</shape>


*******************************************************************************************************************
*******************************************************************************************************************
	LISTS
*******************************************************************************************************************
*******************************************************************************************************************

Note: list randomly selects the down (1) or the up (2) sequence for one adjustment cycle
<list nextdirection>
/items = (1, 2)
/replace = false
/ resetinterval = 1
</list>


*******************************************************************************************************************
*******************************************************************************************************************
	TRIALS: run one adjustment cycle (starting once above and once below baseline value)
*******************************************************************************************************************
*******************************************************************************************************************

Note: trial is run before each new adjustment sequence
- base color and initial target color are determined
and the corresponding shape colors are updated accordingly
- counts are updated
<trial start>
/ontrialbegin = [
	values.direction = list.nextdirection.nextvalue;
	if (values.direction == 1) {
		values.target_value = values.targetvalue_down;
	} else {
		values.target_value = values.targetvalue_up;
	};
	
	values.sequencecount += 1;
	shape.base.colorred = values.baseline_value;
	shape.target.colorred = values.target_value;
	values.change = 0;
]
/timeout = 0
/branch = [
	if (values.direction == 1) {
		return trial.adjust_down;
	} else {
		return trial.adjust_up;
	};
]
</trial>

Note:
- decreases the red color targetonent of the target Color
<trial adjust_down>
/ ontrialbegin = [
	values.target_value -= values.change;
	shape.target.colorred = values.target_value;
]
/ stimulusframes = [1 = taskinstruct1, taskinstruct2, baselabel, targetlabel, base, target]
/validresponse = (parameters.responsekey_down, parameters.responsekey_up, 28)
/monkeyresponse = (parameters.responsekey_down, parameters.responsekey_up, 28)
/ontrialend = [
	values.change = parameters.step;
	if (values.target_value == 255){
		if (trial.adjust_down.responsetext == parameters.responsekey_up) {
			values.target_value -=1;
		};
	} else if (values.target_value == 0){
		if (trial.adjust_down.responsetext == parameters.responsekey_down) {
			values.target_value +=1;
		};
	};
]
/branch = [
	if (trial.adjust_down.response == 28) {
		return trial.end;
	} else if (trial.adjust_down.responsetext == parameters.responsekey_down) {
		return trial.adjust_down;
	} else if (trial.adjust_down.responsetext == parameters.responsekey_up) {
		return trial.adjust_up;
	};
]
</trial>

Note:
- increases the red color targetonent  of the target Color: 
<trial adjust_up>
/ ontrialbegin = [
	values.target_value += values.change;
	shape.target.colorred = values.target_value;
]
/ stimulusframes = [1 = taskinstruct1, taskinstruct2, baselabel, targetlabel, base, target]
/validresponse = (parameters.responsekey_down, parameters.responsekey_up, 28)
/monkeyresponse = (parameters.responsekey_down, parameters.responsekey_up, 28)
/ontrialend = [
	values.change = parameters.step;
	
	if (values.target_value == 255){
		if (trial.adjust_up.responsetext == parameters.responsekey_up){	
			values.target_value -=1;
		};
	} else if (values.target_value == 0){
		if (trial.adjust_up.responsetext == parameters.responsekey_down) {
			values.target_value +=1;
		};
	};
]
/branch = [
	if (trial.adjust_up.response == 28) {
		return trial.end;
	}  else if (trial.adjust_up.responsetext == parameters.responsekey_down) {
		return trial.adjust_down;
	} else if (trial.adjust_up.responsetext == parameters.responsekey_up) {
		return trial.adjust_up;
	};
]
</trial>

Note:
- keeps track of the threshold(s)
<trial end>
/stimulusframes = [1 = eraser]
/timeout = 0
/recorddata = true
/ontrialend = [
	if (values.direction == 1) {
		values.DiffThreshold_down = values.target_value;
	} else {
		values.DiffThreshold_up = values.target_value;
	};

	values.sum_DiffThreshold += values.target_value;
]
/branch = [
	if (values.sequencecount < 2) {
		return trial.start;
	};
]
/posttrialpause = parameters.interadjustmentpause
</trial>

*******************************************************************************************************************
*******************************************************************************************************************
	BLOCKS
*******************************************************************************************************************
*******************************************************************************************************************

Note: block.adjustment1 runs one adjustment cycle (once starting above and once starting below basevalue)
with parameters.baselinevalue1

To run further adjustment cycles, create separate blocks for each of the adjustments 
change -> /onblockbegin = [values.baseline_value = values.baselinevalue2]

and set the baseline values for each of them. Go to EXPERIMENT and add the new adjustment cycles

<block adjustment1>
/onblockbegin = [
	values.adjustcycles += 1;
	values.diffthreshold_down = 0; 
	values.diffthreshold_up = 0; 
	values.sum_diffthreshold = 0; 
	values.sequencecount = 0;
	values.baseline_value = parameters.baselinevalue1;
	values.targetvalue_down = values.baseline_value + (parameters.initialdifference);
	values.targetvalue_up = values.baseline_value - (parameters.initialdifference);
]
/trials = [1=start]
/onblockend = [
	values.diffthreshold1 = expressions.MeanDiffThreshold;
]
</block>

*******************************************************************************************************************
*******************************************************************************************************************
	EXPERIMENT
*******************************************************************************************************************
*******************************************************************************************************************
Note: to run more adjustment cycles add the newly created adjustment blocks
/blocks = [1 = adjustment1] => /blocks = [1 = adjustment1; 2 = adjustment2....]

<expt>
/postinstructions = (end)
/blocks = [1 = adjustment1]
</expt>

*******************************************************************************************************************
												End of File
*******************************************************************************************************************