ZEP Magic variables

If you have suggestions on how to improve this document, or find mistakes, please send them to ilslabs@nulluu.nl

Zep’s magic variables

The purpose of the magic variables

Zep has a number of variables that make Zep very flexible and look consistent with other Zep experiments. This way, you can change many labels from English to Chinese for example just by importing another module. Using modules in Zep makes a Zep experiment recognizable from miles away and quite flexible. Although this seems very cool, it does use many variables that you didn’t write yourself and makes you wonder: “where the heck do they come from, it is almost magic?”

This tutorial aims to explain the modular setup of a Zep experiment. It demonstrates how you can import modules and shows where are all those magic variables are declared and defined. If you understand this, you know that Zep has a certain philosophy that mandates the use of these variables. You don’t have to use them, and yes you can do it your own way. However, by understanding the way Zep works, you don’t have to reinvent the wheel and it will make your life a bit easier, or at least the part of your life that you are using Zep.

With this tutorial comes a zip file with 2 “experiments” where the use and magic of Zeps variables are explained. This tutorial is written with Zep-1.16 as reference. So if you want to complete this tutorial you can download the zip archive from this page. Tutorial1 and 2 use the magic1 and magic2 folders respectively. These are folders in the zip-file.

This tutorial assumes you have read/understood the previous Zep tutorials (if not read the ZEP-tutorial-for-linux or ZEP-tutorial-for-windows first). So when it asks you to open a Zep file or module, use a programmers editor. A rich text editor like Word or Open/Libre office is not suitable for programming. The wealth of characters that Word adds to a Zep script creates evil — or,  more likely– invalid Zep syntax and your Zep script simply won’t run. Now we will start with the first tutorial in this session.

Tutorial 1

Have a look at the magic1 folder. In the folder, you find a very small experiment that still does a lot. It’s called magic1.zp. Open magic1.zp in an editor. On top of the script you see a import section where the module std_windows1.zm is imported. When you run the script the Experimental Control window pops up. Well, the control window is actually imported by the import std_windows1.zm; command.

• To demonstrate this, comment the line containing the import statement away.

Run the experiment again and notice nothing is happening. There is no control window popping up and nothing seems to change (Zep is just waiting for events to occur, but no events that Zep is monitoring occur, so Zep keeps waiting forever). Make sure the keyboard focus is on the terminal and press ctrl+c to terminate the experiment. In normal circumstances you would have used alt + f4 however, since there is no window, there is nothing in Zep that can capture alt+f4, so you would close your terminal instead. Make sure the module std_windows1.zm is imported properly again and test whether the script is working once more and if the control window is displayed.

Now we are going to do one more manipulation to this simple experiment. On line 29 (if you didn’t remove or add lines) we are going to rename the Experiment to test. So change Experiment experiment to Experiment test, and run the experiment. You’ll see tons of errors appearing on the terminal and the program won’t run at all. And all of these error mention something like “Undefined field ‘experiment’”. Now that is weird, what is happening!? The answer lies in the “philosophy” of Zep. It is “telling” you now that if you want to use the Control Window to start your experiment, you need an Experiment called experiment.

The take home message is: Zep uses modules that do a lot for the programmer. The entire control window is a Zep module entirely written in the Zep language, and you can import it by writing one line import std_windows.zm;. Once you use this module, you need to start thinking in the Zep mindset. That philosophy dictates, that if you want to use the control window, you also have to create an Experiment called experiment. This makes Experiment experiment one of the magical variables of Zep.

Tutorial 2A

The next tutorial is about using extra variables and modules of Zep that are typically used in an experiment. Navigate to the magic2 folder.
In this tutorial a slightly more elaborate “experiment” is developed to familiarize you with a number of variables that are used often. The goal of this tutorial is to know what you should do in order to change the language of the experiment as presented to the participant. There are also a number of other variables that are typically used to determine colors. To use these variables we need to import a few more modules.
In the folder magic2 open the magic2.zp file in an editor. Scan the import section of the experiment.

• The purpose of module std_windows1 has been explained in the part “Tutorial 1”. Each of the new imports is commented. Think about or write down the purpose of the modules std_entry_page1, std_exit_page1, std_pause_page1, std_blank_page and std_texts_en. What do you think that these modules accomplish?

