Table of Contents

Name

stimpres - stimulus presentation (ERP DOS programs)

Description

stimpres is a program for presenting visual and auditory stimuli on IBM compatible computers running the DOS 6.2 operating system. It will also run on systems running Win95/Win98 when they are booted in the Command Prompt mode. stimpres is designed as a replacement for the vvsp(2) /cavsp(2) stimulus presentation programs, and as such, uses the vvsp(2) Scenario File format. However, stimpres has incorporated several enhancements to the vvsp(2) feature set.

This document describes the differences between the vvsp(2) /cavsp(2) and stimpres; the reader, therefore, is referred to the vvsp(2) and cavsp(2) documentation for general use and scenario file descriptions.

NOTE: In the early days when the ERP programs were being developed the term ISI (InterStimulus Interval) was being used incorrectly to refer to the time interval between the beginning of one stimulus and the beginning of another, and the legacy of this can be seen today in some ERP programs and documentation. When used correctly ISI refers to the time interval between the end of one stimulus and the beginning of another; SOA (Stimulus Onset Asynchrony) is the correct term to use to refer to the time interval between the beginnings of stimuli. In this manual these terms are being used correctly, but the reader may note an occasional inconsistency that remains as the legacy. For example, the -isi option doesn’t change all ISIs, rather it changes all SOAs (when using proper terminology). Also note the first argument describing each stimulus in a scenario file is properly referred to as the SOA, not the ISI.

Usage

stimpres is invoked with the same syntax as vvsp(2) /cavsp(2) with some additions. Typing stimpres at the command prompt yields the following usage summary:


Usage: stimpres scenariofile [options]
Options are:
-isi delta_isi        increment or decrement all SOAs
-dur delta_dur        increment or decrement all durations
-prep delta_prep      increment or decrement prep milliseconds
-font fontname        select default font
-fontsize size        select default font pointsize
-bgc bgcolor          select default background color
-fgc fgcolor          select default foreground color
-res xres yres        change from default pix resolution of 1024x768
-vgapal               use the default VGA hardware palette
-pal pal_file         get default palette from pal_file (vvsp(2) format)
-bmp_pal bmpfile      get default palette from bmp file
-pcx_pal pcxfile      get default palette from pcx file
-jpeg_pal jpegfile    get default palette from jpeg file
-forcepal palfile     force use of palette in palfile (vvsp(2) form)
-forcejpeg_pal jpeg   force use embedded palette in jpeg file
-forcebmp_pal bmp     force use of embedded palette in bmp file
-forcepcx_pal pcx     force use of palette in embedded pcx file
-sbg bg_crif          employ standing background cri image
-sbg_bmp bg_bmp       employ standing background Bitmap image
-sbg_jpeg bg_jpg      employ standing background JPEG image
-sbg_pcx bg_pcx       employ standing background PCX image
-sbg_pgi bg_pgi       employ standing background PGI image
-skipto label         start presentation from label
-spause               Enable selective pauses only
-mon                  Monitor only marked entries
-stat                 Print stats and synopsis before presentation
-show                 Draw and display 1st stimulus in scenario
-noprompt             Start and end program without prompting
-nocodes              Disable event code processing (useful for testing)
-noaudio              Ignore audio system (works if no audio present)
-8bitdac              Video hardware has 8 bit DAC for visual processing
-outp out-port        Specify event i/o hardware output port
-inp in-port          Specify event i/o hardware input port
-noresp               Ignore response codes
-mapexpcodes mapfile  Specify mapping for Experimenter generated codes

The options not already described in the vvsp(2) /cavsp(2) documentation will be described later in this document.

Configuration File

stimpres looks for the file C:\ETC\STIMPRES.CFG upon invocation. The file is optional, so stimpres will run without it. It is simply a convenience file for setting command line options that you typically use. C:\ETC\STIMPRES.CFG is an ASCII file. Each line consists of options that you would normally type on the command line. You may specify one or more options per line. You could, for example, set the default font to be tms38b.fnt by putting the line


-font tms38b.fnt

