# Functions

The Inquisit expression language includes a number of commonly used mathematical functions that perform various calculations, from rounding decimal numbers to the nearest integer to computing a number's arctangent.

Function Description Examples Result
abs Returns the absolute value of the argument

abs(-1)

1
mod Returns the floating point remainder when the first argument is divided by the second mod(1.33, 1)
mod(9, 4)
0.33
1.0
ipart Returns the integer portion of a floating point argument

ipart(3.14)

3
fpart Returns the fractional portion of a floating point argument

fpart(3.14)

0.14
min Returns the minimum value of the arguments min(0, 1, 2, 3)
min(-100, -1000)
0
-1000
max Returns the maximum value of arguments max(0, 1, 2, 3)
max(-100, -1000)
3
-100
pow Returns the first argument to the power of the second argument pow(3, 3)
pow(10, 2)
27
100
sqrt Returns the square root of the argument sqrt(4) 2
sin Returns the sine of the argument sin(1.570796) 1
sinh Returns the hyperbolic sine of the argument sinh(1.570796) 2.301299
asin Returns the arcsine of the argument
cos Returns the cosine of the argument cos(1.570796) 0
cosh Returns the hyperbolic cosine of the argument cosh(1.570796) 2.509178
acos Returns the arccosine of the argument
tan Returns the tangent of the argument tan(0.785398) 1
tanh Returns the hyperbolic tangent of the argument tanh(1.000000) 0.761594
atan Returns the arctangent of the argument atan(5.0) 1.373401
atan2 Returns the arctangent of the first argument divided by the second argument atan2(5.0 / 5.0) 0.99669
log Returns the base 10 logarithm of the argument log(9000.00) 9.104980
ln Returns the natural logarithm of the argument ln(9000.00) 3.954243
exp Returns the exponential values of the argument exp(2.302585) 10.0
logn Returns the logarithm of the first argument using the second argument as the base
round Rounds the argument to the nearest integer round(1.49)
round(1.50)
1
2
ceil Rounds the argument up to the nearest integer ceil(1.49)
ceil(1.50)
2
2
floor Rounds the argument down to the nearest integer floor(1.49)
floor(1.50)
1
1
deg Converts an argument from radians to degrees
rand Generates a random number within a given range rand(0, 1)
rand(0, 100)
0.55678
97.12314
randgaussian Generates a random number from a guassian distribution with the given mean and sd randgaussian(50, 16)
randgaussian(0, 10)
55
-4.33

### Examples

The following block rounds the mean latency down to an integer and saves it to a value:

<block myblock>
/ trials=[1-5=practicetrial; 6-10=testtrial)]
/ onblockend=[values.simplemean = round(block.myblock.meanlatency)]
</block>

The following block finds the best performance from 3 different trial types and saves the result to a value.

<block myblock>
/ trials=[1-300=noreplace(t1, t2, t3)]
/ onblockend=[values.bestscore = max(trial.t1.percentcorrect, trial.t2.percentcorrect, trial.t3.percentcorrect)]
</block>

## Selection Functions

The following table lists functions for selecting randomly or otherwise from a pool of values.

