Manipulating text with variables

Psychstudio comes with some very powerful and expressive text manipulation tools built in, perfect for use in psycholinguistic experiments and linguistics studies.
Variables allow for complex manipulation of text items and can be used in the following ways:

  • can be applied to any part of a text item.
  • can be nested.
  • can be applied to other variables.
  • multiple variables can be applied to the same part of a text item (including application to other variables).
  • can be used to inject sections of text into a text item.

Variable notation is of the form: $(variable-name ...).

Adding a variable to the component group

Click New in the in the variable column in the variable manager. Give the variable a name, select the variable type from the dropdown list provided and set the variable strategy:

  • Exclusive: values will only be allocated once per stimulus cycle (i.e. once a value from this variable has been allocated to a text item, that value will not be available for allocation to any other text item).
  • Non-exclusive: values can be allocated zero, one or multiple times per stimulus cycle (i.e. a value from this variable can be allocated to multiple text items).

Removing a variable from the component group

Variables can be deleted by clicking on Delete (or D in a small panel) on the undesired variable (i.e. one with a name and strategy value).

WARNING: Deleting a variable will remove:

  • any trials rules containing values belonging to the variable.

Adding a value to a variable

Click New in the in the value column of the desired variable in the variable manager and give it a value. Variable values are allocated to their assigned text items randomly.

Removing a value from a variable

Variable values can be deleted by clicking on Delete (or D in a small panel) on the undesired value (i.e. one without a name and strategy value).

WARNING: Deleting a variable value will remove:

Insert text into a text item (a.k.a. text injection, variable substitution)

Injecting text into a text item is referred to as variable substitution. To inject text into an item, we first need to specify a variable in the text item where we wish the injection to take place. As shown in the example below (Figure 1) we have some text items, three of which have a variable called person and two which have a variable called place. The notation for text injection is simply $(variable-name).

Figure 1. Example text items with injection variables

In the variable manager (Figure 2), we have created some variables with values to inject into their corresponding text items, for example, a text item containing $(place) will be randomly allocated a value from the place variable. For example, when composed, the text item and variable together will produce: It's busy and crowded in the town of Kimpy. I call it ...

Figure 2. Example variables with values

Formatting a text item

Variables can used to selectively format parts of text items. The notation for text formatting is: $(variable-name text).
Variables can also be nested like so: $(variable-name some text $(variable-name2 some more text)). Specificity of application of nested variables is:

  1. global (set by editing the stimulus component on the trials timeline).
  2. innermost to outermost.
So in the nested example above, variable-name2 will take precedence over variable-name.

The following formatting variable types are available:

Let's take a look at a classic, yet simple example, the Stroop task (ignoring levels for brevity). As shown below (Figure 3), we have five text items and a single variable ink-color (of the type Font color) with five values.
The first text item is $(ink-color Brown), which can be described as: the variable ink-color applied to the text Brown. For example, when composed, the text item and variable together will produce: Brown, which can be described as the word Brown with the variable ink-color and (random) value blue applied.

Figure 3. Example text items and variables (Stroop task)

Finally, let's look at a little more complex and completely contrived example:
The $(strike? quick) $(italic? brown $(ink-color $(animal))) jumps $(bold? ($(background over)) the) lazy $(animal).
When composed, we might end up with something like: The quick brown dog jumps (over) the lazy fox.
Note: strike? italic? and bold? are all boolean type values (i.e. either true or false).
TIP: for weighted booleans you can add uneven numbers of true and false values to the variable (e.g. three true and one false).