in the STIMPRES.CFG file, and then you would not have to type that option every time you run the stimpres program. The stimpres program will behave as though any options specified in the STIMPRES.CFG file were typed on the command line.

You can add comments to the STIMPRES.CFG file by preceding them with the "#" character.

Differences Between Vvsp/Cavsp and Stimpres

New Graphics Image Types

vvsp(2) /cavsp(2) graphics images were limited to the proprietary CRI (Compressed Raster Image) format and PGI (Plot Graphics Image) file types. In addition to CRI and PGI graphics file formats, stimpres also supports industry standard BMP, PCX, and JPEG file formats. The corresponding image types for scenario file syntax are:


bmp=bitmap-file
jpeg=jpeg-file
pcx=pcx-file

Embedded Color Palette Information

Each of the graphic file types BMP, JPEG, and PCX, can incorporate a color palette within the graphic file itself. The way this embedded palette information is used by stimpres is dependent on a few factors. There are several ways in which the treatment of Color Palette Information in stimpres differs from the way vvsp(2) /cavsp(2) dealt with Palettes. First of all, in stimpres the Color Palette can change with every image. This is in contrast to the vvsp(2) /cavsp(2) handling of palettes, where the color palette was required to be the same across all visual images in a given run of the program.

How does stimpres decide which palette to use?

This is a slightly complicated question to answer. There are two parts: first, we need to identify all of the potential sources of palette information for a given image; second, we need to identify the priorities of each potential palette source when more than one palette is associated with a particular image.

Before getting to the answer, consider a possible situation: your experiment uses a Standing Background Image that has an embedded palette; call this file sbg.jpg. A particular image displays an image that has its own embedded palette as well; call this file image1.jpg. Then let’s say, you have specified a default palette to use on the command line; call this file mycolors.pal. Only one palette can be in use at any given time, so when it is time to display image1.jpg, which of these 3 palette files should be employed? That’s what we hope to answer in this section.

Sources For Palette Information:

There are several sources for palette information. They are the following, listed in order of increasing priority:

1. The Default Stimpres Palette: this is the palette that is loaded automatically when stimpres starts. It is the palette that is used when no other palette information is available. For example, when your stimulus image is a text string (e.g. text="Hello Everybody!"), the color used to draw the text is determined from the current foreground color and from the default palette.    There are 2 possibilities for this default palette. Either it is the one that was defined
with the vvsp(2) program, which we call the ERPSS palette (the default behavior), or it can be the VGA palette that is loaded automatically on the VGA card. You get the VGA palette to be the default palette by using the -vga command line option.

2. The Override Default Palette: This is the palette that can be specified by the experimenter either by using one of the palette command line options (-pal, -bmp_pal, -jpeg_pal, -pcx_pal), or by using the GLOBAL state change command within the scenario file to override the default palette by specifying one of (pal=…..., bmp_pal=…..., jpeg_pal=…..., pcx_pal=…...). The Global State change command is described later in this document.

3. Palette Embedded In Stimulus Image: this is the case when the stimulus image has an embedded palette, as in the case of JPEG files, and some BITMAP (.BMP) files.

4. Scenario File Stimulus Optional Parameter: this is the case when the scenario file has one of the optional parameters (pal=…..., bmp_pal=…..., jpeg_pal=…..., pcx_pal=...) for a particular stimulus.

5. Standing Background Image With Embedded Palette: this is the situation when a standing background image has been specified on the command line or with a GLOBAL state change command within the scenario file.

6. Forced Palette: the experimenter can specify a palette that is always used, no matter the situation, and that is called the forced palette. It can be specified either on the command line with the one of the -forcepal options (-forcepal, -forcebmp_pal, -forcejpeg_pal, -forcepcx_pal), or with a GLOBAL state change command in the scenario file.

Priority for Palette Information

When more than one palette is present for a given stimulus image, the priority above determines the palette that is loaded, with Forced Palette having the highest priority and the Default Palette having the least priority.