Function Description Examples
noreplace Randomly selects without replacement from a set of values noreplace(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
noreplace(0, 2.5, 5, 7.5, 10)
noreplacecorrect Randomly selects without replacement if a correct response is given and with replacement if an incorrect response is given

noreplacecorrrect(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
noreplacecorrect(0, 2.5, 5, 7.5, 10)

noreplaceerror Randomly selects without replacement if an incorrect response is given and with replacement if a correct response is given

noreplaceerror(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
noreplaceerror(0, 2.5, 5, 7.5, 10)

noreplacenorepeat Randomly selects without replacement or consecutive selection fo a value noreplacenorepeat(10, 20, 30, 40, 50, 60, 70, 80, 90, 100)
noreplacenorepeat(0, .3333333, .6666667, 1)
replace Randomly selects with replacement from a set of values replace(10, 20, 30, 40, 50, 60, 70, 80, 90, 100)
replace(0, .3333333, .6666667, 1)
replacenorepeat Randomly selects with replacement if an incorrect response is given and with replacement if a correct response is given replacenorepeat(10, 20, 30, 40, 50, 60, 70, 80, 90, 100)
replacenorepeat(0, .3333333, .6666667, 1)
sequence Selects the items in the specified order sequence(10, 9, 8, 7, 6, 5, 4, 3, 2, 1)
sequence(2, 4, 6, 8, 10)
getitem Returns the item at the specified index. getitem(counter.deck, 1)
getitem(text.presenteditems, text.presenteditems.itemcount)
getitem(item.useritems, item.useritems.itemcount - 1)
setitem Sets the item at the specified index to the specified value. setitem(counter.deck, values.currentcard, 10)
setitem(text.presenteditems, text.targets.currentitem, text.presenteditems.itemcount)
setitem(item.useritems, values.firstresponse, 1)
insert Inserts an item of the specified value into the specified index. insert(counter.deck, values.currentcard, 2)
insert(text.presenteditems, text.targets.currentitem, 1)
insert(item.useritems, values.firstresponse, 1)
remove Removes item at the specified index. remove(counter.deck, 10)
remove(text.presenteditems, text.presenteditems.itemcount)
remove(item.useritems, item.useritems.itemcount - 1)
clear Removes all items from a stimulus or counter. clear(counter.deck)
clear(text.response)
clear(item.useritems)
reset Resets a counter. If the counter selects without replacement, all items are returned to the selection pool. If selection is sequential, the first item in the pool is selected next. reset(counter.odds)
reset(picture.faces)

### Examples

The following stimulus will be presented in a randomly selected position on the screen:

<picture mypic>
/ items = ("foo.jpg")
/ hposition = replace(0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 100%)
/ vposition = replace(0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 100%)
</picture>

The following trial has a response timeout that gets 50 milliseconds shorter each time the trial is run.

<trial mytrial>
/ stimulustimes = [1=target]
/ timeout = sequence(1000, 950, 900, 850, 800, 750, 700, 650, 600, 550, 500)
/ response = ("a", "b")
</block>

## String Functions

The following table lists functions for analyzing and manipulating strings of text.

Function Description Examples Result
tolower Converts all alphabetic characters in the string to lower case. tolower("TURNIPS")
tolower("Sales@Server.Com")
turnips
sales@server.com
toupper Converts all alphabetic characters in the string to upper case. toupper("turnips")
TURNIPS
capitalize Converts the first letter of each word in the string to upper case. This is useful for presenting proper nouns entered by the participant. capitalize("john")
capitalize("bill gates")
capitalize(tolower("dIET cOKE"))
John
Bill Gates
Diet Coke
concat Contenates two strings together.

concat(concat("United", " "), "States")

United States
search Searches the first string for any occurence of the second string. If the string is found, it returns the zero based index of the first occurence. If the string is not found, it returns -1. search("benjamin", "ben")
search("benjamin", "benji")
search("benjamin", "jamin")
0
-1
3
replaceall Searches the first string for all occurrences of the second string and replaces them with the third stringFinds all occurences of the Randomly selects with replacement from a set of values replaceall("Hello %name%", "%name%", "Julia")
replaceall("old old old", "old", "new")
Hello Julia
new new new
contains Returns true if the first string contains the second string, otherwise false.

contains("sales@server.com", "@")
containst("http://www.millisecond.com", "@")

true
false
startswith Returns true if the first string starts with the second string. startswith("http://www.millisecond.com", "http://")
startswith("Four score and seven years ago", " ")
true
false
endswith Returns true if the first string ends with the second string. endswith("All's well that ends well.", ".")
endswith("Why did the chicken cross the road", "?")
true
false
substring Returns a portion of the string starting at the specified start index and of the specified length substring("www.millisecond.com", 4, 11) millisecond
trim Trims the characters in the second string from the beginning and end of the first string trim(" hello ", " ")
hello
trimright Trims the characters in the second string from the right side of the first string trimright("Get into the chopper!", "!?.")
Get into the chopper
trimleft Trims the characters in the second string from the left side of the first string trimleft("\$1.00", "\$"))
1.00
length Returns the length of the string length("123")
length("54321")
3
5
format An advanced function that allows string substitutions and formatting of decimals using format strings as used by the C function printf. format("You have %i points", 16)
format("%.2f", 3.14159265)
You have 16 points
3.14
evaluate An function that evaluates a string as an expression and returns the result. evaluate("(1 + 6) * 5")
evaluate(text.mathproblems.currentitem) - evaluate(text.mathproblems.currentitem)
35
0

### Examples

The following stimulus will be presented in a randomly selected position on the screen:

<surveypage mypage>
/ caption = format
/ questions = [1=firsname; 2=lastname]
/ ontrialend = [text.firstname.item = capitalize(lower(textbox.firstname.response))]
</surveypage>

The following trial has a response timeout that gets 50 milliseconds shorter each time the trial is run.

<block myblock>
/ trials = [1-100=test]
/ branch = [if( contains(textbox.college.response, "Cornell") == true ) block.next]
</block>

## Performance Metric Functions

The following table lists functions that calculate performance metrics and statistics. Many elements contain properties corresponding to these functions. The benefit of the functions is that they can compute performance metrics for combinations of elements, whereas the property returns the metric for its element only.

Consider, for example, a task involving two types of trials, a target trial and distractor trial. Using the totalpercentcorrect property, we can get the percent of correct responses on either trial element. Specifically, the expression "trial.target.totalpercentcorrect" returns the percentage for target trials, and "trial.distractor.totalpercentcorrect" returns percentage for distractor trials. What if we want the percent correct for both types of trials. For this, we can use the totalpercentcorrect function. Specifically, the expression "totalpercentcorrect(trial.target, trial.distractor)" will return the percentage for the combined set of trials. These functions can be used to compute metrics for any arbitrary combination of elements.

Function Description Examples
correctcount number of correct responses in the current block correctcount(trial.targeta, trial.targetb, trial.targetc)
count number of times the item was run within the current block

count(trial.foo, trial.bar, trial.foobar)

errorcount number of incorrect responses in the current block errorcount(trial.red, trial.green, trial.blue)
inwindowcount number of responses occurring within the response window in the current block inwindowcount(trial.category1, trial.category2)
maxlatency maximum response latency in the current block maxlatency(trial.leftlow, trial.lefthigh, trial.leftmid)
meanlatency mean response latency in the current block meanlatency(trial.leftlow, trial.lefthigh, trial.leftmid)
minlatency minimum response latency in the current block minlatency(trial.leftlow, trial.lefthigh, trial.leftmid)
notinwindowcount number of responses occurring outside the response window in the current block notinwindowcount(trial.category1, trial.category2)
percentcorrect percent of correct responses in the current block percentcorrect(trial.stroopredred, trial.stroopgreengreen, trial.stroopyellowyellow, trial.stroopblueblue)
sdlatency standard deviation of response latencies in the current block sdlatency(trial.leftlow, trial.lefthigh, trial.leftmid)
sumlatency sum of response latencies in the current block sumlatency(trial.leftlow, trial.lefthigh, trial.leftmid)
selectedcount number of selected items selectedcount(item.targets, item.distractors)
totalcorrectcount total number of correct responses totalcorrectcount(trial.critical, trial.test)
totalcount total number of times the item was run so far totalcount(trial.soa100, trial.soa300, trial.soa500)
totalerrorcount total number of incorrect responses totalerrorcount(trial.critical, trial.test)
totalinwindowcount total number of responses occurring within the response window totalinwindowcount(trial.congruent, trial.incongruent, trial.neutral)
totalmaxlatency maximum response latency totalmaxlatency(trial.leftlow, trial.lefthigh, trial.leftmid)
totalmeanlatency mean response latency totalmeanlatency(trial.leftlow, trial.lefthigh, trial.leftmid)
totalminlatency minimum response latency totalminlatency(trial.leftlow, trial.lefthigh, trial.leftmid)
totalnotinwindowcount total number of responses outside the response window totalnotinwindowcount(trial.congruent, trial.incongruent, trial.neutral)
totalpercentcorrect percent of correct responses totalpercentcorrect(trial.bigtargeta, trial.bigtargetb, trialbigtargetc)
totalpercentinwindow percent of responses within the response window totalpercentinwindow(trial.congruent, trial.incongruent, trial.neutral)
totalsdlatency standard deviation of response latencies totalsdlatency(block.critical1, block.critical2)
totalsumlatency total sum of response latencies totalsumlatency(trial.leftlow, trial.lefthigh, trial.leftmid)
totaltrialcount total number of trials run totaltrialcount(block.training1, block.training2)
totalvarlatency variance of response latencies totalvarlatency(trial.leftlow, trial.lefthigh, trial.leftmid)
trialcount number of trials run within the current block trialcount(trial.congruent, trial.incongruent)
unselectedcount number of unselected items unselectedcount(picture.target1, picture.target2, picture.target3)
varlatency variance of response latencies within the current block varatency(trial.leftlow, trial.lefthigh, trial.leftmid)