Inquisit Tutorial

In this tutorial you’ll program a bit yourself. We’ll take baby steps, don’t worry. Every time you see the  symbol, it means you have to start typing yourself at that point, before you go on reading. At the end of the tutorial you will have made your first experiment with Inquisit.

First some practical information. You start Inquisit from the Start menu (All programs, Inquisit 4). The experiment you create will be written in a file called a script. A script file has the extension .exp. Double-clicking such a file will automatically start Inquisit and run the experiment. If you want to edit the file, open it from within Inquisit. If you want to try out your experiment, go to Experiment in the menu, and click Run. To interrupt an experiment, press Ctrl + Q.

When running the experiment, Inquisit will automatically create a data file with the same name, but using the .dat extension containing the responses and reaction times of participants in your experiment.

Bottom-up decisions

So now you loaded Inquisit and see an empty white window in front of you. How do you get from here to a working experiment? First you will need to make a few decisions. The most important one is of course deciding on the experimental paradigm, and then you start programming the paradigm from the bottom up. Let’s say you want to know whether participants have an implicit preference for flowers versus spiders. One possible experimental paradigm would be an IAT with words and names (although in this case pictures might work better, but to keep things easy, we’ll stick to spider and flower names). The next steps are the bottom-up decisions. Think about the possible answers you could give at each step:

  • Stimuli: What kind of stimuli would you need? Which categories? Think of some examples.
  • Trials: What kind of trials do you need? What does a trial look like? What is the order and timing of the stimuli? What kind of responses can a participant give? When is a response the right one? What happens if the participant responds incorrectly?
  • Blocks: How are the trials ordered in blocks? What are the instructions for each block?
  • Experiment: How are the blocks ordered? How does this depend on conditions? How are conditions selected?

On each level of the bottom-up thought process there is an Inquisit counterpart that you need to program. I recommend that when you program, you start out programming the experiment in this same bottom-up order.

Stimuli

So let’s decide on some stimuli. For the IAT we have in mind, we need four different categories of stimuli: spider names, flower names, positive words, and negative words. We will now actually program these stimuli in Inquisit. To tell Inquisit that we have some negative words that form a category of stimuli enter the following text in the open window:

<item negative>
 /1 = “tragic”
 /2 = “horrible”
 /3 = “awful”
 </item>

Take a closer look at the text you just entered. The first and last lines are called tags. The first line is an open-tag that tells Inquisit that the lines below, until the close-tag on the last line are items to be used as stimuli. The item part on the first line is called the element. There are multiple types of elements, for each of the different bottom-up steps. We will come across many of them. In the open-tag the second part is a name which you will use in the rest of the script to refer to the information contained in this specific tag (note: these names are case-sensitive). The close-tag always repeats the element, in this case item, but with a slash before it, marking it a close-tag. The lines between the open-tag and close-tag contain the actual stimuli. Every line within tags always start with a slash, indicating so-called attributes. Different elements have different attributes. You will see many of them as we go. In the case of item elements, the attributes are actually stimulus numbers, with the words between the quotations marks being the actual stimulus. In this case the stimuli are plain text, but here you could also put filenames of pictures or sound files within the quotation marks.

Of course, three stimuli are not enough to fill an entire IAT. Go ahead and complete the list until you have ten different negative words. Then, make three more item lists, one for positive words, one for spider names and one for flower names. For the continuity of this manual, it’s important that you call them negative, positive, spider, and flower. Remember, these are the names you add as second part to the open-tag, and which will be used in the entire script to refer to these specific stimuli. 

A note on structuring your script: It does not matter in what order you place the elements of the script, as long as all elements that you need are in the script, and every element has its own start-tag and end-tag. When you run the experiment, Inquisit will read through your script, checking whether all necessary elements are there, regardless on where they are in your script. However, for the sake of your own readability, pick a consistent ordering of elements and stick by that. The best way to order them now is to keep them in chronological order of the bottom-up path we’re following now. Besides that, you can add comments in your script to make it more readable. Every line of text that you add to your script that is not enclosed within open-tags and close-tags will not be interpreted by Inquisit. This means you can write anything you want there, without worrying about errors. Just make sure you don’t accidentally write something in the format of a tag.