So, back to the example given at the beginning of this section, the palette associated with the Standing Background Image (sbg.jpg) is the palette that would be used to display the stimulus image (image1.jpg).

When a stimulus image has an embedded palette, but that palette isn’t used because some higher priority palette is also present (scenario file stimulus optional parameter, standing background image with embedded palette, or forced palette), then stimpres finds a nearest color match for each pixel in the graphics image by finding the shortest Euclidean distance between the color in the graphics image file and the colors defined in the color palette in use.

Note that the use of the palette options will effect how fast images can be changed. For example, if the -forcepal option is used on the command line, then significant processing time will be saved when loading the graphics images onto the video card memory, as no palette information will have to be loaded with each image. A 256 color palette is 768 bytes, and can take about 0.3 milliseconds to load onto the graphics card. This can be a significant amount of time if you are trying to load a new, large graphics image every 16.67 millisecond, as you might if you are trying to load a new image with every vertical retrace cycle.

Adding

Decorations Such as Borders or Fixation Marks to Images with Embedded Palettes

One might think that a convention for palettes is to reserve the color 0 for black and the color 255 for white, but this is not so. An image’s embedded palette may contain neither black nor white. So how does one present consistent features such as a black border or white fixation mark on images with varying palettes? The answer is to use image manipulation software to decorate the images as desired. It could be tedious editing many images by hand but the command-line-driven convert utility from the ImageMagick open source software suite (www.imagemagick.org) can make such tasks nearly trivial.

For example, to use convert to paint a white cross at pixel 100,100 in the image contained in file input.jpg, and write the new image to the file output.jpg:

convert -pencolor White -draw ’text 100, 100 +’ input.jpg output.jpg

If you don’t like the plus character there are graphics primitives like lines, circles, rectangles to get what you want and where. Wrap it up in a shell script and voila ... consistent white crosses where you want them with embedded palettes:

#!/bin/bash for f in *.jpg; do convert -pencolor White -draw ’text 100, 100 +’ ${f}.jpg ${f}_new.jpg
done

The convert utility can be thought of as a command line Photoshop, so this is a general strategy for batch processing jpgs, that is the same trick can be used to resize, crop, composite, etc..

Graphic Resolution

vvsp(2) /cavsp(2) set the graphic resolution to 640 (horizontal) by 480 (vertical) pixels with 8 bit (256) colors. By default stimpres sets the graphic resolution to 1024 (horizontal) by 768 (vertical) pixels with 8 bit (256) colors. Users may set a specific graphic resolution by using the -res xres yres command line option. The 4:3 aspect ratio ought to be maintained when setting a custom resolution. Popular resolutions would include 640x480, 800x600, 1024x768 (default), 1152x864, and 1280x1024. stimpres will always use 8 bit color resolution.

Dynamic Image Loading

vvsp(2) /cavsp(2) loaded all text and graphics images into memory before running the program. This enabled the programs to switch between images very quickly, but limited scenario files to as few as one large graphics image per file. stimpres loads stimuli throughout the run of the program, removing images from memory after their presentation in order to make room for more images. The result is that there is no fixed limit to the number and size of graphics images that can be presented in a run of stimpres.

Fonts

vvsp(2) /cavsp(2) used a proprietary font file called the ERPSS Raster Font format. stimpres supports industry standard Windows 2.x style bitmap font files, a number of provided MGL 1.x bitmap and vector fonts and industry standard TrueType fonts. TrueType fonts (easily identified by font file names with the extension .ttf) are scaleable fonts; for stimpres adjust the size by either the -fontsize command line option or the fontsize scenario file image option. Note that fontsize is analogous to the pointsize parameter used for fonts in common desktop publishing applications.

Font files are located in the FONTS subdirectory under the SCITECH directory, typically C:\SCITECH\FONTS. However, a full pathname can be given if a font file is in another directory (e.g. stimpres myscen.scn -font C:\MYFONTS\COOLFONT.TTF).

ASD File Enhancement

