skip to primary navigation skip to content
FAQ for DMDX with fMRI


  1. I want to run a neuroimaging experiment should I use DMDX or Visual Basic?
  2. How do I create a DMDX file?
  3. What video mode is used in the fMRI projector at WBIC? How fast is the refresh rate?
  4. How do I measure participants’ responses? Which of the four buttons should I use?
  5. How do I get data from my output files? What’s the difference between .azk and .zil output files?
  6. How do I specify exact timing of stimuli in DMDX?
  7. How can I check that the timing of my experiment is correct? What are these errors that I get about "display scheduled 2 ticks late"?
  8. How do I ensure that DMDX stays in sync with the fMRI scanner? How do I get the scanner to start the experiment running?
  9. Should I use scrambling? How should I order my stimuli?
  10. How do I use DMDX to figure out the exact TR that the scanner is running at?
  11. How do I record from all four buttons? I thought that I'd set up DMDX to do this, but then it didn't work!
  12. Where's the old version of this page gone?
  13. How do I ensure that DMDX responds to the shorter scan pulses provided on the CBU Siemens Trio?
  14. Can you give me a quick summary of what I should do?

  1. I want to run a neuroimaging experiment should I use DMDX or Visual Basic?


    The choice of which system to use is not a straightforward one. I can recommend using DMDX if you can answer yes to the following questions about your experiment:

    a) It involves visual presentation of words, pictures other static displays or involves auditory presentation of sound-files.

    b) There is a finite set of stimulus items to be presented (i.e. you don’t need to generate a unique set of items for each subject).

    c) A fixed number of stimuli are presented in each scanning session (i.e. the number of stimuli presented per block is determined by the experimenter, not by the number of items that the subject gets through in 30seconds).

    d) It involves either no response from the subject or a simple button-press response (2-afc or 4-afc).

    For complex experiments, and for confident programmers, Visual Basic or some other code that you write yourself will be more powerful, flexible, etc. However, compared to some systems that I’ve used, DMDX is actually pretty good. With practice you can set up an experiment to display words, pictures, sound-files in any combination quickly and easily.

    back to the top

  3. How do I create a DMDX file?


    The script files that DMDX uses are simple .rtf (rich text format) files, these can be created using standard desktop applications (word/excel/etc.). For the sophisticates amongst you, it is also possible to write c code, perl, or awk scripts that generate these files. You may also need some files that contain the images (.bmp) or sound files (.wav) that will be presented to subjects.

    The .rtf script starts with a header-line, providing information about how the machine is configured, and global settings for the experiment (video mode, response measurement, etc.). It then contains sequences of item lines that give instructions about what words/pictures/soundfiles to present. To find out more about DMDX files, read some introductory information on header-lines and item-lines, here.

    back to the top

  5. What video mode is used in the fMRI projector at WBIC? How fast is the refresh rate?


    The WBIC machine and video-projector is set up to display stimuli in a high-resolution (1024 by 768 pixels) and high-colour (16 bit) mode. This should be sufficient for most people’s requirements while still allowing for rapid stimulus displays. The refresh rate for this video mode is 75Hz - that is one tick is approximately 13.333 ms. You can read more about ticks here.

    To use this display mode, you need to include the following video mode in the header line of your file

    <vm 1024, 768, 768, 16, 0>

    I recommend that you stick with this video mode unless you have a good reason not to (wanting a stimulus display of exactly 500ms rather than 506ms or 493 ms is not a good enough reason).

    back to the top

  7. How do I measure participants’ responses? Which of the four buttons should I use?


    Each item line in a DMDX file usually begins with a + or a - sign. This is a sign of DMDX’s more modest origins when it was designed for use with experiments like lexical decision in which a yes/no response is expected. If your experiment is 2-afc then you should assign one response as yes (+) and another as no (-). That way, response times measured by DMDX will be positive if they are correct and negative if they are incorrect. On the standard button box in the scanner, you should use the buttons underneath the subjects index finger and middle finger (when the box is held in the right hand). By default, the index finger corresponds to a negative response and the middle finger a positive responses – though this can be changed. Alternatively, if you want to record either button press, but don’t wish to specify a response as correct or incorrect then you can use a carat (^) instead of the + or -.

    If your experiment is a 4-afc design then you will need to record responses from all four buttons. This is not done by default. You have two options here, you can either assign one of the four buttons as being correct (and the others as incorrect) on each trials using the <mpr> and <mnr> keywords. Alternatively, if you need to know which of the four buttons are pressed (rather than just whether the response was correct or not) you can use the <zil> keyword which will make DMDX output all responses made, not just whether they are correct or incorrect.

    NB: There are some wrinkles with using all four buttons on the button box, as I discovered to my cost. You need to use the following sequence of keywords in the top line of the file:

    <zil> <id "pio12"> <mip 37> <umtp> <umvk> <vzk +Bit1> <vzk +Bit2> <vzk +Bit3> <vzk +Bit4>

    I would also recommend that you test your script with a four-button box before taking it to the WBIC.

    Turns out that I made a mistake when originally writing this page... please check your script carefully!

    back to the top

  9. How do I get data from my output files? What’s the difference between .azk and .zil output files?


    Each time a DMDX file (e.g. experiment.rtf) response is output to a file with the same name and a different extension (either experiment.azk or experiment.zil). If you run more than one subject on a single experiment data from the second and subsequent subjects is appended to the bottom of the file. The difference between the these two sorts of output files is in the amount of detail that is recorded.

    The .azk format includes only rt and 2-afc errors for the first response that the subject makes on each item and will only record responses for the yes/no buttons as described above.

    The .zil option records all button presses (not just yes/no and not just the first response for each item), it also records the time that the button is pressed and released. The .zil output also records the time at which the scanner sends a trigger pulse. Basically, I recommend using .zil unless you feel that there are no circumstances in which you could possibly use this additional information.

    There is an awk script that I’ve written to process the .azk output and convert it into a form that can be easily imported into Excel or SPSS. You can download it here. I’ve written a similar script for .zil files though this isn’t being as widely distributed as it needs some more refinement. Send me an email and I’ll pass this on to you in return for feedback on how you got on with it and how it should be improved.

    back to the top

  11. How do I specify exact timing of stimuli in DMDX?


    Stimulus timing in DMDX can be a bit of a minefield. However, for most things that are needed there are some simple guidelines and a limited number of parameters that can affect things. What I’m going to describe here is the simple case in which items are scheduled at regular intervals. Come and have a chat with me if you want to do something more sophisticated.

    The main source of confusion is that there are several interacting factors that determine the duration of stimulus displays and inter-trial intervals. In a conventional behavioural experiment the ITI is seldom crucial so DMDX uses this time to do save data, load picture files and do other such house-keeping. In fMRI we want exact control not only of timing within an item, but also between items. This means that we need to be a bit more careful with how set up our files. First of all, I’ll explain the anatomy of a single item-line in a DMDX file.

    The following item lines will display the word "hello" and measure a response.

    +1 * "hello" /;

    the time that the word is displayed for is determined by the <f> parameter that was set in the top line of the DMDX file. This gives a value, in ticks of the time that the item is displayed for. So, if we had <f 15> in the top-line of the file, "hello" would be displayed for 15 ticks (200ms). The end of the item has a slash and a semicolon (/;). This indicates that DMDX should move on to the next item. However, there are two factors that can affect how long DMDX waits before displaying the next item.

    The first factor that increases the inter-trial-interval is the time out for measuring RT. The "hello" item doesn’t finish until the RT timer has finished timing - either because a response has been made or because of a "time-out". The time-out is set using the <t > keyword. By default this is 4000ms, but can be changed either in the top line or at any point during an item. So for the item above, instead of moving onto the next item after the 200ms display time, DMDX would move on after a response has been made - or if no response was forthcoming, 4000ms from the time that the RT clock was started.

    Clearly, this will mean that the timing of an experiment could be changed depending on how quickly participant’s respond - this makes sense in a behavioural experiment (we normally want to encourage people to go quickly) - but will be crucial in an fMRI experiment where fixed stimulus timing is required. The solution is to make sure that there are events in each item line up to the offset of the response time-out. So for example, if you wanted to give participants 4 seconds to respond (using a time-out of 4000ms), you should add another frame to each item-line as follows:

    +1 * "hello" / <% 285> /;

    So, after "hello" is displayed, there will be a pause of 285 ticks (3.8 seconds) during which a blank screen will be displayed, making the entire item last 4000 ms (200ms and 3800ms). Of course, if you wanted a shorter delay between items you could reduce the time-out and reduce the duration of the blank display accordingly.

    The second factor that increases the inter-trial-interval (ITI) is the delay parameter <d>. This is set in the top line of the file (though it can be altered elsewhere) and gives a number of ticks that DMDX pauses between items. So in the following file:

    +1 * "hello" / <% 285> /;
    +2 * "world" / <% 285> /;

    The delay between successive words would be 4000ms plus the value of d (there’s also a single extra-tick that is added, but I’ll discuss this later). This delay period is very important since DMDX uses this delay to do various bits of administration saving data, loading picture or sound files, etc. For this reason I would recommend that you include a delay of at least 10 ticks (~130ms) and make this delay longer if you are using large image files since these take longer to load from disk.

    So, for the example above, if you wanted a 200ms presentation of a word <f 15> and then another word starting exactly 4000ms later, I would recommend using a time-out to be 3500ms <t 3500> a delay of 10 ticks d 10>. You would then set up your item lines as follows:

    +1 * "hello" / <% 274> /;
    +2 * "world" / <% 274> /;

    We can break down the timing calculation as follows (NB at a 75Hz refresh rate, 1 tick ~ 13.3 ms):

    word display
    (set using <f 15> in top line)
    blank display
    (set using <% 274> in item)
    extra tick
    (from /; at end of item)
    (set using <d 10> in top line
    total ITI

    This complicated calculation only really becomes relevant where you are scheduling successive events that require a response. If all you wanted is a sequence of events with a single response, you can do things like this:

    +1 "spot" / "the" / "repeated" / "word" / "in" / "this" / * "this" / "sequence" /;

    Here DMDX will present single words (RSVP) on the screen and measure responses with respect to the repeated word. For complex displays such as this you may need to increase the delay parameter.

    Postscript (29/06/01) There is some further discussion of timing issues in continuous running designs here. This could be very useful to people wanting to display lots of bitmaps. It seems like there is a way to get DMDX to display an image while loading another image into memory... I've not tried any of this though.


    back to the top

  13. How can I check that the timing of my experiment is correct? What are these errors that I get about "display scheduled 2 ticks late"?


    As the above discussion illustrates, setting timing parameters in DMDX can be a bit arcane. I would therefore recommend that you check your file before you run it. One good way to do this is to use the <rcot> option. This is set in the top-line of the file and means that when the file is run, the data that is output will include a record of the exact time at which the RT clock is started (ie. the position of the * in each item-line). For example, in running the following file (with <f 15>, <d 10> and <t 3500> as described before):

    +1 * "hello" / <% 274> /;
    +2 * "world" / <% 274> /;

    we get the following output in the .azk file:

    Subject 1, 06/29/2000 14:58:34 on PC111, refresh 13.33ms COT
    Item 1, COT 0, No Responses.
    Item 2, COT 3999, No Responses.

    As you can see, the second item occurs almost exactly 4000ms after the time of the first item (as we'd hoped).

    When running an experiment you may find error messages appear in the output file:

    ! Display error at msec 295, tick 18 in item 1, frame "hello"
    ! moved into video memory 2 ticks late
    ! (previous frame's duration will have been longer)

    This occurs when DMDX was asked to display an image or word at a time when it was "busy". Normally, this occurs when DMDX isn't given long enough to load picture or sound files from the disk. If you get error messages like this, I recommend increasing the delay parameter that you use. For example, if you are displaying full screen, high colour bitmaps, you may need to allow as long as half a second of delay (~35 ticks) and adjust other parameters accordingly. Exactly how much delay DMDX requires is will depend on the speed of the PC that you are using. Therefore you should make sure that you test your DMDX file either at wbic or on the wbic-mimic machine at the CBU.

    Postscript (12.12.02) Thanks to Jonathan Forster for pointing out that this script (like most imaging studies) needs to be run using the <nfb> option otherwise the feedback displays send the timing off.

    back to the top

  15. How do I ensure that DMDX stays in sync with the fMRI scanner? How do I get the scanner to start the experiment running?


    The top-line of a DMDX file normally includes the option <cr> (continuous running). In this mode, DMDX will not pause between items unless specifically instructed to do so. However, DMDX can be instructed to pause and wait for a request before displaying an item. The way to do this within a CR file is to add an item numbered 0 as in the following fragment:

    +1 * "hello" / <% 274> /;
    0 "Wait for Scanner.";
    +2 * "world" / <% 274> /;

    So this script will display the word "hello" and then display the words "wait for scanner". Only when a trigger is sent from the scanner (currently at the end of an acquired volume) will the script move onto the next item. Remember, however, that there will still be a delay (as set using the <d> parameter) between the end of one frame and the start of the next.

    Since the timing in DMDX tends to be quite robust, it should be ok to let DMDX run for several minutes without intervention (though you should check this using the rcot option as described above). However, on useful thing to do is to use triggers to start the experiment. Since we typically have 6 dummy volumes before the start of an experiment, this is an ideal opportunity to get the experiment and the scanner running together as well giving the subject some warning of when the experiment is about to start. The following bit of script will display a warning message, followed by a countdown during the dummy volumes:

    0 "Waiting for Scanner.";
    0 "3";
    0 "2";
    0 "1";
    0 "0";
    0 "+";
    +1 * "hello" / "" <% 274> /;
    +2 * "world" / "" <% 274> /;

    back to the top

  17. Should I use scrambling? How should I order my stimuli?


    Scrambling in DMDX is also a bit arcane – see Mike Ford's tips page for further information. In general, I would recommend scrambling by hand. That way you can be ensure that you will know what order of events to put into your analysis. If you determined to use different scrambling for each subject I would recommend thoroughly testing your file to make sure that DMDX is doing what you think it should do.

    back to the top

  19. How do I use DMDX to figure out the exact TR that the scanner is running at?


    If you use the <zil> option to record all button presses you will notice a large number of events labelled "+Bit0" and "-Bit0". These are the start and the end of the scanner trigger - hence there is always 50ms between the "+Bit0" and "-Bit0" events. If you have used <rcot> to record the clock on time, you can calculate the exact time of each scanner trigger and hence the exact TR that the scanner is producing for your image acquisition sequence. One word of warning though - don't believe DMDX's values too literally, triggers that fall during a delay period will be missed. It's also possible that there is some measurement error in DMDX. You should take an average over a large number of volumes to get a reasonable estimate of the effective TR for your image acquisition.

    Matthew Brett has written a perl script and Ian Nimmo-Smith some Matlab code to do this process automatically and come up the with the appropriate TR from your file - even allowing for missed triggers. Matthew's email says this:

    I have written some stuff to get an estimate of your  actual TR from a DMDX zil file, in FMRI.  I run my DMDX file, saving the output as zil, and making sure my timout parameters are set so that I have a decent chance of catching a few of the scanner output pulses.

    With this file, you can estimate your TR.  The file might be called myfile.zil.  In Unix, run the following from the Unix prompt: myfile.zil

    which extracts scanner on and scanner pulse off events into two separate  files, myfile_sub1_biton.txt, and myfile_sub1_bitoff.txt (one pair of files for each subject in the zil file).

    Then, to get the TR, start matlab/SPM (spm 99 from the Unix prompt), and run the following from the matlab prompt:

    >> est_tr

    Select the on and the off files you have just created, and you should get the TR output to the matlab window.

    There's now an updated version of this code, you can read more about it here.

    back to the top

  21. How do I record from all four buttons? I thought that I'd set up DMDX to do this, but then it didn't work!

  22. Hmm. Just goes to show how important it is to test things on the WBIC mimic before scanning... believe me, many people have been caught out by this! Those crucial keywords that you need to add to the topline of the file are:

    <zil> <id "pio12"> <mip 37> <umtp> <umvk> <vzk +Bit1> <vzk +Bit2> <vzk +Bit3> <vzk +Bit4>

    back to the top

  23. Where's the old version of this page gone?


      Why do you want to read this???


    back to the top

  25. How do I ensure that DMDX responds to the shorter scanner pulses provided on the CBU Siemes Trio?

On the Siemens Trio at the CBU, the scanner pulse that indicates when a volume is acquired is now 6ms in duration, rather than the 50ms pulse that was used by default at the WBIC. This scanner pulse is sent to the "request" input of the PIO input card, and so can be used to initiate DMDX trials or scanning runs. However, by default, DMDX only listens for a pulse once every 10ms, so it is possible that DMDX will miss some of these request pulses.

To accommodate this shorter pulse, DMDX needs to monitor for scanner pulses at a faster rate than is set by default. This can be very easily achieved by setting:

<id pio12 1>

as the "input device" in the top-line of your script.

back to the top


  1. Can you give me a quick summary of what I should do?

A quick summary of recommended usage is:

1) use the request pulse to start the DMDX script (with item 0)

2) ensure that the duration of stimuli on each trial exceeds the time-out so that inter-trial-intervals are independent of participants response times

3) allow for a suitable delay between trials (at least and more if using picture or sound files)

4) use the RCOT option to record the onset time of each trial (helpful for analyses)

5) use the ZIL option to record button presses and scanner triggers during each trial (helpful for figuring out the repetition time of the scanner)

6) test your script carefully before you scan your first volunteer - always use the CBU-mimic before scanning.

Matt Davis - 19/01/06