Stimuli: continued…

So now Inquisit knows your stimuli, but it still needs to know how to work with them. You will have to tell Inquisit whether these stimuli need to be handled as text, as pictures, as movies, etc. and how they need to be presented. You can do this with the text, picture, video, sound elements. To see more elements, press F1 for the help function, and in the contents look for Language Reference and then for Stimuli.

Because the stimuli we are using are text stimuli, we will use the text element. In the text element we can define how the stimuli are selected from the item list and how the stimulus should be presented on the screen. For each item list we have to define a specific text element. The negative text element might look something like this:

<text negative>
 /items = negative
 /select = noreplace
 /position = (50, 50)
 /txcolor = (255, 0, 0)
 </text>

Let’s take a closer look at this text element. The open-tag and close-tag should look familiar by now. The only thing different from the item element is the fact that item is replaced by text. The name of the text element is the same as the name of the previous item element. This would not be necessary. I could just as easily have called this element negative_words. As long as in the second line the items attribute still refers to negative, Inquisit will know that the text element negative_words refers to the item element named negative. I like to keep the names of text elements and item elements the same. It’s no problem for Inquisit and improves the readability of your script. So let’s stick with negative as name for both the text and the item elements.

As mentioned in the previous paragraph, the items attribute on the second line provides the actual reference to the specific items element containing the actual stimuli. This line is very important. Without it, Inquisit would know how to present negative stimuli, but would not know what stimuli to present. For shorter lists of stimuli you could skip the extra step of defining a specific item element. You can directly include the stimuli in the text element by using the items attribute in the following way:

/items = (“tragic”, “horrible”, “awful”)

The reason you do not want to do this most of the times is that you need to be able to refer to these items from other elements besides this specific text element.

The third line states the select attribute. This attribute tells Inquisit how to select stimuli from the item list referenced by the items attribute. There are lots of options here, but the most important ones are replace and noreplace. The first randomly selects a stimulus from the item list each trial and will replace it in the item list so it might be selected in a subsequent trials. Most of the time though, you would not want the stimulus to be replaced in the item list, so every stimulus will be presented once. That’s where noreplace comes in: Inquisit will randomly select a stimulus from the specified item list and not replace it until all stimuli have been selected once across trials. When all stimuli have been selected, and a trial requests another stimulus the item list will be reset, and all stimuli will be selectable again.

The third line contains the position attribute, which defines where on the screen the text should be displayed. The (50, 50) means put the stimulus right in the middle of the screen: 50% in the horizontal direction, and 50% in the vertical direction. Play around with the values if you want. You will need to type the full text element to try this. 

To try out how a stimulus is presented, make sure your cursor is positioned at the respective element, and press F11 to run the selected element only.

The last attribute in the text element is the txcolor attribute. If you just played around with the position of the stimulus you will already have seen that the stimulus was presented in red. That’s because of this attribute. The three values are RGB (Red Green Blue) values, and range from 0 to 255. In this case we have 255 for Red, 0 for Green and 0 for Blue, making the stimulus fully red.

There are more attributes for this element you might want to check out. If you put the text cursor somewhere between the open-tag and close-tag, you will get more information about the possible attributes for this specific element from the help function by pressing the F1 key. For instance, you might want to change the font to a bigger one using the fontstyle attribute.

So we now have a negative text element. Now create the positive, spider, and flower text elements. 

Trials

The next step is to define how stimuli will be used in trials. Trials follow a specific timeline, shown in the chart below, which I copied from the Inquisit website:
trialtimeline

Don’t let the complexity of the chart discourage you. The part where your stimuli get presented is the Present Stimulus Frames part. You will have to tell Inquisit what stimulus to present at what frame or time. All the other attributes of the trial timeline have default values, which you don’t need to alter, unless you have special needs for them. If you want to know more about these trial timeline attributes, have a look at http://www.millisecond.com/support/docs/v3/html/howto/howtocontroltiming.htm.

