Docs: ploterps

Introduction

Ploterps (E1) is a program that is designed to allow quick and easy plotting of ERP data. By expending more effort, it is also possible to produce plots in almost any format. Publication-quality figures can be created directly, or the plots can be imported into a graphics program such as CorelDraw for beautification.

Ploterps provides the user with about 40 commands to control the manner in which data are plotted, and a series of these commands is typically read from a "command file" that the user creates with a text editor. Commands can also be read from the UNIX command line, and it is possible to create quick-and-dirty plots without a command file by specifying an automatic plotting command on the command line. Ploterps utilizes the standard ERPSS graphics commands and options, and the user who is unfamiliar with these should read the Multiplot Tutorial and User's Manual before attempting to use ploterps.

Usage

One invokes ploterps like this:

Plot_device is any of the ERPSS plotting devices that are available on the system you are using (e.g. epft, las, save). Commandfile is a text file consisting of ploterps commands. Ploterps commands can also be placed on the UNIX command line, in which case they are executed before the commands in the command file. If commandfile is "-", the standard input stream is used as the source of commands; if commandfile is "none", only commands from the UNIX command line will be executed.

Automated Plotting

A special command, "autoplot", can be used to produce plots without specifying any format information. The syntax of this command is:

The files parameter is replaced by a list of one or more files (separated by commas) and the bins parameter is replaced by a list of bins that should be plotted for those files (again separated by commas). The optional parameters space=, scale=, and rect= specify the amount of space between horizontally adjacent channels (0.0 - 1.0), the scaling of the plot (in microvolts), and a rectangle that bounds the plot (e.g., rect=0,1,1,0 -- left, top, right, bottom). There are various parameters (e.g., calibration bar size) that are normally set to default values, but which can be modified with other commands described below. The default parameters for this command cause the plots to be drawn negative "up", with 5 uV calibration markers.

In most cases, this command will be used to overlay a set of several bins from a single file. An example of this, the output of which can be found at the end of this document, is as follows: 


	ploterps epft none autoplot testdata 2,3,4 scale=12
In this example, epft indicates that the data should be plotted on the epf_tool plot device and none indicates that no command file should be read. The autoplot option then specifies that bins 2, 3, and 4 of file "testdata" should be overlaid and the data should be plotted with a scale of 12. The exact definition of the plotting scale will be provided later, but the important thing to note is that larger scale values lead to smaller ERP waveforms.

If multiple files are listed in an autoplot command, each file will be plotted on a separate page, with the bins from a file overlaid. If the bin list and file list are reversed on the command line, however, the organization of bins and files will be reversed. For example, to overlay the data from files avg1, avg2, and avg3 using bin 5, the command would be 


	ploterps epft none autoplot 5 avg1,avg2,avg3
Ploterps determines whether the bins or files are listed first by simply checking the first character of the first argument to see if it's a digit, in which case it assumes that the bins are listed first; it is therefore necessary that file names do not begin with digits. When multiple pages are plotted, ploterps (E1) waits for the user to press the return key between pages (unless the plotdevice is a hardcopy device).

General Command File Format

The ploterps command file should be formatted according to the specifications described in the Multiplot Tutorial and User's Manual, which are briefly summarized here. Commands and arguments are separated by white space (spaces, tabs, or newlines immediately preceded by a '\\'). Any line or argument that begins with a '#' character is treated as the beginning of a comment, and the rest of the line is ignored. All commands and arguments are converted to lower case, so the original case is irrelevant. Commands may have mandatory arguments, which occur in a fixed order, and/or optional arguments, which may occur in any order. If ploterps detects an error either in syntax or during the execution of a command, it will print an error message containing the line number at which the error was detected, and continue processing the input, if possible.

When a command file is used, plotting consists of 4 conceptual steps. First, a set of "positions" is defined, each of which is a rectangle in which a baseline and a set of overlapped ERP waveforms are drawn. In a typical case, there will be one position defined for each electrode location, and these positions are typically laid out in a rectangular grid. The second step is to draw the baselines and channel labels for each position. The third step is to select various bins and data files and draw the actual ERP waveforms. The final step is to add additional text and graphics to create titles, legends, etc. These steps do not necessarily occur in this order, but these steps are present in some form in almost every ploterps command file. In general, there are no rules about the order of commands except that some commands rely on parameters that are set by other commands, and the parameters must be set before the command can be executed properly.