The ASD file format (Audio Stimulus Description File) is backward compatible with the ASD file format for cavsp(2) . The ASD file format specifies event codes that are to be emitted during the playback of a .WAV audio file. ASD files are ASCII files that have as their first line the name of a .WAV file, subsequent lines consisting of a millisecond offset and an event code. For example, to play the .WAV file myaudio.wav, and emit event code 2 at 200 ms and event 4 code at 400 ms into the playback of the file, the .ASD file would look like this:


    myaudio.wav
    200  2
    400  4

The Enhanced form of the ASD file now allows you to specify visual images to be presented during the playback of an audio file. Any visual image type that is allowed in a scenario file (including visual image options such as color=, font=, xoff=, and + for multiple image continuation, etc.) can be used in an ASD file. Place the visual image information after the event code on the ASD file line where you want the image to be displayed. For example, if you wanted to display the word “SURPRISE” at 400 ms into the playback of the previous example, and then overlay the word “SURPRISE” with the JPEG image mypic.jpg at 600 ms, the ASD file would like like this:


    myaudio.wav
    200 2
    400 4 text=SURPRISE
    600 6 text=SURPRISE +
    jpeg=mypic.jpg

GLOBAL Display Parameter Changes

stimpres scenario files have been enhanced to incorporate a "Global Parameter Change Command". The idea is to change the default behavior during the run of a scenario file. For example, you might want to use one Standing Background Image for a significant portion of your scenario file and another Standing Background Image for another portion of your scenario file. Or, you may want to change the default font somewhere in the run of your scenario file. Or, you may want to change the default palette. This can all be accomplished by placing a GLOBAL command in your scenario file. The global command consists of the keyword GLOBAL placed as the first word on a scenario file line, followed by one or more display parameters of the form parameter=value. Note that you can have multiple GLOBAL command lines in a scenario file, and that each GLOBAL command can incorporate more than one global parameter change. The parameters that can be changed via the GLOBAL command are:


  Forced Palette
    Forcepal=palettefile
    forcebmp_pal=bmpfile
    forcejpeg_pal=jpegfile
    forcepcx_pal=pcxfile
  Default Override Palette
    pal=palfile
    jpeg_pal=jpegfile
    bmp_pal=bmpfile
    pcx_pal=pcxfile
  Default Font and Fontsize
    font=fontfile
    fontsize=size
  Default Foreground Color
    fgc=colornumber
  Default Background Color
    bgc=colornumber
  Standing Background Image
    sbg=crifile
    sbg_bmp=bitmapfile
    sbg_jpeg=jpegfile
    sbg_pcx=pcxfile
    sbg_pgi=pgifile
  X offset
    xoff=n
  Y offset
    yoff=n
  Default Label Origin
    lblo=n

For example, to force the use of the palette file “blknwht.pal” at some point in the scenario file, put the line:

GLOBAL pal=blknwht.pal

on the line immediately before the stimulus at which you want the new palette to begin taking effect.

Video Hardware and Timing

vvsp(2) /cavsp(2) were restricted to using the TSENG ET4000 video chip. stimpres employs the MGL graphics library of SciTechSoft which supports virtually all current video hardware that complies with the VESA VBE1.2 and VBE2.0 video standards. If a particular card isn’t supported, a driver (Scitech Display Doctor) can most likely be obtained for that card at SciTechSoft’s website, www.scitechsoft.com. Presently, the driver file in use is the free Nucleus Display Driver and is installed in the C:\SCITECH\DRIVERS directory at installation time. Newer versions of this file will support newer video hardware.

At startup, stimpres times the vertical sync on the video hardware for 4 seconds to determine the vertical refresh rate. It then uses that calculated timing to time-lock the onset of each visual stimulus with the next vertical sync. (The vertical sync period is the time in which the video monitor’s electron gun is sweeping from the lower right hand corner of the display back to the upper left corner of the display. The electron gun is off during this period, and this is the time when any change to the video screen must be made in order to prevent flickering and/or image "tearing"). The refresh rate is dependent on the video card and the resolution, and is set at the default refresh rate for the video card at the resolution being used. The resolution and refresh rate are displayed momentarily during stimpres initialization; for the current video cards in the Kutas lab (ATI XPERT 98 Rage Pro Turbo 8MB AGP 2x SVGA) at the default resolution of 1024x768 the refresh rate is 60 video frames per second (16.67 milliseconds per frame). Since all visual image changes must be made during the vertical retrace period, scenario file images will be displayed and erased during the vertical retrace period immediately following the time specified by the SOA/DUR for that image. For example, If you specify that an image should be displayed for 30 milliseconds, but the vertical sync period is 16.67 milliseconds, your image will be displayed for approximately 33 milliseconds.

