Expressions

Inquisit supports a variety logical and arithmetic expressions. Expressions are a powerful feature that enable you to create sophisticated and flexible scripts that dynamically adapt based on a wide range of inputs such as the participant's responses, elapsed time, the computer's capabilities, and more. Best of all, expressions allow you to express adaptive scripts in a natural, intuitive way, making it much easier than before to program adaptive tasks.

If you are familiar with imperative programming languages like JavaScript, Java, C#, PHP, or C, Inquisit's expression language syntax will be immediately recognizable to you. Inquisit's basic expression syntax follows the same rules as these other languages.

Simple Statements

If an expression consists of a set of statements, each statement must be delimited by a ";". For example, the following to statements keep a running total of the sum of all response latencies and the total correct responses:

Compound Statements

In addition to simple statements, Inquisit expressions can also consist of compound statments such as "if", "else if", and "else". For example, the following statement updates the sum of latencies only if the response latency falls within a certain range:

Multiple statements can be nested under and an "if" condition by placing the statements inside "{" and "}". In the following example, the sum of latencies and total correct are updated only if the latency falls withing the designated range:

"If" conditionals can be accompanied by "else" statements to designated statements to be executed only if the "if" conditional fails. If the following example, if the response latency falls outside the given range, a value tracking the number of discarded trials is incremented by 1:

"Else if" statements allow you to include multiple conditionals. For example, the following updates a points counter based on speed at which a response that was given, rewarding faster responses with more points:

Operator reference. This topic covers the syntax for mathematical operations such
as addition, subtraction, multiplication, equality. It also covers logical operations
such as tests for equality, inequality, greater than, less than, logical AND, logical
OR, and so on.

Function Reference. Inquisit contains numerous
built in functions that can be used by expressions. Examples include fuctions for
returning the maximum of two values, rounding real numbers to integers, computing
the natural logarithm of a value, and more.

Incorporating expressions into a script

There are a number of different Inquisit elements and attributes that make use of
expressions. The following provides an overview of how expressions can be used in
a script. The reference topics elements and attributes provide more detailed information
on where expressions are valid.

Simple Attributes

Simple attributes are just regular old attributes that can be set to a single numeric
value, or possibly a set of numeric values. For example, the timeout attribute consists
of a single numeric value, for example /timeout = 1000. The size attribute consists
of two numeric attributes, for example /size = (200, 300). Inquisit allows
you to set these attribute values to either
a constant number such as "5" or a numeric
expression such as "sqrt(5) + 22 - text.target.currentitemnumber".

As an example, imagine you are running a task in which subjects try to answer as
many questions as possible in 5 minutes. When their time is up, the current trial
is interrupted and no more trials are run. One way to achieve this is to set the
timeout of each trial as a function of the time elapsed since the task started.
This might look like the following:

The above example computes the number of milliseconds remaining in the 5 minute
period by subtracting the number of milliseconds that have elapsed since the start
of the block from 18000000, which is the number of millisecond in a 5 minute interval.

There is a problem with this expression however, namely that it might return a negative
number, which is not a valid timeout value, or it might return 0, which Inquisit
interprets to mean no timeout at all. We can fix this by uses Inquisit's "max" function,
which returns the maximum value of two expressions. The following ensures that the
timeout is never set to a value less than 1 millisecond.

Event Attributes

Inquisit 5 introduces a set of event attributes that allow you to execute logic
at a particular time in the experiment, such as at the beginning or end of a certain
type of trial or block. These attributes allow you to configure aspects of the script
based on prior performance or tally up custom scores and metrics. Event attributes
include ontrialbegin, ontrialend, onblockbegin, onblockend, onexptbegin, and onexptend.

As an example, imagine a decision making task in which you award points based on
correct decisions. There are two types of decisions, a relative easy type worth
2 points and a harder type worth 5
points. Using the ontrialend attribute, this is easily accomplished.

Note that the trial.easydecision.correct property is set to 1 for a correct response
and 0 for an incorrect response, so we can simply multiply this property by 2 and
add the result to the score. Another way to accomplish the same thing would be to
use conditional logic as follows.

Task Flow Attributes

Task flow attributes allow you to conditionally determine the flow of a procedure based on prior performance. For example,
a script might repeat a practice block of trials until the percent of correct responses meets some criteria before moving
on to the critical blocks. Another script may skip a certain type of trial based on the response to a previous question. Flow attributes include branch, skip, repeat,
and stop.

As an example, imagine you wish to provide adaptive feedback to participants based
on how well they perform a task. Specifically, if they make 5 correct responses
in a row, they are shown a message of encouragement. If they make 3 incorrect responses
in a row, they are shown a message warning them to slow down and concentrate on
the task.

First, we'll define the two trials used to display the encouragement and warning
feedback. Note that since these are just feedback trials, we use the recorddata
command to prevent the data from these trials from being added to the data file.

The first branch
uses the mod function, which returns the remainder when the first argument, trial.maintask.correctstreak,
is divided by the second argument, 5. If the correctstreak is a multiple of 5 (e.g.,
5, 10, 15, ...), the remainder is 0 and the first statement in the condition is
true. However, the mod function also returns 0 if the correctstreak is 0, in which
case we don't want to show the encouragement trial. So, a second statement checking
whether the correctstreak is 0 has been added. Now the encouragement trial is run
after ever streak of 5 correct responses.

The second branch
is similar, except that it shows a warning trial for every streak of 3 incorrect
responses.

Stimulus Items

Expressions can also be incorporated into stimulus items in order to be displayed on the screen.
For example, a text stimulus might include expressions representing their performance, a score,
or the amount of time remaining in a task. In order to distinguish regular text from text that
should be evaluated as an expression, expressions must appear between <% and %>. Anything appearing between these delimiters will be evaluated as an expression. Otherwise, the text is displayed as is.

The following example shows a text item that displays a participant's total score on a judgment and decision making task by adding subscores from phase 1 and 2:

The following text shows the number of minutes that have passed since the start of the session. Since the script.elapsedtime property returns the duration in millisecond, the value is divided by 60000 and rounded to the nearest integer to convert it to minutes:

Instruction Pages

Just like stimulus items, expressions can also be inserted into instruction pages. Again, anything appearing between expressions must appear between <% and %> is evaluated as an expression. Otherwise the text or html is displaed as it is.

The following instruction page shows the mean latency on a block rounded to the nearest integer.