An example will help to make the various steps and commands clearer. The following text represents a command file named "ploterps.example2" that can be found in /usr/erpss/manuals/plot. Line numbers have been added to the beginning of each line to facilitate discussion, but should not be included in a real command file. The output of this command file (plotted with the command "ploterps psprne ploterps.example2") can be found in Figure 1. 


	01 file /usr/erpss/doc/manuals/plot/testdata	# Load a file
	02 bin 0					# Load a bin
	03 
	04 cal -5.0			# Set cal marker size
	05 timewindow -95 800		# Set plotting epoch
	06 scale 8.0			# Set scale for drawing of waveforms
	07 autoposition 6 2 space=.05 rect=.05,1.20,.95,.00 # Create positions
	08 
	09 
	10 # Draw titles
	11 textstyle laborigin=TM textsize=6.0 italics medium
	12 text 0.48 1.32 "Example 2"			# Draw title
	13 textstyle laborigin=TM textsize=4.0 simplex thin
	14 text 0.48 1.27 "Subject: %v" v=subdesc	# Draw subject name
	15 
	16 # Draw legend
	17 textstyle laborigin=LM textsize=4.0 thin
	18 line 0.54 0.10 0.63 0.10 solid thin
	19 text 0.65 0.10 "Non-Target"
	20 line 0.54 0.07 0.63 0.07 dotted medium
	21 text 0.65 0.07 "Target"
	22 
	23 # Draw baselines
	24 gridstyle thin		# Use thin lines for baselines
	25 calmarks on			# Turn on automatic cal mark drawing
	26 polindicators off		# Turn of automatic polarity indicators
	27 tickmarks on			# Turn on automatic tick mark drawing
	28 ticks 100			# Draw ticks every 100 msec
	29 ticklength 0.02		# Ticks are .02 units long
	30 ticklabels off		# Don't label ticks
	31 drawbaseline 0-9		# Draw the grids for channels 0-9
	32 autobaseline off		# Don't auto-draw baselines
	33 
	34 # Draw calibration legend
	35 polindicators on		# Include polarity indicators
	36 calmarks off			# Don't auto-draw cal marks
	37 drawbaseline 10		# Draw the baseline (w/o cal marks)
	38 drawcal 10 calorigin=tro laborigin=ML textsize=4	# Draw cal marks
	39 ticklabels on		# Turn on tick labels
	40 ticks 200			# Draw the ticks every 200 msec
	41 drawbaseline 10		# Draw baseline again with tick labels
	42 
	43 textstyle textsize=3.5 simplex
	44 chanlabel 0-9 0-9		# Draw channel labels at each position
	45 
	46 bin 2			# Load bin 2
	47 linestyle solid thin		# Set linestyle to solid/thin
	48 drawbin 0-9 0-9		# Draw waveforms from current bin
	49 
	50 bin 3			# Load bin 3
	51 linestyle dotted medium	# Set linestyle to dotted/medium
	52 drawbin 0-9 0-9		# Draw waveforms from current bin

Figure 1

The first things that are specified in this command file are a file and a bin ( lines 01-02). These are specified first so that any future commands that need information from a file (such as the subject description) or a bin (such as the channel labels) will know where to get this information.

The next section of the file specifies the information needed to set up the drawing positions. The size and polarity of the calibration marker ( line 04) are specified in the "cal" command, which indicates that these markers should show 5.0 microvolts and that negative should be plotted upwards. The "timewindow" command specifies that the plotting window should extend from 95 msec pre-stimulus to 800 msec post-stimulus. Note that this window can be longer or shorter than the actual data epoch, and only the portion of the waveform that fits within this time window will be plotted. The next command ( line 06) indicates that a scale of 8.0 microvolts should be used, meaning that each position will have a height of 8.0 microvolts. The final command in this section ( line 07) sets up the actual positions. The positions can be set to a regular grid using the "autoposition" command, as in this example, or a set of arbitrary positions can be defined with a set of "position" commands. Each position is a rectangle, and the "autoposition" command divides the screen into a set of rows and columns of equal-size rectangles (6 rows and 2 columns in the present example). The "rect=" option allows the user to specify the overall dimensions of the area that will be divided into the individual drawing rectangles (the coordinates for this option are left, top, right, bottom). The "space=" option causes the program to leave a bit of space between adjacent rectangles. Each drawing rectangle in this grid is assigned a number, beginning with 0 at the upper left corner and increasing by one as we move across each row and then down the screen (e.g., position 0 is top row, left column; position 1 is top row, right column; position 2 is 2nd row, left column; position 3 is 2nd row, right column; etc.).

