How-tos
Adding, deleting or replacing stimuli in ZEP
If you have suggestions on how to improve this document, or find mistakes, please send them to labman.gw@uu.nl
When using ZEP, you often have to add your own stimuli. When you download an experiment from the website, example stimuli are given, but you probably want to test with your own set of stimuli. When an experiment is tailored to your needs, or created for you from scratch, the programmers will often leave adding the stimuli to yourself.
In ZEP, stimuli can be added in two different ways. Either in the script itself, in the stimuli.zm ZEP-module, or in a seperate CSV file, which will then be located somewhere in the stimuli folder.
Which of these methods you have to use, depends on how the experiment was programmed. The easiest way to check is to go to the stimuli folder in your experiment, and to check if there is a CSV-file there somewhere. If there is, you have to use this file. If there isn’t, you have to change the stimuli in the code of the stimuli.zm module itself.
How do stimuli work?
In ZEP, the stimuli are given as a list of items. Each of these items have the same attributes. Regardless of the script, the first attribute, which is called the id, is always there. The rest of the attributes differ per experiment.
The type of an attribute is defined in the code of the stimuli.zm module. The value of this attribute has to be of that type for each of the stimuli in the list. The type can be written text, a whole number, a floating point number, a boolean (either true or false), or any user defined type. If you give a value to an attribute of an item that does not correspond to the type, ZEP will not run your experiment. You should never change the type of an item or an attribute, because this type is required by many other parts of the program. If you use the wrong type somewhere, it is better to change the value that results in an error to something of the correct type.
Attributes can be all sorts of things. In the simplest experiments, an important attribute is a word that is shown. These words will be entered as a string, enclosed in quotation marks. Another example of an attribute can be the name of a sound file that has to be played, an entire sentence, or an image that is to be shown.
Changing the stimuli
Regardless if you use CSV files or are defining the stimuli array in the stimuli.zm method you use (CSV or in the code itself), the best practice is to use the existing stimuli as an example for how you should enter your own.
Open the file stimuli.zm which is located in either the modules or test folder with a plain text editor. On Linux, you can use Gedit; on Windows, you can use either Notepad or Notepad++.
Somewhere in this file, you will find something that looks like this:
record TestItem{
int id; // item id
ItemType type; // item type
string word; // The word that is shown
}
The first line, ‘record TestItem’, defines a new type for the testitems (the stimuli). You won’t have to change this, but you can look at it, to get an idea of which types are used. In this example, each stimuli you add has 4 attributes. In the code above, the first column shows the type of the attribute, the second column shows the name of the attribute and the third column, everything after the double forward slashes (//) indicates a comment, meaning ZEP will ignore whatever follows the double forward slashes. Comments are useful to give hints to humans reading the code and in this case, they give a description of the attribute.
Further on in the program, you will find something for ‘TestItem[..] test_items’ (and often prac_items as well). The prac_items are the stimuli used in the practice round and the test_items are used during the actual test.
It might look something like this:
TestItem[..] test_items =
{
{1, NON_WORD, "slirque"},
{2, NON_WORD, "crawse"},
{3, NON_WORD, "thwurp"},
{4, NON_WORD, "clem"}
}
This code means that test_items is a list of stimuli of the type TestItem. This type was defined before in record TestItem and requires exactly the attributes as given there.
The list is surrounded by curly brackets (‘{‘ and ‘}’) and each of the items in the list is separated by a comma. Each of the items is also surrounded by curly brackets and each of the attributes in each of the items are also separated by a comma. The first attribute is the id, which is defined to be an int, meaning it is a whole number, going from 1 to the number of items in the list. The second attribute is, in this case, the type of the stimulus. The last attribute is the word that is shown to the participants. These are just examples, and in other experiments many more and different attributes could be used.
If the value of an attribute in any of the existing stimuli is not written in between quotation marks, you only have a limited number of options for that attribute. In the place of NON_WORD, for example, you can only put NON_WORD itself, or REAL_WORD. The available options for the attribute are also defined in the code. To see what those options are, try to find the type for that attribute and look through the file to see what options are given to that type. For the NON_WORD attribute, it would look like this:
enum ItemType{
REAL_WORD, // A real word
NON_WORD // A non-word
}
Once you are sure you know how to fill in each of the attributes, you can replace the existing stimuli with your own ones. Make sure each of the stimuli have the same number of attributes and that you do not forget any of the brackets, quotation marks or comma’s. If you make a mistake here, ZEP will not start, but you can use the error it gives you to track where you made a mistake and then correct it.
When the stimuli are saved in a CSV file, you won’t have to open any of the code. You can just navigate to the CSV-file in an explorer and then open it with either Microsoft Excel or LibreOffice Calc.
Once you have opened the file, you should see a normal spreadsheet layout consisting of rows and columns. Each of the columns is reserved for a predefined attribute of the stimuli and each of the rows, sometimes with the exception of the first few, define a single stimuli.
Do not change any of the rows that do not start with a number. Only the rows that start with a number are rows that define the stimuli. The number of rows before the stimuli should stay unchanged, so make sure not to touch them.
In each of the other rows, you can now replace the columns to create your own stimuli. The type of the information should remain the same, so if a column consists of numbers, you should use numbers, if a column consists of the words ‘true’ or ‘false’, you can only use ‘true’ or ‘false’ in that column and if a column only contains all capital words, only those words can be used in that column and only one of these per field. If a column contains other text, you can replace it with your own text. Use the headers (the titles of the columns) as an indication of what the column does if you are unsure. You also have to make sure the first stimuli has 1 as the id attribute and the following stimuli count upwards from 1.
You can use any number of stimuli. If you want to add more than there already are, just create a new row for each of the new stimuli. If you want to remove the stimuli, just remove the entire row.
Once you are satisfied with the new stimuli you entered, you can click ‘save’. Then run the experiment. You won’t have to close the CSV file for this. If you made a mistake somewhere, ZEP will not be able to start the experiment. You can use the errors ZEP gives you to see which lines are the problem and then fix those errors. If ZEP runs, but the stimuli isn’t presented the way you had expected, this will also have to do with the way you entered the stimuli and you can then fix that in the CSV as well.
Once you are sure you have entered all the stimuli you want to use and they work as expected, you can close your CSV file. And then you are done.