Importantly, you can choose to define the presentation timings of your stimuli based on time or frames. Defining the timings in terms of time (milliseconds) has the advantage of working independent of the frame rate settings of your graphics card and display settings. The disadvantage is that if the time you assigned for a specific stimulus does not perfectly coincide with a new frame, the stimulus might be presented a frame later. An example might clarify: If you have a display set to 60 Hz (frames per second), a single frame will have a duration of 1 / 60 secs = 16.67 ms. If you then want to present a stimulus at 300 ms, you can calculate the frame number from the beginning of the trial to the moment you want the stimulus to be presented: 300 / 16.67 = 18. Actually the equation yields 17.996, 18 is a rounded number and 18 frames take 18 x 16.67 = 300.06 ms. If it really needs to be exactly 300 ms, you will need to set the refresh rate to 100 Hz. Then, a single frame will take 10 ms, and after 30 frames, exactly 300 ms will have passed. Note that using time instead of frames to define the timings will not solve this problem if the refresh rate is still set to 60 Hz: there is no way Inquisit can show a stimulus at exactly 300 ms, if the display only shows a new frame every 16.67 ms. So be advised, if you choose to use times, you have no guarantee that stimuli will actually be presented at the times of your choosing. In the best situation, it’ll be pretty close.

By the way, changing the refresh rate of your computer is easy. Just go to an empty spot on your desktop. Right click on it, and select Properties. Then select the Settings tab, click the Advanced button, select the Monitor tab, and then select the appropriate refresh rate from the dropdown list below. Don’t forget to click Ok or Apply. Also, don’t forget to do this on all the computers you will run your experiment on in the lab!

Let’s program a trial then. We will need to make one for each type of trial in the experiment. For instance, we need a trial for presenting an spider name. Because an IAT has a stereotype compatible and a stereotype incompatible block, we will actually need to program two different trials, one for each block: in the compatible block participants will have to respond to spider names with the same key as for negative words and in the incompatible block they will have to respond to spider names with the same key as for positive words. We’ll decide now that the left key will always be used for positive words, and the right key always for negative words. We’ll also decide that the left key will be the ‘A’ key, and the right key will be the ‘L’ key.

Moreover, we will need to program some extra text stimuli to show on the screen, such as a fixation cross and a text for when participants make an error. You already know how to create text stimuli, so create one that shows a plus in the middle of the screen called fixation. Also create a text element called error that show red text a little bit below the center of the screen. 

The spider names trial in the compatible block might look something like this:

<trial compatible_spider>
 /stimulusframes = [1=fixation; 10=spider]
 /correctresponse = ("l")
 /validresponse = ("a", "l")
 /errormessage = true(error, 1000)
 /pretrialpause = 500
 </trial>

The first and last lines should look very familiar by now. The second line shows the stimulusframes attribute, which contains the actual frame numbers at which stimuli will be displayed on screen, 1 being the first frame. On the 1stframe, the fixation element will be shown, which you just programmed. On the 10th frame an spider name will be presented, which in the case of a refresh rate of 60 Hz means 10 x 16.67 = 166.7 ms. We could have used the stimulustimes attribute instead of the stimulusframes attribute if we wanted to use time instead of frames as timing unit. The line would look exactly the same, except for the attribute name and the 10 before spider. The latter would be replaced by for instance 170, meaning 170 ms. Pay special attention to the square brackets that are being used with this attribute, and the semicolon that is used as separator. Whenever Inquisit needs a list of elements with timing in front of it, it will always expect these square brackets. A lot of the time a script will not run because you accidentally used normal parentheses, or a comma instead of a semicolon.

The second and third lines go together. You always have to define the validresponse attribute. It tells Inquisit which keys can be used as response. Additionally, if you want to define an error message, you will need to tell Inquisit what key is the correct one for this specific trial. You do this with the correctresponse attribute. Keys you mention in correctresponse do not need to be mentioned in validresponse. Pay close attention to the double quotation marks. Single quotation marks won’t work. The reason the keys are also between parentheses is that Inquisit expects a list of keys.

The errormessage attribute tells Inquisit that it needs to show the text defined in the error text element, which you just programmed, for 1000 ms. Don’t forget the true before the parentheses.

Finally, the pretrialpause attribute is one of the attributes shown in the previous image depicting the timeline of a trial. In this case we tell Inquisit to wait 500 ms before the presentation of the stimuli should start.