Also note that if you specify a combined image that has both a visual and audio component, that image can only be presented at vertical sync time; therefore, the stimulus will be displayed and the audio will start to play at the vertical sync immediately after the requested start time.

Audio Hardware

The cavsp(2) program required MediaVision’s Pro Audio Spectrum audio card which is no longer available. At this time stimpres requires the industry standard Sound Blaster sound card with a DSP of 4.0 or greater. Unfortunately many “Sound Blaster Compatible” cards are not truly compatible with the Sound Blaster DSP. Future implementations of the stimpres program will likely support more sound card architectures, though audio device independence is becoming more and more difficult as manufacturers are increasingly reluctant to release their low-level hardware descriptions to programmers.

Audio Stimulus Timing Issues

The nature of PC audio hardware limits the effective time resolution for output of event codes concurrent with audio playback. This is especially important to be aware of when using the ASD file format to emit event codes during playback of an audio file. The SoundBlaster audio hardware is good, but not perfect at playback. The system works like this: during playback, stimpres monitors the progress of the audio playback by programming the SoundBlaster card to cause a hardware interrupt every time it completes playback of 256 bytes (128 samples). This is called a "block" of audio data. The event codes that are listed in an ASD file are assigned to a particular block. As soon as that block of 128 samples has played, the hardware interrupt will be generated, and the interrupt handler code will check to see if there is a corresponding event code, and emit it if there is one.

You can use this information to determine the "granularity" of the ASD file timing. For example, if you have a Mono .WAV file, sampled at 44.1Khz, that translates to 2.9 milliseconds per 256 byte block (128 samples / 44,1000 samples/second = 2.9 milliseconds). In other words, an event code specified in an ASD file could be emitted 2.9 milliseconds after it was requested. This granularity can be further affected by the processing of the video vertical sync period. Combine this information with the rate at which the digitizer system is digitizing EEG data (a sampling rate of 250 Hz for a sample period of 4 milliseconds is typical). It is conceivable, then, that an event code could be recorded 8 milliseconds after it was requested by the time you factor in both the stimpres event code timing granularity and the digitizer sampling granularity.

Experimenter Generated Event Codes

The experimenter can manually generate event codes by pressing the Function Keys F1-F12. By default, pressing F1 causes stimpres to output event code 16731, F2 outputs 16372, F3 outputs 16373, etc. The codes that are generated can be specified via the -mapexpcodes command line option. The user creates an ASCII Experimenter Event Code Map File that contains lines of the form


    f1=code_for_f1
    f2=code_for_f2
    etc.

stimpres will replace the default code for a particular function key with the code specified in the mapfile.

Command Line Differences

stimpres implements a few command line options that vvsp(2) /cavsp(2) did not. These are the following:


-bmp_pal bmpfile
-pcx_pal pcxfile
-jpeg_pal jpg file

These options augment the -pal command line option. BMP, PCX, and JPEG graphics files all can have an embedded color palette. These command line options set the override default palette for the current run of stimpres.


-sbg_bmp bmpfile
-sbg_pcx pcxfile
-sbg_jpeg jpgfile
-sbg_pgi pgifile

These options augment the -sbg command line option by allowing any of the supported graphics files to be used as a standing background image. When a particular video frame is being prepared during the run of the program, any standing background image is first copied to the video frame, then the specified image is drawn. These options are often used to draw a frame around lines of text.


-font fontname
-fontsize size

