|
|
Docs: merps
Merps is a Windows utility to measure event-related potentials (ERP's) in a ERPSS datafile. The original merps (E1) program was written under Unix and was thusly designed with a commandline interface, but this new version was designed to operate under Windows using a graphical user interface (GUI) to make operation simpler and faster in certain situations. For instance, if you want to quickly measure peak-to-peak amplitudes, latencies, and such among several data files, this new version will likely provide faster and more effective results. However, if you intend to use a batch file or script to pipe output results into another program, you're looking for the original version...this new version displays results to the screen, but doesn't have a facility for saving measurement results automatically to files. The remainder of this document will focus on the new Windows version of merps.
In order to use merps, you need to have one or more valid ERPSS data files. These data files are produced by avgerps (E1), and subsequent ERPSS processing files such as normerps (E1).
Start the merps program by double-clicking the merps icon.
You should see the following window appear on the display:
Choose File->Open from the pulldown menus, or click the Open icon in the toolbar to open a new data file.
meana
This function calculates the mean amplitude, in microvolts, over the measurement window. No arguments are required, and no errors are possible. The units for the value are microvolts.
max, min
These two algorithms both come in two versions: one that returns a latency value, and one that returns an amplitude value:
maxa maxl mina minlThe maximum value is the largest data value in the search window, while a minimum value is the smallest. Note that this does not necessarily correspond to a "peak", which is a local maximum or minimum (see lpeak below). No arguments are required, and no errors are possible. The units for the amplitude values are microvolts and the latency values milliseconds.
mma, mml
These two algorithms find the maximum minus minimum amplitude (in microvolts) and the absolute value of the difference in latency between the maximum and minimum, respectively. Both use the max and min routines (above), and the comments there apply. No arguments are required, and no errors are possible.
lpeak
Local peak latency. This function comes in two forms, one evaluating the latency of the largest local peak, and another the amplitude:
lpeakl sign #pts lpeaka sign #ptsBoth versions require two arguments. The first can be either the single character "+" or "-", indicating whether one desires a positive peak or a negative peak, respectively. The second argument indicates how many points should be averaged together, and is used as follows. The underlying algorithm finds the largest local extremum, either a local maximum (sign is "+"), or minimum (sign is "-"). A local maximum is defined as the largest point which is larger than the previous point and larger than the subsequent point. Because high frequency noise can cause spurious peaks, the point must also be greater than the mean of the #pts previous points and the mean of the #pts subsequent points. A local minimum is defined analogously.
This function will produce a soft error if no local peak is found, the #pts is negative or zero, or insufficient data are available before or after the measurement window to calculate the surrounding mean values. In both cases the maximum or minimum value in the window is returned. A hard error can occur if sign is neither a "+" or "-".
The units of the measurement are milliseconds referred to stimulus onset in the case of lpeakl, or microvolts in the case of lpeaka.
flpeak
Fractional local peak latency. This function also comes in two forms, one evaluating the latency and the other the amplitude of a point on the leading edge of a peak:
flpeakl sign #pts fract flpeaka sign #pts fractInitially, lpeak is used to find an extremum in the search window, using the first two arguments (sign and #pts); the comments under lpeak apply. Note that if a local extremum cannot be found, the maximum or minimum in the window is taken, and a soft error noted. Next, a "fractional amplitude" is calculated by taking the third argument (fract, a fraction between 0.00 and 1.00) times the value at the extremum. Then, data points at successively smaller latencies from the extremum are compared to the fractional amplitude. The point at which the data fall below (in the case of a maximum) or surpass (in the case of a minimum) the fractional amplitude is noted, and used to print either a latency value (in milliseconds), or the fraction of the amplitude of the peak (in microvolts). If fract is between 1.00 and 2.00, the algorithm will move through successively larger (rather than smaller) latencies until the data fall below (2.00-fract) times the maximum amplitude. Thus, if fract is 0.2, the onset of a peak will be found at a point preceding the peak with an amplitude of 0.2 times the peak amplitude, and if fract is 1.8, the offset of the peak will be found at a point following the peak with an amplitude of 0.2 times the peak amplitude.
This function will produce a soft error if no local peak is found, the #pts is negative or zero, or insufficient data are available before or after the measurement window to calculate the surrounding mean values. In both cases the maximum or minimum value in the window is used. Additionally, if the fractional amplitude is zero (perhaps due to small data values or truncation errors), a soft error is recorded. flpeak also checks that the waveform crosses zero before the latency of the fractional amplitude, also generating a soft error if it does not. Another type of soft error occurs when the peak does not fall above the baseline for positive peaks or below the baseline for negative peaks; an arbitrary approximation is returned when this error occurs. Hard errors are returned if sign is not one of "-" or "+", or if fract is less than or equal to 0.00, or greater than or equal to 1.00.
fa
Fractional area. This function again comes in two forms, one evaluating the latency and the other the amplitude of a point in the search window:
fal sign fract faa sign fractBoth forms require two additional arguments; sign can be one of "+", "-", or "+-", indicating that only positive area, negative area, or the true algebraic area should be used in the algorithm, respectively. The second argument fract is a decimal fraction between -1.00 and +1.00. The fa algorithm first determines the total area of the specified polarity in the search window. Then, beginning at the earliest latency in the search window and moving towards longer latencies, area of the appropriate polarity is accumulated until its absolute value exceeds fract times the absolute value of the total area; for fal the latency of this point is returned, in msec, for faa the fractional area is returned, with units of microvolts time msec. If fract is negative, the fa algorithm essentially inverts the accumulating area before comparing it with the absolute value of the total area, which is necessary when one is searching for the fractional amplitude or latency of a negative peak.
Hard errors arise if sign is not one of "+", "-", "+-", or "-+", or if fract is not between 0.00 and 1.00. If no area of the specified polarity is present (e.g., if you ask for a fraction of the positive area and the area is entirely negative), a soft error occurs. The value resulting from this soft error is equal to the onset of the measurement window for fal or 0 uV for faa. Note that these values are completely artificial and may bias your results, so occurrences of this soft error should be examined closely.
Merps reads commands from either the standard input or a measurement command file (mcf) to set various parameters pertaining to performing a measurement or to select a measurement function. Commands that set parameters are termed measurement parameter commands, while commands that actually cause measurements to be made and the values placed in the output file are termed measurement commands. Before measurements can be made, one must define the data file(s) that will be measured using one or more file commands or by using the -f option during the invocation. The particular bin(s) in each data file must also be defined using a bins command, as well as the channel(s) using a channels command, and (optionally) the processing function(s) with a procfuncs command. The window over which the measurement algorithm is applied also must be set using a window command, and, finally, the order to perform the measurements must be specified using an order command. Once these parameters are set, one or more measurement commands can be executed, yielding the output measurements.
The order in which the data files and the bins, channels, and processing functions in those files are measured during the execution of a measurement command is based on an implied, factorial model involving a number of factors and levels of those factors. Beware, however, as these factors are almost certainly not those actually being analyzed experimentally, but rather an algorithmic mechanism for succinctly representing the order in which measurements are to be made. These measurement factors are the data files, bins, processing functions, and channels. Each factor has one or more levels, and each level of a factor is indexed by a non-negative integer. The index is used to select the actual level of the corresponding factor. For example, if four bins were defined by a bins command as 3, 5, 4, and 1, then there are four levels of the bin factor with indices from zero to three, corresponding to bins 3, 5, 4, and 1. Note that the order of the bins that are selected as the bin factor index moves from 0 to 3 is the same as the order that the bins were specified in the bins command. Each of the other factors work similarly; for the files factor, the order of appearance of the file commands determines the order of the files.
This scheme is useful in thinking about the order command, which specifies the order in which the indices of the factors increment and thus the order of the measurements in the output file. For example, the order command
order files channels binswill cause all the bins for a specific file and channel to be measured before the next level of the channel is selected. I.e., the indices for the files factor move slowest, those for the channels factor next fastest, and those for the bins factor the fastest. Usually one will perform a repeated measures analysis of variance on the measurements; if one is using ranova (E1) or anovae, files will probably need to "move fastest", and should thus be the last argument on the order command line.
Note that this internal model of factors and levels is not meant to correspond to a particular experimental design, and in most cases more than one experimental factor will be subsumed in the bins that are measured. Nonetheless, this scheme is flexible enough to allow most experimental measurement needs to be met by devising an appropriate mapping of the experimental factors and required order of output onto a sequence of merps commands.
Perhaps the best way to understand merps is to look at an example or two. Let's consider a hypothetical experiment where the effects of attending to stimuli on the ERPs are to be statistically evaluated. For concreteness, lets say we've presented three subjects with high and low pitched tone pips, and had them attend to one pitch and then the other in separate presentations of the same set of stimuli. Thus, for each subject, we have averaged the raw data and now have four bins as follows:
Bin Description 1 High Tones, attend High Tones 2 Low Tones, attend High Tones 3 High Tones, attend Low Tones 4 Low Tones, attend Low TonesThese data are in files named s01, s02, s03. We intend to apply a repeated measures analysis of variance to the measurements, and wish to examine the mean amplitude of the ERP at the latency from 100 to 200 msec after stimulus presentation. For various reasons, we also wish to restrict the analysis to the Cz scalp site, which happens to be channel number 3 in the data files. In the analysis, we anticipate three factors:
Factor # Levels Values Description A 2 High tone, Low tone Pitch of eliciting stimulus B 2 Attended, Unattended Effect of Attention S 3 Ss1, Ss2, Ss3 SubjectHaving established this framework for the analysis, an appropriate merps command file (mcf) would be:
file s01 file s02 file s03 bins 1 3 4 2 chans 3 order chans bins files window 100 200 meanaSome comments are perhaps in order. Note that the ordering of the data is such that the same bin and channel is measured for each subject before moving to the next bin; this is appropriate for the ranova (E1) model, since subjects "moves fastest". Also, since only one channel is being measured, the position of the chans and bins in the order command is irrelevant. Since no baseline command was included in the mcf, the entire pre-stimulus period will be used as the zero-voltage reference.
At risk of being too detailed, here is the order in which the measure will appear in the output file after merps is successfully run:
FILE BIN CHAN DESCRIPTION s01 1 3 Hi Tones, Attend Hi, Subject 1 s02 1 3 Hi Tones, Attend Hi, Subject 2 s03 1 3 Hi Tones, Attend Hi, Subject 3 s01 3 3 Hi Tones, Attend Lo, Subject 1 s02 3 3 Hi Tones, Attend Lo, Subject 2 s03 3 3 Hi Tones, Attend Lo, Subject 3 s01 4 3 Lo Tones, Attend Lo, Subject 1 s02 4 3 Lo Tones, Attend Lo, Subject 2 s03 4 3 Lo Tones, Attend Lo, Subject 3 s01 2 3 Lo Tones, Attend Hi, Subject 1 s02 2 3 Lo Tones, Attend Hi, Subject 2 s03 2 3 Lo Tones, Attend Hi, Subject 3One final comment - note that the experimental factors of underlying types of tones and attention are subsumed in the merps bins "measurement factor". The measurement factors, again, are only a mechanistic shorthand for ordering the measurements.
Note that one can specify additional measurements in the mcf by simply continuing the mcf. The commands are executed in the order they are encountered in the mcf, and the parameters from commands are retained until that command is again encountered in the mcf. Hence, if one had a between-subjects factor in addition to the two within-subjects factors in the above example, and the only difference between the measurements was the data files, one might employ an mcf similar to this one:
file s01 file s02 file s03 bins 1 3 4 2 chans 3 order bins chans files window 100 200 meana clearfiles file s04 file s05 file s06 meanawith the between-subjects factor "moving most slowly". Note that the same bins and channels are measured in the same order for the second meana command, but the files have been switched. This example also demonstrates the optional clearfiles command, which closes all currently open files and resets the number of open files to 0. The ranova model for this analysis might be:
Factor # Levels Values Description A 2 Schizophrenic, Normal Mental Competence B 2 High tone, Low tone Pitch of eliciting stimulus C 2 Attended, Unattended Effect of Attention S 3 Ss1, Ss2, Ss3 Subject within Group
Errors that occur during the execution of merps are divided into two categories: hard errors, and soft measurement errors. Hard errors occur, for example, when a file cannot be opened, there is a syntactical error in the mcf, or when an insurmountable error arises during the execution of a measurement command. Soft, or measurement errors arise when a measurement command was not successful because of the nature of the data. For example, one might be looking for a negative peak but the data are all positive over the search window. Soft errors arise only during the execution of a measurement command, and are distinguished from hard errors during a measurement command in that some value, possibly useable, is calculated and printed. For example, if one is searching for a positive local peak, but no local peaks are present in the data, the maximum value of the data in the window might be placed in the output file and a soft error noted. This maximum value might be deemed acceptable by the user, in which case one could use the measurement output file "as is". However, if a hard error occurs, the output file of measurements could not be used in subsequent analyses, as non-sensical values (if that) would be present, and the output file is removed before termination of merps if not operating in interactive mode. The description of each measurement command explains the possible errors and their causes. For both hard and soft errors, a message is printed on the standard error that is intended to help diagnose the problem.
Merps can be used interactively by supplying "-", "none", or "stdin" as the name of the mcf in the invocation, without redirecting the standard input from another source. While not essential, "-", "none", or "stdout" will generally be specified as the output file, so that the measurements and descriptive text will appear on the standard output and can be read. In addition, one will most likely want to employ either the -s, -v, or one of the -g(e) options in the interactive mode, either to generate descriptions and diagnostic information, or to view the data as it is measured.
In the interactive mode, the standard input is used as the source of the commands, and merps behaves differently in a number of ways. Firstly, merps prompts the user for input by printing ": " on the standard output at the end of each command. Secondly, the help command is functional, and prints a summary of the data and parameter commands for merps (E1). Thirdly, interrupts, normally fatal, are caught and return the user to the command level. Finally, the occurrence of certain errors simply aborts the command execution and returns the user to the command level rather than terminating merps (e.g. the inability to open a file).