PDM – Progressive demasking software Copyright (c) 2006 DUFAU Stéphane, STEVENS Michael & GRAINGER Jonathan. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no FrontCover Texts, and no BackCover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". PDM is a program designed for running progressive demasking experiments on Windows 2000/XP based computers. The program is written by and for researchers in cognitive psychology and is covered by the GNU public license. In a progressive demasking trial a targetmask pair is presented consecutively several times until a response is made by the participant. During the trial, the total display duration of the target and mask pair is held constant, but the ratio of the target display duration and mask display duration is increased progressively. At the beginning of a trial (in the first cycle), the mask display duration is greater than the target display duration. As the cycle increases, the mask duration is decreased and the target duration is increased by the same amount of time. This makes the target progressively appear from the mask. The following table shows the display duration (in milliseconds) for consecutive cycles in a trial for the targetmask pair [TABLE; #####]. Cycle 1 Cycle 2 Cycle 3 … Cycle 12 Cycle 13 Cycle 14 TABLE duration 15 30 45 … 180 195 Infinite until response ##### duration 195 180 165 … 30 15 0 Total duration 210 210 210 … 210 210 210 PDM software is delivered as a zip archive. Once unzipped, the software is organized into a root directory containing 3 subdirectories and several files. Two of these subdirectories (whose names begin with “user_”) are intended to contain user data: input files (stimuli) in “user_input” and output files (subject response data) in “user_output”. The third subdirectory named “bin” contains necessary files to run the PDM software. Three additional files in the root directory serve to launch an installer program, an uninstaller program and the main PDM program. The last file, called “pdm.ini”, contains modifiable parameters such as screen display size, fonts, timing, etc.
1. How to use the program Running the program as it is configured is a good starting point. To install the software extract the archive in a directory of your choice (e.g. c:\pdm). Be careful to preserve the directory structure of the zip file. Then double click on “install.bat”. This will install the driver needed to read the vertical sync signal from the system’s registry. You need to be logged in with administrative privileges to do this. If this driver is not installed, pdm will use a vertical retrace simulator to determine the stimulus display durations. Here is an example session:
· To run the program, double click on “pdm_run.bat” or execute it from a command window.
· First, the program will ask for a subject number (4, for example) and a file number (1, for example).
· The program then displays the first stimulus pair contained in the stimuli file ‘stim1.txt’.
· Press the space bar to stop the display of the first mask and word pair.
· The program will ask for the answer (i.e. the word seen).
· Type your answer and press the ‘return’ key.
· The next stimulus pair is then displayed.
· Repeat the previous instructions until all the stimuli are displayed. The program should display 5 pairs and 2 PAUSE.
· When PAUSE is encountered, press the ‘return’ key.
· At the end of the program, press the ‘return’ key.
· The program writes output data file named ‘data_S4F1.txt’, as you have set subject number 4 (S4) and file number 1 (F1) at the beginning of the program execution. 2. The output At the end of the program execution, a file called ‘data_SnFm.txt’ is created in the “user_output” subdirectory (where ‘n’ is the participant number and ‘m’ the file number). If the (n,m) output files already exist, this is not a major problem since the program never overwrites an output file, but appends data to the end of the existing output file. The timestamp written at the end of the report is then useful to identify which data bloc corresponds to which pdm session. In the data files particular attention should be paid to timing error reports. These are inherent to multitasking computers, and can occur at the level of stimulus and response timing. The file ‘data_SnFm.txt’ can be opened with your preferred text editor (MS Word, Word Pad, Notepad, UltraEdit…). It contains the participant's data: information concerning the trial settings, the reaction time and two rough timing error measures. subject file trial mask target response RT RTE STE
1 1 1 1 1 1 1 1 1 2 3 4 ##### @@@ ***** %%% Table chair PAUSE Pen table chair pen 1321 1075 0 946 0 0 0 0 0 0 0 0 Field ‘subject’ The participant number the experimenter typed at the beginning of the program execution. Field ‘file’ The file number the experimenter typed at the beginning of the program execution. Field ‘trial’ The trial number (n). Field ‘mask’ The mask displayed in the current trial. This corresponds to the mask read in the nth line of the mask file. Field ‘word’ The word displayed in the current trial. This corresponds to the word read in the nth line of the word file. Field ‘response’ The response the participant typed at the end of a trial. Field ‘RT’ The reaction time (in milliseconds) corresponding to the time elapsed between the onset of the first mask display (i.e. the beginning of a pair display) and the space bar press. Field ‘RTE’ The error time (in milliseconds). This parameter gives the response timing error. A value of 0 ms indicates a nearly perfect reliability. Values of a few milliseconds are acceptable. Most computers will give 0 ms. RTE corresponds to the time elapsed between successive checks of the keyboard status (i.e. a key is pressed or not). As operating systems such as Windows XP are multitasking, the value of the keyboard status is checked in a discrete time mode. Generally, keyboard status in PDM is checked once every 1 to 250 microseconds. Field ‘STE’ The vsync error (0 or 1). This parameter gives display errors of stimuli. A value of zero means no vertical synchronisation errors were detected during the trial. A value of one means that at least one error was found. Most computers will give 0. A computer screen displays one image per refresh cycle. It can happen that the pdm program misses the beginning of a refresh cycle (usually around 15 milliseconds) and only proceeds to the desired display in the following refresh cycle. Please refer to the log file for details of the error when an error is encountered. When STE errors are encountered in a particular cycle of a trial, a sentence is written at the end of the trial line. This gives for example “m 13 1” or “t 9 1” that stand for “1 monitor cycles added
for the mask duration in the experimental cycle 13” or “1 monitor cycles added for the target duration in the experimental cycle 9”. The program checks for a maximum of four STE errors per trial. If so, " 4 OR MORE VSYNC ERRORS FOUND " is written for the trial. When no vertical synchronisation errors were encountered, the sentence ” no stimulus timing error found “ is written at the end of the data file. If one of the STE values is positive, the sentence ” stimulus timing error found in 1 trials. Check the error information at the end of the data trial lines “ is written. In that case, refer to the corresponding trial for details. 3. Programming an experiment Before a first experimental use of the software, the authors recommend testing the experimental computer in real conditions (with the desired settings) in order to ensure the timing quality. Good software execution does not lead to major reported errors in data files. If errors are encountered, please refer to sections 4 (dealing with errors) and 3.1 (setting up the program) of this document. 3.1. Setting up the program Program parameters such as screen size and refresh rate are controlled by the ‘pdm.ini’ file. A backup copy of the ‘pdm.ini’ file is saved as “pdm.ini.(original_copy).ini” in the bin folder. To open pdm.ini, you can use your favourite text editor. The file contains the possible values of each parameter. A brief description of the parameter is given here. Some of the parameter values can be modified and their influence on the program execution seen. Try some out and do not forget to save pdm.ini before launching PDM program. screensize 1 : VGA, 640 x 480 pixels. 2 : SVGA, 800 x 600 pixels. 3 : XGA, 1024 x 768 pixels. 4 : XGAplus, 1152 x 864 pixels. 5 : SXGA, 1280 x 1024 pixels. 6 : SXGAplus, 1400 x 1050 pixels. 7 : UXGA, 1600 x 1200 pixels. 8 : WXGA, 1280 x 768 pixels. 9 : WXGAplus, 1440 x 900 pixels. 10 : WSXGA, 1600 x 1024 pixels. 11 : WSXGAplus, 1680 x 1050 pixels. 12 : WUXGA, 1920 x 1200 pixels. fullscreen 1 : windowed 2 : full screen 3 : full screen with hardware acceleration refreshrate refresh rate <= 70 are hardware calculated refresh rate > 70 are software calculated (can generate minor timing errors)
priority 1 : normal 2 : above normal 3 : high waitmode control under which condition the program idles use this if the computer's fan makes too much noise during program operation 1 : use all cpu power all the time (best timing) 2 : economize during wait intervals (like ITI) (not too bad) 3 : economize also while waiting for a response (bad) 4 : economize also while waiting for a vertical sync (really bad) testmode can be used to run the program in a non interactive test mode. In this mode, all targetmask pairs in the stimulus file are presented, but the response registration at the end of each trial is omitted. By running the program in this mode the stimulus timing performance of a given computer can be tested on a large number of trials before starting to use this computer for experimental runs. This mode can also be used to interface the computer with an external hardware test setup. At the onset of the first targetmask cycle of each trial, a data bit that can be used to trigger an external timer is sent to the parallel port. Furthermore, masks are presented normally and targets are presented in black on a white background, to make mask and target fields visually separable to an optocoupler attached to the screen. 1: normal operation 2: test mode ticksNb the total duration of a (mask+target) presentation is 14 image refreshments if 14 is set. e.g. (14 x 1/60)= 233 ms for a refresh rate = 60 Hz or (14 x 1/85)= 165 ms for a refresh rate = 85 Hz tFontType 1 : arial tFontStyle 1 : regular 2 : courier 2 : bold 3 : times 3 : italics 4 : bolditalics The experiment messages are language specific parameters. Please note that you are limited to one line of text per display. Sentences longer than the screen resolution will be truncated. So for example do not set for the first screen: “In the following experiment, you will see pairs of word and mask successively displayed in …” but simply set “Press space to begin”. 3.2. Stimulus files
The experimenter should create as many stimulus files as needed, keeping in mind that randomizing the stimulus presentation is his own choice (and his own responsibility!). For example, if you plan to present stimuli randomized for each participant, you should create a separate pair of stimulus files for each participant. You can also write 4 different pairs of stimulus files to be used in a Latin square permutation. That gives: stim1.txt (pair 1), stim2.txt (pair 2), stim3.txt (pair 3), stim4.txt (pair 4) in a Latin square permutation: Participant 1; pair 1 (saved to file ‘data_S1F1.txt’) Participant 2; pair 2 (saved to file ‘data_S2F2.txt’) Participant 3; pair 3 (saved to file ‘data_S3F3.txt’) Participant 4; pair 4 (saved to file ‘data_S4F4.txt’) Participant 5; pair 1 (saved to file ‘data_S5F1.txt’) Participant 6; pair 2 (saved to file ‘data_S6F2.txt’)... The program reads a pair of stimulus file line by line, beginning with the first line. Stimuli should be maximally 20 characters long. Once your set of stimuli is prepared, randomization can be carried out with Microsoft Excel (using the random function) or any kind of software using spreadsheets. 4. Dealing with er ror reports The PDM program has been conceived to generate the least possible timing errors. However, a few errors might occur during a complete experimental run. We recommend rejecting the trials reported as having an error. However, if the number of trials with timing errors is too high, you can consider employing the advice we give in this section. Advice for avoiding such errors is given in the last paragraphs of this section. Two types of errors are reported in output files. Keyboard error time (RTE). An RTE is revealed when RTE is greater than one millisecond. Let's take an example: RTE is reported to be 10 ms for a reaction time measured at 1200 ms. As RTE deals with the successive checks of the keyboard status, this means that the space bar was hit between 1190 ms (1200 – 10) and 1200 ms after stimulus onset. We cannot know precisely when the key was hit during this 10 ms time interval. It is safe to remove trials with an RTE value greater than one from further data analyses. However, as the mean reaction times in this paradigm are typically vary between 1000 and 2000 ms, an RTE of only a few milliseconds is not a major problem. Vertical synchronization error (STE). A STE is revealed when the STE value for a trial is nonzero in the main data file. The interesting parameter reported in that case is the added display duration (ms). This gives the number of screen refresh cycles added to a stimulus in a particular cycle. For example, having 15 ms added to a target stimulus in the final cycle is not a major problem, since the target display in that cycle is 195 ms. Adding 15 ms to a target display in the early cycles would be a bigger problem. When display duration is added to
masks, the impact of this error is less important, since the stimulus of interest is the target. It is certain that an added display duration of several dozens of milliseconds leads to a trial rejection. Timing errors can originate at two levels: (i) the settings used by the experimenter and (ii) the compatibility between experimental computer and the PDM program. In order to avoid errors in PDM execution, please read the following paragraphs. (i). Settings configured in pdm.ini can have an impact on timing performance. To avoid errors, you may try to: use the native screen resolution since other resolutions lead to graphical interpolation calculation. use the native screen refresh rate, or set it to 60 Hz. set the program priority to high level. (ii). The authors have not conceived the software to be perfectly executed on all Windows XP computers but on most of them. It may happen that a computer generates a bad PDM execution. This is the case when a third program uses lot of computer resources (antiviral programs, virus, native Windows programs ...). To ensure a good execution, you may try to: turn off your antiviral program (be sure to run an analysis before), shut down unnecessary programs appearing in the Windows tray, turn off your screensaver. For advanced Windows users, instead of turning off programs, you may try to lower the previous cited program priority since the PDM priority can be set to high. This manipulation gives the PDM program a higher priority compared to others. To change a program priority, open the task manager, right click on the name of the program and set its priority to a lower degree. If none of the manipulations work, you may consider testing the PDM program with another experimental computer. 5. Making your own font The easiest way is to install tscope software on your computer (http://expsy.ugent.be/tscope/ ). Once installed, please follow the steps described in this section (extracted from the Tscope web site). You can make your own font files with the True Type fonts that are installed on your system. This is a twostep process: first the font has to be converted to a pcx file format, then the pcx file has to be converted to an allegro specific file format. The ttf2pcx program converts True Type fonts to pcx files. It can be found in /usr/local/ttf2pcx.
If you start ttf2pcx, it will show a list of all the available True Type fonts on your system. Select the font you want, and export it (monochrome, no antialiasing, and set max char to 0xFF). Once you have exported the font to a pcx file (e.g. myfont.pcx), copy it into /usr/local/allegro/tools dir. Open the Cygwin shell, and cd into that directory. Run ./dat myfont.dat a myfont.pcx –s2 and you will end up with a font file that can be read by Tscope. Copy it into your programs working directory, or into /usr/local/fonts to use it with your programs. The authors: Stéphane DUFAU 1 , Michael STEVENS 2 & Jonathan GRAINGER 1 . 1 CNRS & University of Provence, Marseille, France 2 Ghent University, Ghent, Belgium If you use the PDM software in your research activity, please quote our work in your publication as follows: Dufau, S., Stevens, M. & Grainger, J. (2007). Windows Executable Software for the Progressive Demasking Task (PDM). Behavior Research Methods, in press. PDM is copyright (c) Stéphane DUFAU, Michael STEVENS & Jonathan GRAINGER, 2007. This copyright and licence apply to all source code, compiled code and documentation. PDM is free software. You can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License and the GNU Free Documentation License, published by the Free Software Foundation. This licence can be found at www.gnu.org. Note that the program is distributed without warranty of any kind, either expressed or implied. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or correction. This work is based on the following tools:
Tscope, a C/C++ library dedicated to psychology experiment (GPL) http://expsy.ugent.be/tscope/ Stevens, M., Lammertyn, J., Verbruggen, F., & Vandierendonk, A. (in press). Tscope: A C library for programming cognitive experiments on the MS Windows platform. Behavior Research Methods. Allegro, a C/C++ library dedicated to game creation (GPL) http://www.allegro.cc Crimson editor (Freeware) Cygwin, a programming environment (GPL) http://cygwin.com These tools were used during development on a Microsoft Windows XP SP2 environment. This work was initiated following a conversation with Boris Burle (http://www.up.univ mrs.fr/lnc/ACT/people/Boris/borisen.html). If you modify PDM, you are encouraged to submit your changes to me for possible inclusion in subsequent versions. Help demands and comments are welcomed. They can be emailed at the following address stephane.dufau@univprovence.fr Particular request involving supplementary work will be studied.