These options specify which font file and fontsize (analogous to pointsize in many word processing programs) to use when displaying text. See the description of fonts above for more info. Note that the -fontsize parameter does not apply to all font files. It is generally used when specifying a TrueType font file. If not specified, the default fontsize is 18.


-res xres yres

This option lets the user specify the graphics resolution in pixels for the color display device. The default resolution is 1024x768. When the -res option is specified, the stimpres program attempts to initialize the display device to the requested resolution, and will exit with an error message if it is not able to do so. Typical alternate resolutions are: 1280x1024, 800x600, 640x480, 320x240. Note that when lower resolutions are used, it is typically much faster to display the images, thus you may choose to use a lower resolution when doing video-like segments with very fast inter-stimulus intervals.


-vgapal

This is a little-used option that causes the default palette to be the VGA hardware palette rather than the ERPSS palette defined with the original vvsp(2) program. This option was introduced to expedite the stimulus preparation time for one idiosyncratic experiment, and probably should not be used in general.


-forcepal palfile
-forcejpeg_pal jpeg
-forcebmp_pal bmp 
-forcepcx_pal pcx

These options set the "Force" palette. This is the highest priority palette, and overrides all other available palettes for a given stimulus.


-nocodes

This disables the processing of digital event codes. This is especially useful when testing a scenario file on a computer that does not have the necessary hardware for the event code processing.


-noaudio

This option disables the audio subsystem of stimpres. This is useful for running a visual stimulus only scenario file on a system that does not have the necessary audio hardware installed.


-noresp

This option renders all conditional branching meaningless, and causes all response codes to be ignored.


-mapexpcodes mapfile



See the description above for Experimenter Generated Event Codes.



-prep delta_msec

This option is used to increase or decrease the default amount of time that is allowed for preparing the next stimulus when using the branching features and when using the wait-for-response features.

By default stimpres stops accepting button presses 100 ms before the end of the duration of a branch stimulus to allow itself time to prepare the next stimulus. This 100 ms can be adjusted up or down delta_msec with the -prep option. There are two situations when this may be useful. First, if the ISIs on branch stimuli are sufficiently large to allow enough time for preparing the stimuli that follow, the 100 ms can be reduced to 0 ms (using -prep -100) to allow the acceptance of responses during the entire duration. Second, if the ISIs on branch stimuli are small or 0, the 100 ms can be adjusted up or down, trading between time needed to prepare the stimuli that follow and time spent accepting responses.


For example, a scenario file might contain something like:

1000 500 1 text="press 1024 or 1025" br="1024 1024" br="1025 1025"
1000 500 2 text="no response" end
1000 500 3 text="Got a 1024" label=1024 end
1000 500 4 text="Got a 1025" label=1025

stimpres’ default behavior when presenting the first stimulus is to wait 400 ms (100 ms less than the 500 ms duration) after the start of the stimulus for either a 1024 or 1025 response, then if neither has been received, ignore button presses altogether and begin loading the "no reponse" stimulus; if -prep -70 is specified on the command line, the behavior will be to wait 470 ms (100 - 70 = 30 ms less than the 500 ms duration) after the start of the stimulus for either a 1024 or 1025 response.

There is a similar situation when the stimulus that has the branch option also has a wfron or wfroff option. In this case, stimpres waits indefinitely until it receives a response or until the experimenter cancels the Wait For Response state by pressing "C". Once one of these happens, stimpres gives a grace period of delta_msec for the next image to be loaded before exiting with a "stimulus not loaded in time" error. (note: at the time of this writing, it doesn’t seem like the -prep option is adjusting this grace period. Possibly a program bug?)

-120Hz vvsp(2) /cavsp(2) option NOT implemented

The –120Hz option from vvsp(2) /cavsp(2) is not available in stimpres. This option was only available because of an undocumented hardware glitch discovered in certain video card implementations that used the TSENG ET4000 video chip. stimpres makes no assumptions about the refresh rate of the computer’s video card. Instead it calculates the vertical refresh rate each time the program is run and bases its timing on the measured vertical refresh rate.


Table of Contents