|
|
Docs: merps
Merps is a program which measures signal parameters of event-related potentials (ERPs) in standard ERPSS data files. It uses an input command file, termed a measurement command file (mcf), to specify which measurements to make and how to make them, and an output file to hold the resulting values. It is also possible to use merps (E1) in an interactive mode, wherein commands are taken from the standard input, and/or the measurements are printed on the standard output. One can optionally specify which data files to measure during the invocation, thus allowing the same mcf to be employed for measuring multiple data sets without having to edit the mcf between each set of measurements.
The user specifies the order in which the measurements are made and placed in the output file, and can optionally specify the number of columns for the output; hence merps is usually sufficient to assemble data for any subsequent statistical analyses. Descriptive information about the measure or the data being measured can be printed to help in verifying the validity of the mcf. In addition, to assist in the interpretation of the measurements, the data being measured can be displayed on a graphics device, if desired. This is especially useful when certain types of measurement errors arise, such as the failure of a peak finding algorithm to locate a negative peak of the proper polarity. One can have merps plot either data that engender these measurement errors, or all data. Finally, it is possible to easily add additional measurement algorithms to merps, avoiding the necessity of having to write special purpose programs in most cases.
Here's the generic invocation of merps:
The second argument, outfile, specifies the file in which the measurements will be placed. Note that merps will not write over an existing file, but rather will complain and exit. If the outfile is any of "-", "none", or "stdout", measurements will be printed on the standard output, along with any descriptive information, regardless of the source of the commands. Thus, to use merps in a fully interactive manner, one should invoke merps with "-" as both the commandfile and outfile. Note that the output file (if not the standard output) is removed if a fatal error occurs during execution or if merps (E1) is killed by an interrupt (delete).
Options for merps are selected with additional arguments on the invocation line that begin with "-". An option may have none, one, or many arguments of its own. Any such arguments for an option immediately follow the option and are associated with that option until another argument beginning with a "-" is encountered. Here are the options that are currently implemented:
-f datafile1 [datafile2 ...]
The -f option is used to specify ERP data files on the command line, and is handy for making the same measurements on different data sets, especially in a shell script. One or more standard ERPSS data file names should follow the -f. This option emulates multiple file commands (see below) and causes merps to initially open the specified files and assign them numbers (starting with zero) that are used by commands in the mcf. Note that any file or clearfiles commands in the mcf will also be executed, so the use of this option should be coordinated with the contents of the mcf. Note that the file names cannot begin with "-", as this character is recognized by merps as introducing additional options.
-c commandfile(s...)
The -c option allows one to use multiple command files to perform measurements. merps first performs the measurements in the required command file commandfile, and then sequentially opens each commandfile specified via this option and performs the commands contained therein. Note that any exit or quit commands in any of the command files cause immediate termination of merps at that point. Again, the command files cannot start with "-".
-n ncols
One can instruct merps to output ncols measurements per line of the output file (rather than the default of one per line) by using this option. The number ncols should be larger than 1 and not so large that the line length of the output file becomes unmanageable. This is particularly useful for subsequent analyses that employ matrix or columnar manipulations on data.
-g plot_device +/- descaluV
-ge plot_device +/- descaluV
-gw plot_device +/- descaluV win_starttime win_stoptime
These options cause merps (E1) to display the ERP data on plot_device in a manner such that descaluV is one-quarter of the total vertical space alloted for plotting the data (as well as the size of a calibration marker drawn on the plot). If descaluV is negative, data are plotted so that increasingly negative values are drawn upwards on the plot. The value of the measurement, its units, the measurement function, data parameters and descriptions are also displayed on the plot. The -ge form causes only data that could not be successfully measured to be drawn, while the -g form plots all data as they are measured. The -gw form allows the user to override the default (the entire averaged epoch) and specify their own window start time and stop time (win_starttime and win_stoptime, respectively), which is handy when one wishes to focus on a particular timeframe of interest. When either of these graphic display options are in effect, merps pauses at the end of each plot waiting for a newline from the standard input, regardless of the source of the measurement commands.
-s
-v
Normally merps outputs only the actual measurement values, as this is most appropriate for subsequent processing of the data by other programs. By employing one of these options, additional information about the data being measured and the measurement itself can be printed. The -s option causes merps to append the units of the measurement (e.g. uVolts), the short name of the measurement algorithm, and the file, bin, processing function, and channel used for the measurement to the value. The -v provides more extensive information, including the levels of the factors used to generate the data parameters ( see below), the long name of the measurement algorithm, and the various descriptions of the data from the data headers. Neither of these options function well when more than one measurement per line is being printed, as directed by the -n option.
The operation of merps is controlled by various commands that are placed in one or more measurement command files, or mcfs. These are standard ASCII files that can be generated using any text editor. The commands for merps, whether in an mcf or supplied interactively, occur one per line, along with any associated arguments. Lines in the command file that begin with "#" are considered comments, and are ignored, as are any blank lines in the file. The first string on any line is interpreted as the command name, whose recognition is based on matching an initial substring. For example, the channels command would be invoked by any word starting with "chan". That is, chan, channels, chans, and chandelier would all be recognized as a valid channels command. The unique substrings that are used to match each command are listed in the description of each command. The case of the command is irrelevant; the command string is converted to lower case before analysis.
Since one must specify the data that will be measured, the order in which to make the measurements, and certain other parameters as well as the type of measurement(s) to make, the command set is divided into measurement parameter commands and measurement commands. The measurement parameter commands set various parameters that control the data that are measured and the order of measurements, while the measurement commands actually cause measurements to be made and the values placed in the output file.
Note that one can specify as many measurements in an mcf as desired, by simply placing them in the mcf. The commands are executed in the order they are encountered in the mcf, and the parameters from measurement parameter commands are retained until the specific command is again encountered in the mcf.
Some of the measurement parameter commands must be present before any measurement commands appear in the mcf. These mandatory parameter commands and their arguments are:
file data_file
The file command opens the ERPSS data file data_file and adds it to the list of data files. The order in which the file commands appear specifies the order in which they will be measured. Recognized by the substring "fi".
bins B1 [B2 ...]
Indicates that bin(s) numbered B1, B2, ... are to be measured, in that order. Recognized by the substring "bin".
channels C1 [C2 ...]
As with the bins command, the channels command specifies which channel(s) will be measured, and in what order. Recognized by the substring "chan".
order (chans) (bins) (files) [procfuncs]
This command determines the order in which measurements are made. The arguments chans, bins, and files must occur as arguments to the order command, but the procfuncs argument is optional. The order of appearance of these words as arguments determines the order in which. The first argument is cycled through most slowly, the second next fastest, etc, and the last fastest. This syntax is compatible with the anovae and ranova programs, where the first factor moves most slowly, and the last factor fastest. Note that for repeated measures designs, the factor that designates subjects (usually files) should be last. Unless procfuncs is present in the order command and a procfuncs optional parameter command has been encountered, processing function 0 (the first) will be measured. Recognized by the substring "order".
window lo_msec hi_msec
All measurement commands require a latency range over which the algorithm is applied. This latency range is specified by the window command, where the beginning and ending latencies (inclusive), in milliseconds with respect to stimulus onset are set by lo_msec and hi_msec. The search window remains in effect until another window command is encountered. Recognized by the substring "wi".
Note that at least one file, channel, and bin, as well as the search window must be specified before any measurements commands are encountered in an mcf.
In addition to the mandatory parameter commands, one can utilize certain optional commands to modify the operation of merps:
clearfiles
This command does not require any arguments and closes all open files in preparation for subsequent file commands. It is necessary since the files and their order is determined by multiple commands on separate lines with each additional file command simply adding to whatever is already open. Recognized by the substring "clearf".
baseline lo_msec hi_msec
Most measurement algorithms are sensitive to the manner in which the zero-voltage value (baseline) is calculated. Unless a baseline command is encountered in an mcf, the entire pre-stimulus period is averaged to calculate the voltage that is subtracted from all data points. Like the window command, the limits are inclusive, and, once changed, the new baseline window remains in effect until another baseline command is encountered. Recognized by the substring "base".
procfuncs P1 [P2 ...]
If one wishes to measure a processing function other than 0, it can be specified using this command. Operation is similar to the bins and chans commands, above. Recognized by the substring "procf" or "pf".
help
This command, of use mainly when merps is operating in interactive mode, prints a short summary of the commands and their usage. Recognized by the substrings "h" or "?".
exit
This command is mainly of use when merps is used in interactive mode, and causes merps to close all open files and exit. Recognized by the substrings "exit", "quit", "e", and "q".
A variety of algorithms that calculate various signal parameters are available in merps, and additional ones are easily added. These mesaurement commands do not have aliases, and the entire name must be typed in full. The case, however, is immaterial. In all cases, merps checks the measurement window, baseline window, etc against the data, possibly encountering a fatal error. Remaining errors generated by the measurement commands and their causes are detailed in the description of each specific algorithm.
Errors that occur during the execution of a measurement command are divided into two categories: hard errors, and soft errors. Hard errors occur when an insurmountable error arises during the execution of a measurement command. If merps is not operating in interactive mode, hard errors are fatal and cause termination of merps, with the attendant removal of the (incomplete) output file. In contrast, soft errors do not cause merps to terminate. In most cases, the measurement algorithm which encounters a soft error attempts to deliver a reasonable datum, although this is not possible in all cases. For both hard and soft errors, a message is printed on the standard error that is intended to help diagnose the problem. For more information on errors, see the section so entitled below.
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).