Now create the incompatible_spider, compatible_flower, incompatible_flower, positive, and negative trial elements yourself. Before you start, think about why you do not need to have special positive and negative trials for each separate block. Don’t forget to edit the validresponse and correctresponse attributes as needed. If you want to try out your trials, use F11 to run the selected element only. 

As with all other elements, you can get explanation about other attributes by placing the text cursor between the start-tag and end-tag and press F1. Have a look at other trial element types, such as likert to easily create likert questions and openended to easily create open ended questions. They will have some different attributes you might want to check out.

When browsing through the contents of the Language Reference in the help function, you will also find other ways to ask questions to your participants through the survey and surveypage elements, which allow you to show multiple questions on one screen, and have all kinds of different question types, such as analog sliders, checkboxes, and drop down lists. This tutorial does not cover those, but it is good to know those exist. The same goes for the fact that you can use parallel and serial ports as input for Inquisit, using the port element. Useful if you want to connect joysticks or other custom hardware to your experimental set-up. Good to know, but I am not going to explain it here.

Blocks

You have created stimuli, and told Inquisit how to use those stimuli in trials. The next step is organizing those trials into blocks. We will need to define every block separately. Additionally, we need to define several text stimuli that show the correct combination of categories for the left key in the bottom left corner of the screen and for the right key in the bottom right corner of the screen. These stimuli need to be displayed throughout the entire block, that’s why we define them here on the block level and not on the trial level. You already know how to create text stimuli, but I’ll show you how to create one of them, showing “positive & spider” in the bottom left corner.

<text reminder_positive_spider_left>
 /items = ("positive & spider")
 /position = (10, 90)
 /font = ("Arial", -20, 700, 0, 49)
 </text>

Now create the others yourself. Call them reminder_positive_left, reminder_negative_right, reminder_positive_flower_left, reminder_negative_spider_right, and reminder_negative_flower_right. Don’t forget to edit the position attribute. 

Now let’s start with ordering the trials in blocks. The easiest one is the practice block, because that one only uses positive and negative trials. The block element might look something like this:

<block practice>
 /trials = [1-20=noreplace(positive, negative)]
 /bgstim = (reminder_positive_left, reminder_negative_right)
</block>

The trials attribute looks a bit like the stimulusframes attribute of a trial element. Instead of frame numbers, the numbers represent trial numbers. In this case the meaning is that trial 1 to 20 should show positive and negative trials without replacement. This means that every trial in this block Inquisit randomly decides whether it will be a positive or a negative trial, but in such a way that at the end of the 20 trials, ten will have been positive and 10 negative. If you want that trials never get repeated immediately after another (so no positive trial and then immediately another positive trial) you should use noreplacenorepeat.

Both noreplace and noreplacenorepeat ensure that you do not end up with a skewed distribution of trial types across all 20 trials. If you would have used replace instead of noreplace, this would not be the case; every trial a specific element would get randomly selected, and you might end up with for instance 16 positive trials and 4 negative trials in the practice block for one participant, and 8 positive and 12 negative trials in the same block for another participant.

It is also important to note that the noreplace within a block element does something different from a noreplace in a text element. The noreplace in a block element will randomize the selection of trial elements. The noreplace in a text element handles the subsequent randomized selection of the stimuli within a specific list. In other words: Inquisit will randomly select either the negative or the positive text element because of the noreplace in the block element. Once it has selected for instance the negative text element, it needs to select a stimulus from within the negative text element. Because you set the select attribute in the negative text element to noreplace it will randomly select a stimulus from the negative item element.

Importantly, every time a new block is run by Inquisit, it will forget the previous selections made in text elements. So if you assigned noreplace in a text element referring to an item list with 10 stimuli, and then in one block run only five trials, in the next block Inquisit will have forgotten about the five stimuli that have already been selected. You can circumvent this with the resetinterval attribute of the defaults element. You will learn about the defaults element later.

On the third line the bgstim attribute tells Inquisit what stimuli to keep on the screen (background stimuli) during the block. In this case we need the reminders specific to this practice block to be in the subsequent list. In other blocks, you will need to change this list accordingly.

The second block we’ll define is the compatible practice block. Have a look at the following block definition:

<block compatible_practice>
 /trials = [1-20=noreplace(positive, negative, compatible_spider, compatible_flower)]
 /bgstim = (reminder_positive_flower_left, reminder_negative_spider_right)
</block>

This block definition should make sense now. The appropriate trials have been added and the background stimuli have been changed. Now go ahead and create the three remaining blocks. Call them compatible_target, incompatible_practice, and incompatible_target. Make sure you use the correct amount of trials. You can try out your blocks by pressing F11 to run the selected element. 

Experiment

This is the point at which we are going to unify all blocks into one single experiment. From this point on, we’ll be able to double-click on the .exp file containing your script to run the whole experiment, without having to select which block to run. We will need to think about how we order the blocks, and with this come considerations about counter-balancing. We want every subject to start with the practice block. After that we want half of them start with the compatible blocks and then the incompatible blocks, and the other half with a counter-balanced order. Inquisit lets you do this in multiple ways. I am going to show you one of them.

Let’s start with one specific order:

<expt>
 /blocks = [1=practice; 2=compatible_practice; 3=compatible_target; 4=incompatible_practice; 5=incompatible_target]
 /subjects = (1 of 2)
 </expt>

First note that the open-tag does not require a name. The blocks attribute contains the actual order in which the blocks should be run by Inquisit. The subjects attribute takes care of part of the counterbalancing. In this case it states that every first out of two subjects should get this particular ordering of blocks. This will be based on the participant number you enter when you start the experiment. Participant 1 will get this order, 2 will get another order that we will define next, 3 will get this order again, etc.

The expt element taking care of every second out of two participants will look like this:

<expt>
 /blocks = [1=practice; 2=incompatible_practice; 3=incompatible_target; 4=compatible_practice; 5=compatible_target]
 /subjects = (2 of 2)
 </expt>

As you can see, the order of the blocks has changed, and the subjects element changed to apply to every second of two subjects. Note that you can create more conditions if you’d want to by changing (1 of 2) and (2 of 2), to (1 of 4) and (2 of 4), and add two more expt elements with (3 of 4) and (4 of 4). That way you have four different conditions. You can change more than ordering too. By referring to totally different blocks, which contain totally different trials, you can have some participants do a different experiment from other participants. There are other ways to accomplish this, for instance by using the variables element. Explanation of this element lies outside the scope of this tutorial, but if you’re interested in more advanced ways of using conditions in your experiment, be sure to take a look at it.

Now include these two expt elements in your script, run the whole experiment by pressing Ctrl + F5, and you’ll probably figure out soon what we’re still missing. 

Instructions

Yes! There were no instructions in your experiment. How are participants going to know what they have got to do? We’re going to change that right now.

You can add instructions before and after any block and expt, using the preinstructions and postinstructions attributes. In those you will refer to page elements containing the text you want to use as instructions. The general layout of the instructions is defined in the instruct element. Let’s start with the layout:

<instruct>
 / txcolor = (255, 255, 255)
 / screencolor = (0, 0, 0)
 / nextkey = (" ")
 / prevkey = ("p")
 / nextlabel = "(Space) Next page..."
 / prevlabel = "(p) Previous page..."
 </instruct>

The attributes (there are more than these, press F1) are pretty straightforward. txcolor you should recognize from the text element, in this case white. screencolor is the background color, in this case black (remember? No red, no green, no blue, makes black). nextkey tells Inquisit that a space is the key to be used to go to the next page. prevkey does the same for going to the previous page. nextlabel and prevlabel state the labels that should be put on the on-screen buttons on every page.

The next step is creating the individual instruction pages. The welcome instruction page at the start of the experiment might look something like this:

<page welcome>
 Welcome to this experiment.
 ^^In this experiment you will categorize words and names.
 </page>

Within the open-tag and close-tag of a page element you can just type the text you want to show on the instruction page. To indicate that a line of text needs to be presented on the next line, you insert the ^ symbol. Just pressing enter or return won’t work, because that will just be interpreted by Inquisit as a space. I used two ^ symbols to create an empty line between the first and second line.