To get an idea what the experiment looks like I would suggest to run the experiment quickly and step through it until the thank you message has been presented and the experiment finishes. Between the welcome and goodbye pages there were 4 stimuli and a continue button. Although the layout on the screen was correct, the four stimuli looked very different. Only the upper left stimulus is presented in the way it should. Therefore, in the map test open the test_page.zm file and scan through it. You should be able to locate four TextShapes. Only the shape in the upper left corner is programmed in such way that it will look consistent.

• So find the other three shapes and modify them to look consistent with the upper left one.

Make sure you use the right variables and don’t fill out constants (such as the “42” with the font size of the lower right stimulus). If you fill out a number such as 42, you have hard coded the variable. Therefore it isn’t variable anymore, but a hard coded constant. The next part of the tutorial will make clear why it is important to use variables and not hard coded constants.

• Run the experiment and adapt your code as many times needed to make sure all 4 stimuli look identical.

Tutorial 2B

The default values (or implementations of pages etc.), as provided by Zep, are not always right for your current purpose. Zep understands this too. Say, you don’t want to display “Welcome”, to welcome the participant to your experiment, but “Welcome to this experiment” instead. Or even nicer, we expect that our participants read Chinese better then English and therefore we want to display standard texts in Chinese. We’ll first look into this last part, because this is the easiest.

In the previous section you have seen that more modules were loaded. For example std_texts_en. This loads the default text module for the English language. This module contain the values for many text strings that are regularly  used in an experiment. Say now you want the experiment to be presented in another language.

• In the file magic2.zp change import std_texts_en; to import std_texts_cn;.

Run the experiment once more. Notice how all default strings, the ones you didn’t fill out manually but that are defined in a variable, automatically change to the Chinese language. To achieve this, you only needed to change 2 letters in the experiment. You changed “en” to “cn” while importing the language module. If you would have used constants instead of the variables from the std_texst_xx modules, you would have to look up all the constants through out the experiment in multiple files and change them manually. Now this “experiment” is very small, so it is doable. However, real life experiments or programs could use dozens (or hundreds, thousands) of places where such changes must be inserted. The job might become a hassle. Or worse, you might forget a few occasions and only notice it once you are conducting your experiment for real.

The final part of this tutorial is about changing the default values for the for an experiment. You might think I don’t want to say “Welcome” to welcome the participant but “Welcome to this experiment”. To do this we are going to obtain a copy of the modules that are distributed with the Zep program. If you are on Linux find the folder /usr/share/zep/<version>/modules/. Replace “<version>” with the version of Zep that you are running eg. “1.16”. If you are on Windows locate C:\program files( x86)\zep\<version>\modules\; use “x86” if you installed the 32 bits version of Zep and without x86 if you installed the 64bits version of Zep. The modules are always in the directory where you installed Zep. This directory is the system module directory, all modules that can be imported are located there. It is the system modules directory since changes there would affect all experiments of Zep (with the same version). Modules have a .zm filename extension and contain Zep code.

• In the system modules directory locate the std_texts_en.zm file and copy it in the modules directory of your experiment directory (it should already exist and be empty).

This is your experiments module directory, all changes to the modules there only affect your current experiment. Now you have copied the file in your experiments module directory Zep will first look there to load a module and if it can’t find it there, it tries to import it from the global module directory. The file std_texts_en.zm in your experiments modules directory is only relevant to your specific experiment. So now you can change it as you wish. In magic2.zp multiple variables are noted as having magical properties, denoted with <magic> for the purpose of this tutorial. Find them in magic2.zp and find their counterparts in your own std_texts_en.zm file (here they are not denoted). Run the experiment and make sure you see the English texts/lines, if you don’t see them fix them.

• Now you can change the strings in your the modules folder of your experiments directory. So change the welcome message to “Welcome to this experiment”.

If this message is too long for your monitor you can look at the goodbye message how to solve this.

Conclusion

The Zep magic variables are sometimes difficult to pinpoint were they come from. Some variables are build in to Zep, but most come from the modules that are shipped with Zep. Once you know how to use them successfully, you are able to make drastic changes to the experiment with just importing another module. The approach taken remains flexible, because you can put the system module in the modules directory of you own experiment and make changes to your specific experiment. All in all, this makes Zep both flexible and powerful.

This tutorial touched some of the magic variables of Zep, but there are many more. So in the future when using Zep, if you are confused about where a variable is defined, you can look through the modules listed in the system Zep modules.