The next job is to draw titles and a legend that indicate what waveforms are being plotted. These tasks use the basic text and line commands that are available in most of the ERPSS graphics programs (see the Multiplot Tutorial and User's Manual for more information). The ploterps program adds an additional feature to the "text" command, however, allowing header information from the current file and bin to be specified in a text string. This is shown in line 14, which plots the string "Subject: %v" followed by the option "v=subdesc". Whenever the "text" command encounters the string "%v", it replaces "%v" with the header variable specified in the subsequent "v=" option. In the current example, this feature is used to print the subject description variable in the title. A list of the available header variables is found in Appendix B.

The next step in this example is to draw the baselines for each of the channels. First, several parameters are specified: use thin lines ( line 24); draw calibration markers on each baseline ( line 25), but without polarity markers ( line 26); draw ticks on each baseline ( line 27) at 100 msec intervals ( line 28) using ticks that are .02 units long ( line 29); don't draw text labels for each tick mark ( line 30). Finally, the baselines are drawn ( line 31). By default, a baseline is drawn whenever an ERP waveform is drawn, but here we draw the baselines explicitly and therefore don't want them drawn again when the waveforms are drawn. This is achieved by turning off automatic baseline drawing on line 32.

A time and voltage calibration grid is also drawn in position 10 with the commands that begin on line 35. This is accomplished by first drawing a baseline without any calibration markers ( lines 35-37), using the previously defined spacing. Next, a calibration marker is drawn ( line 38). Finally, we redraw the baseline with tick labels on and an interval of 200 msec between ticks. This will cause the tick marks to be redrawn, but this is necessary in order to put labels at ticks every 200 msec.

The observant reader may note that 12 positions were defined with the "autoposition" command, but only 11 are used (10 for drawing ERP waveforms and 1 for plotting the calibration grid). This is perfectly okay: defining a position does not entail that one actually use that position.

The next step in this example is the drawing of channel labels at each position with the "chanlabel" command ( line 44). The arguments following this command specify the channels from the data file (channels 0-9) and the positions in which the labels from these channels are to be plotted (positions 0-9). The data channels are simply mapped, in order, onto the positions (e.g., "chanlabel 2-4 0,2,10" would map channel 2 to position 0, channel 3 to position 2, and channel 4 to position 10).

The final step in this example is to plot the actual ERP waveforms (lines 46-52). In order to draw data, it is necessary to load the desired bin ( line 46). The linestyle that will be used for drawing the waveform is then specified with the "linestyle" command ( line 47). Finally, the data from the selected bin are drawn with the "drawbin" command. This command allows the user to specify a set of channels from the data file and draw them at a set of positions, using the same mapping as was used for the "chanlabel" command. After the data from one bin are drawn, they are overplotted by the data from another bin with a different line style ( lines 50-52).

In many cases, it is desirable to draw several pages of plots with a single command file. A new page can be specified with the "newpage" command, which clears the screen on video plot devices and loads a new piece of paper in hard copy devices. On video devices, it is useful to make the program pause at the end of drawing a page so that it can be examined before it is erased and replaced with the subsequent page. This can be achieved with the "pause" command, which causes the program to wait for a RETURN to be entered from the standard input (usually the keyboard). If this "pause" command is included in the command file, but one wishes to make a hard copy, the pause can be disabled by including the "nopause" command on the UNIX command line (e.g., "ploterps psprne plotfile nopause").

Exporting Plots to Other Programs

Although ploterps can create publication-ready figures of considerable complexity, it is often useful to export plotted waveforms from ploterps into commercial graphics programs such as CorelDraw. Such programs allow mouse-driven, visual, interactive plotting and have more extensive features. Exporting data from ploterps can be accomplished via PostScript plot filters that were written by Clif Kussmaul. These filters are named " mpsf" for "Monochrome PostScript File" and cpsf" for "Color PostScript File" (these will usually be prepended with a "p" to indicate portrait mode). These plot filters convert the output of ERPSS graphics programs into an "Encapsulated PostScript" (EPS) format and save the result in a named file. For example, to save the output of the above example in a color portrait EPS file named "EPSsave", one would invoke ploterps as "ploterps pcpsf:EPSsave ploterps.example2".

Once saved in an EPS file, the image can be imported into a graphics program (see the manual for the specific program that you are using). The entire plot will be stored as a single "group", and it will be necessary to "ungroup" this image in order to apply any graphical operations to individual parts of the image. For reasons that are somewhat obscure, the "ungroup" operation must be executed twice.

ERPSS programs treat text as complex sets of line segments, and all information about characters and fonts will be lost when data are exported from ploterps; when these images are imported into other graphics packages, the text will look terrible. It is therefore recommended that all text be eliminated from the command file or removed as soon as the image is imported into the graphics package.

Command File Argument and Parameter Conventions

Many of the commands for ploterps (E1) employ options that specify attributes such as font type and line color, and these are defined in the Multiplot Tutorial and User's Manual. The most common options are line style options (abbreviated "line_opts"), which consist of:

and text style options (abbreviated "text_opts"), which consist of the all of the line style options plus: These options specify parameters that are used for plotting lines, shapes, grids, labels, etc. There are default values for these parameters, but different sets of defaults are used for different commands. The defaults are controlled by three commands, textstyle, linestyle, and gridstyle, and these sets of defaults are applied to the drawing of text, lines, and grids (baselines), respectively. For example, the command "linestyle thick" will cause ERP waveforms to be drawn with thick lines, whereas the command "textstyle thick" will cause text to be drawn with thick lines. One non-obvious application of the default values is that the gridstyle defaults are used to control the format of tick labels when baselines are being drawn, but the textstyle defaults are used to control the format of the channel labels (allowing these to have different formats).

Coordinate System

Many commands allow user-defined positions text, lines, plotted data, etc, on the drawing surface. The standard coordinate system is used, in which the x direction always goes from 0.0 to 1.0 (left to right) for any device, whether it is used in landscape or portrait mode. The bottom-most point on the page corresponds to 0.0 in the y direction, while the top-most point depends on the specific device in use. For most devices, which have a 4 to 3 aspect ratio (x to y available surface ratio), this will be 0.75 in landscape mode, and 1.33 in portrait mode.