We want to show this page at the very start of the experiment. We have a choice now, either we include this page in the preinstructions attribute of both expt elements, so it gets shown regardless of the condition a participant is assigned to, or we edit either the practice block element to include this page in the preinstructions attribute. Because the practice block is the first block in both conditions, it’s more efficient to edit that block instead of editing both expt elements (good programmers are lazy by definition). If you would want to have different instructions based on conditions, you could use the preinstructions attribute of the expt elements to refer to different instruction pages.

After editing, the practice block element looks like this:

<block practice>
 /trials = [1-20=noreplace(positive, negative)]
 /bgstim = (reminder_positive_left, reminder_negative_right)
 /preinstructions = (welcome, practice_instructions)
 </block>

The only thing different is the addition of the preinstructions attribute. The first page to show is welcome and the second one is practice_instructions, which we didn’t create yet, but you can create now. After that, run the practice block to see what the pages look like.  

It’s also time to make all other instruction pages. Go ahead and make the instruction pages you deem necessary at the start or end of each block and a final “thank you” one at the end of the experiment. Then, create all the references from the blocks and experiments using the preinstructions and postinstructions attributes. They work identically for the expt and block elements. 

Finishing touch

Your experiment is now finished. You might have noticed that some attributes have to be set the same for every element, such as the font of text elements if you wanted to change that. If you would copy-paste every text element, you will need to change every single element again if you wanted to change the overall font. There’s an easier way to do this, using the defaults element, like this:

<defaults>
 /fontstyle = ("Arial", 3.5%)
 /screencolor = (0,0,0)
 /txbgcolor = (0,0,0)
 /txcolor = (255, 255, 255)
 /minimumversion = "3.0.0.0"
 </defaults>

Every text element that misses the fontstyle or the txcolor attributes for example, will default to the values stated in the defaults element. Look in the Language Reference (F1) for more attributes, such as the minimumversion attribute, which will ensure that this script will not run on Inquisit versions below 3.0.

You might also be wondering about data recording. Well, Inquisit automatically takes care of this for you. It will save everything there is to save in a file in the same folder as your script, with the same name as your script, but with the extension .dat. This is a simple tab delimited text file which you can open with any text editor, but also with Excel or SPSS. You’ll get one response per row. All participants will be in the same file. If you read in your data in SPSS using the Read text data command, you will need to work with the Aggregate and Restructure command to get your data in the more familiar format with one line per participant. For this to work well, you should have well-named blocks and trials, names that are really descriptive of the respective blocks and trials. Otherwise you are going to have a hard time decoding your data.

There are more advanced programming techniques in Inquisit if you have special needs regarding branching, or giving block feedback, or conditional stimulus selection. You can read more about them in the online help.

And don’t forget to find the monkey to test your scripts for you (hint: look for Experiment, Run Monkey in the Inquisit menu). This is especially useful if you want to check out what your data looks like in experiments that take a long time to run.

Congratulations! You now know how to program Inquisit!

6 Replies to “Inquisit Tutorial”

  1. This is insanely helpful. I especially enjoy the pedagogical aspect of encouraging the reader to complete several lines of code themselves. I would love more tutorials using other experimental paradigms.

  2. This is a great start to this tutorial! There are some major errors here though that make it frustratingly hard to follow. First, both letters must appear in the validresponse line otherwise it will result in an error when running the trial. Second, pressing the F5 key on the keyboard is not a command in inquisit. Ctrl + F5 will run the experiment, however. Also, none of the tabs you mentioned are anywhere to be found nor is there any button labeled “Do” in this program.

    Thanks for all of your hard work! Correcting these errors may make this easier for others to follow.

    1. Dear Sam,

      Thanks for your feedback. This tutorial has been written years ago for Inquisit 2, and then updated to Inquisit 3. Apparently, things have changed since then, we’re at version 4 now. I’ll update the tutorial to reflect the changes you mention.

      Best,

      Ron

  3. This is wonderful, thanks so much! Could you describe how to counterbalance keys – do you have to create another set of blocks with, for example, I for E and vice versa if you want to counterbalance which keys participants are instructed to press?

    Thank you!

    1. The most straightforward way would be indeed to create another set of blocks, that refer to another set of trials with the reverse key mapping, and counterbalance with various elements. There are shortcuts though, using , but that’s more complicated to explain.

Leave a Reply

Your email address will not be published. Required fields are marked *