Table of Contents

Name

merp_manual- merp User’s Manual (ERP manuals)

Description

merp - Measure

Event-Related Potentials

merp is a program which quantifies various event-related potential (ERP) signal parameters. It uses an input command file termed a measurement command file (mcf) to specify the measurements to be made and the data files to be measured. The order of the measurements that are output is determined by the sequence of commands in the mcf, and can thus be tailored to output measures in the order required for any subsequent statistical analyses.

merp normally includes sufficient descriptive information regarding the type of measure and the source of the data that of the validity of the mcf can be easily verified. This descriptive information can be suppressed when the actual measures alone are being collected for subsequent analyses. In addition, to further simplify the interpretation of the measures, the data and the measures can be displayed on the color monitor. This is especially useful when certain types of measure errors arise, such as no negative peak during a search for a negative peak. The display option can be set to graph only those data which engender such measure errors, or all data.

Using Merp

Getting Started

The prototypical invocation of merp is:


merp [options]opt mcf1 mcf2 ...

where the mcf1, mcf2, ... represents the names of the measurement command files. If no mcfs are present on the command line, the measurement commands will be taken from the keyboard on a line by line basis; this is useful for interactive viewing and measuring of data. After determining the options specified on the command line, merp sequentially processes each mcf in turn. Any desired options are introduced with flag argument(s) and precede the mcfs (if present) in the command line. The currently avaliable options include:

-d

Don’t include the measurement command or the data descriptors in the output.

-lv lobe_points

Filter the data by forming a running average of 2 * (lobe_points) + 1 points centered on the output data point, where lobe_points is a decimal number. Note that the actual time period over which the averaging takes place is dependent upon the sampling rate, and must be calculated by hand. This procedure implements a non-causal filter with no phase shift at any frequencies. If one feels the transfer function in the frequency domain is important, it is:


         N        2  nf
    1 +     2cos(-------)
        n=1        fs
    ---------------------
            2N + 1

where N is lobe_points, fs is the sampling rate in Hz, and f is the frequency of interest.

-filter filter_type cutoff [cutoff]

Filter data with lowpass, hightpass, or bandpass filter. filter_type must be one of lp (lowpass), hp (highpass), or bp (bandpass). cutoff is the cutoff frequency. For bandpass filter, both low and high cutoff frequencies must be specified.

-ga -+desired_cal

Display all data being measured on the color monitor, with a calibration marker of desired_cal microVolts. This effectively scales the data, since the size of the calibration mark is always one-eighth of the vertical screen length. If desired_cal is preceded by a minus sign, negative is plotted "up", else positive will be "up".

-ge -+desired_cal

This is similar to the -ga option above, except only those measurement commands that cannot be fulfilled cause a display of the offending data and command.

-p latfile ampfile

When using the pkla function for simultaneously calculating peak latency and peak amplitude, print the latency measures to the file latfile and print the amplitude measures to the file amp_file as well as to standard output. Note that the pkla function is unique among the measurement functions as it provides a mechanism for manual override of the default peak measurement. Instructions on the graphic screen explain how to use arrow keys to move a cursor along the waveform for manually specifying a peak latency.

Note that any flags which require arguments must be entered in the order shown. For example, to start merp where one desires a display of every measurement on data filtered using a 7 point running average, one might type:


merp -lv 3 -ga -5 np100300.mcf

assuming np100300.mcf is a measurement command file and that one wishes the data displayed on the mx graphics device. Note also that since the simple invocation:


merp

can be used to invoke merp for interactive measurement of data, one must type "help" on a line by itself in order to induce merp to print a summary of the options and the commands. It is also possible to get this summary by invoking merp with an invalid option, for instance:
merp -q

Running merp

Actually running merp is not difficult; the work is in the creation of the measurement command files. merp can, however, be used interactively both in terms of displaying the data being measured and entering measurement commands.

If one has invoked merp with either of the graphing options (-ga or -ge), merp will pause after each plot. One can continue by typing a return, and measurement will continue. In the case that a command has either a "wild" channel specification or a "wild" file specification (see below), merp will pause awaiting a carriage return after each particular measurement is made.

If one wishes to interactively measure data using merp, simply invoke merp without any mcfs in the command line. merp will interpret this to mean that measurement commands should be taken from the keyboard. As each measurement command is entered and completed with a carraige return, merp will perform the indicated function and then return for more input. A control z will end input from the keyboard, and merp will terminate.

Note that it is possible to use merp by invoking it without specifying any mcfs on the command line, but redirecting the standard input thus:


merp <mcf

where mcf is a measurement command file. This is a legal construction and will function properly; difficulty arises only when one wishes to graph the data by employing either the -ga or -ge options. In this case, after each command is executed and then plotted, merp will use the next line of the input file as input, interpreting it to mean that measurement and plotting should continue. Hence, one should be wary of redirecting the standard input of the merp program.

Saving the Measures

Normally the measures are output to the standard output and thus appear on the monitor unless the standard output has been redirected. When one first creates a measurement command file, it is wise to allow the descriptors to be printed along with the measures to ensure that merp is measuring the data that one intended to measure, and in the order desired. Once a mcf has been verified as containing the proper commands, the output measures should be saved in a file for future processing using the -d (no descriptors) flag. Here is an example using a mcf named "negpk501.mcf" :


merp -d negpk501.mcf > negpk501

In this case the measures will be placed in a file named "negpk50150", without any descriptors.

Errors During Measurement

There are two major classes of errors that can occur during the execution of merp. The first class consists of "soft" or "measurement" errors; these arise when a requested measurement cannot be completed due to the nature of the data. For example, asking for a negative peak when no negative peaks are present in the specified latency range will produce a measurement or soft error. Soft or measurement errors are those which are displayed when merp is invoked with the -ge (graph errors) option; these errors always output a measure even if it is meaningless. This approach has been adopted because in some cases the measures are not meaningless. For instance, while there may not be a negative peak present in a certain latency window, merp will output the least positive value in that window. Hence, under certain conditions where one is certain that the appropriate value is being produced, these soft errors can be ignored.

The other class of errors - hard errors - cover all other errors which prevent merp from completing a measurement. These include syntax or format errors, errors in acquiring the proper data (i.e. the file does not exist, the specified bin is out of range), or invalid parameters. All hard errors will destroy the sequence of measures in the output file and should thus be considered fatal, although few actually cause merp to terminate immediately.

In all cases merp prints out what is meant to be a self-explanatory message followed by the line number and name of the measurement command file in which the error occurred. These printed error messages always appear on the monitor, even if the standard output has been redirected and measurements are being saved in a file. This should alert the user that something is amiss and requires attention even if merp is started asynchronously with its standard output redirected. If the output has been redirected, the error messages will not appear in the file of measures, but only on the terminal. In those infrequent cases where one can ignore soft errors, this will prevent the file containing the measures to be cluttered with error messages.

Measurement Commands and Measurement Command Files

Measurement command files (mcfs) are used to direct merp to perform particular measurements on specified data. They are composed of sequences of commands (and parameters, if necessary) with one command per line of the file, and are created using an editor. There are three basic classes of commands: measurement commands (functions), parameter definition commands, and miscellaneous commands. The sequence of functions in the command file determines the sequence of measures output by merp.

Function Command Lines

The form of a standard function command line which will produce at least one output measure is as follows:


func bin chan file lowlat hilat [ext1] [ext2] [ext3]

where

func

is the name of the specific type of measurement function (meana, rms, pkl, etc. listed below),

bin

is the bin number in the file,

chan

is the channel number (starting at 0) or $ if "wild" channels have been defined (see below),

file

is the filename of the data file (this must have been defined previously in a "file" declaration; see below) or * if all files are to be measured

lowlat

is the lower latency of the window over which the measurement is to be made,

hilat

is the upper latency of the window (note both of these latencies are referred to stimulus onset),

ext1 ext2

are extra arguments which may be required for particular measurement functions.

Note that all of the arguments (parameters) on a function line are numeric integers, except "func" and "file", which are ASCII names. The optional "ext1" and "ext2" arguments can be ASCII or numeric, depending on the particular function.

Wild Channels and Wild Files

Quite often one wishes to make the same measurement on a number of subjects or a number of channels. As alluded to above, there is a provision in merp that allows this to be accomplished without repeating the function command line with different filenames. In the case of files, one simply places an asterisk (*) in place of a specific filename. When that function command line is executed, each of the files defined previously in the mcf will be measured in the order in which they were defined.

A similar subterfuge is possible with the "chan" argument in a function command. In this case one must define which channels are to be measured and in what order. This is accomplished using the "channels" command (see Parameter Definition Commands below), which must precede the use of a wildcard chan selector in a function command. To denote a wildcard chan selector, one places a $ (dollar sign) in the chan argument position of the function command line.

In a function command which contains both wild file and wild chan specifications, all the files are measured before stepping to the next channel. Currently there is no way to override this ordering except by explicitly typing out the filenames and using a wild chan selector. Although this involves replicating the function command line a number of times, it is still easier than not being able to employ the wild channels. If one could not employ the wild chan selector, it would be necessary to replicate the function command the product of the number of files times the number of channels times!

Measurement Functions

In an actual mcf, "func" would be replaced with the mnemonic for one of the available functions. Currently there are 19 functions which can be used to quantify various aspects of the ERPs. These are:

pkl

Peak latency. This function requires one extra argument which can be either the single character "+" or "-", indicating whether one desires the latency of a positive peak or a negative peak, respectively. This function can engender a soft error: pk - no such peak polarity. The units of the measurement are milliseconds referred to stimulus onset.

pka

Peak amplitude. This function uses some of the same internal code as pkl above; hence it employs the same extra polarity argument and can also result in a soft error. The output is in microvolts.

lpkl

Local peak latency. This function finds the largest local peak, 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 N previous points and the mean of the N subsequent points, where N is set by the user. This function requires two extra arguments. The first can be either the single character "+" or "-", indicating whether one desires the latency of a positive peak or a negative peak, respectively. The second argument indicates how many points should be averaged together for peak determination (i.e. the number N). This function will produce a soft error if no local peak is found, in which case the peak is determined in the same way as the pkl function. The units of the measurement are milliseconds referred to stimulus onset.

lpka

Local peak amplitude. This function uses some of the same internal code as lpkl above; hence it employs the same extra arguments and can also result in a soft error. The output is in microvolts.

mnarndpk

Mean amplitude around peak. Finds a peak as in pkl and pka functions. Then finds the mean amplitude in a window surrounding the peak. Requires 2 extra arguments: a ’+’ or ’-’ for the polarity of the peak, and the size of the window in milliseconds.

mnarndpkc

Mean amplitude around peak of specific channel. This is similar to mnarndpk. Requires 3 extra arguments: a ’+’ or ’-’ for the polarity of the peak, the size of a window (in milliseconds) centered at the peak, and the channel to find the peak in. The window determined by the peak for the channel specified by the third extra argument is then used to determine the mean amplitude for the channel being measured. For example, a measurement command file containing these commands:

    file test.avg
    channels 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
    mnarndpkc 1 $ * 100 400 - 300 3

would first find a negative peak for channel 3 between 100 and 400 milliseconds, then it would measure the mean amplitude for the 300 millisecond window centered at this peak for all the channels. If the beginning of the requested window would start before the beginning of the epoch, the beginning of the window is set to 0. If the end of the requested window would occur after the end of the epoch, the end of the window is set to the end of the epoch.

meana

Mean amplitude. Meana calculates the mean amplitude over the latency range. It does not employ extra arguments, and no soft errors are possible. The output units are microvolts.

ppa

Peak to Peak Amplitude. Ppa calculates the maximum minus the minimum voltage over the latency window. No extra arguments are needed and no soft errors can be produced. The units are microvolts

rms

Root Mean Square. This is a measure of signal power over the latency window. It is the square root of the mean sum of squares over the interval. No extra arguments are required and no soft errors are possible. The units are microvolts.

fpl

Fractional Peak Latency. This function requires two additional arguments: the polarity of the peak ("+" or "-") and the fraction of the peak amplitude desired in that order. The fraction is entered as as a floating point constant between 0.0 and 1.0 (e.g. .25). The routine first finds the appropriate peak and then moves toward smaller latency values until the absolute value of the data at the current latency falls below the fraction times the absolute value of the peak. Fpl can result in a soft error and the units are in milliseconds.

lfpl

Local fractional peak latency. Like fpl, only works on a local peak. Requires an additional argument: N - the number of points to be averaged together in local peak determination (this is analogous to the N used in the lpkl function).

fpa

Fractional Peak Amplitude. This is similar to fpl above, except that the fractional amplitude of the peak is returned. Thus, two extra arguments are required, a soft error is possible, but the units are in microvolts.

fal

Fractional Area Latency. Fal requires two additional arguments. The first is one of "+", "-", or "+-", indicating that only positive area, negative area, or both should be used in the algorithm. The second extra argument is a decimal fraction as in fpl above. The fal routine first determines the total area of the specified polarity in the latency window; it then, beginning at the lowlat latency and moving towards longer latencies, accumulates area of the appropriate polarity until its absolute value exceeds the fraction times the absolute value of the total area. A soft error is possible - no such area polarity. The units are in milliseconds.

faa

Fractional Area Amplitude. This function employs the same routine as fal above and hence uses the same arguments and can produce the same soft error. The output, however, is the fraction times the total accumulated area (not the absolute value) and has units of microvolts*milliseconds.

npppa

Negative then Positive Peak to Peak Amplitude. This function measures a peak to peak amplitude by first finding the largest negative peak in the measurement window and then determining the largest positive peak subsequent to the negative peak. The amplitude difference is the value returned. No errors are possible, and no additional arguments are required.

pnppa

Positive then Negative Peak to Peak Amplitude. This function is similar to the npppa function above, except that a positive peak is first found, followed by a negative peak.

lnpppa

Local Negative then Positive Peak to Peak Amplitude. This function is a hybrid of the npppa and the lpka functions, using local maxima and minima instead of absolute maxima and minima in the latency window. If no local maximum and/or minimum can be found, the absolute maximum or minimum is used, and a soft error returned.

lpnppa

Local Positive then Negative Peak to Peak Amplitude. This is similar to lnpppa as npppa is to lpnppa.

abblat

Above or Below Baseline LATency. This function is one method of attempting to estimate the onset latency of a monophasic waveform. Two additional arguments are required - a polarity (’+’ or ’-’) and a numerical "duration". It works like this: The waveform is searched, starting at the beginning of the measurement window for the first point of the proper polarity. This latency is remembered. Subsequent points are tested for their polarity and if "duration" milliseconds of such points are found, the latency of the start of that stretch is returned. If, at any time in the search, a point or points or the wrong polarity are encountered, the procedure begins again at that point. If no stretch of data are above (polarity +) or below (polarity -) for "duration" milliseconds, it is considered an error and a message to that effect is printed.

bonslat

Baseline ONSet LATency. This function is another way of attempting to determine the onset latency of a monophasic waveform. It requires two additional arguments - a polarity and a decimal numeric factor. It works like this: The baseline period is searched for either the largest positive (polarity = ’+’ ) or largest negative (polarity = ’-’) contiguous area. Then, a search instituted in the measurement window for the first contiguous area of the appropriate polarity which exceeds "factor" times the baseline area. The latency of the first point of this area (in the measurement window) is returned. A number of errors are possible - no area of the appropriate polarity in the baseline period, no area of the appropriate polarity in the measurement window, or no area exceeding "factor" time that in the baseline period was found.

pxonslat

Positive eXtrapolated ONset SLATency. Yet another way to determine the onset latency of a peak. It requires two additional arguments - both being a fraction of the positive peak in the measurement window. The idea is to specify two points on the rising phase of a peak, and then extrapolate a line passing through these two points to the baseline and measure the latency of the intersection. Hence, the first fraction must be less than the second, both must be positive and less than 1.0. A number of errors are possible; no such peak polarity, first fraction not less than the second, etc.

nxonslat

Negative eXtrapolated ONset LATency. Same as pxonslat, except for negative peaks.

These functions are not meant to cover all types of measurements one might wish to make on ERP data. Instead, merp has been written to allow easy additions of new functions. As these are added, this document will be updated to reflect the current state, as will the manual pages.

Parameter Definition Commands

There are three commands which are used to set parameters used in the measurement of data. Only one of these is required in a mcf; this is the file definition command. File definitions should be the first statements in a mcf, and the ordinal position of the statements determines the order in which files will be processed when a "wildcard" indicator (*) is used in the file position of a function line. The file definition statement has this form:

file file_name

where filename is the name of the data file to be measured. A file definition containing the name of a file must precede any instance of that file name in a function command, or a "file undefined" error message will result. It is useful employ either a relative name (..\..\s02.na or \exp\pilot\ppi\data\s03.erp) or a full pathname so that the measurement command file can be used from different directories.

There are two other parameter definition commands. One is used to alter the interval which is used to calculate the baseline voltage which is subtracted from every point in the data prior to measurement. The format of this command is:

baseline start stop

where start and stop are decimal integers which denote the beginning and ending latencies of the portion of data which are to be averaged together to form the baseline voltage. The start and stop latencies are relative to stimulus onset, so if one wanted to use 50 msec prioir to stimulus onset as the baseline interval, one would type
baseline -50 0

Whenever a baseline command appears in a measurement command file, those latency values are used for every subsequent measurement made until another baseline command is encountered. Note that if no baseline command appears in a mcf, the entire prestimulus interval is used by default as the baseline interval. In most cases, this is the desired choice and no baseline commands will be required.

The third type of parameter definition command is the "channels" command. This is necessary only when one desires to "wild" channel selections in function lines. The format of the channels command is:

channels i, j, k, ...

where i, j, and k are decimal integers between 0 (zero) and the number of channels in the data minus one. Whenever a wildcard channel specifier or selector ($) is encountered in the chan position of a function line, all the channels specified in the last channels command will be measured in the order they appeared in the channels command. Remember that if a wildcard specification is also used in the file position of the function command (*), all the files will be measured at each channel before the next channel is selected. It is an error for a wild channel selector ($) to appear without a channels command preceding it somewhere in the file.

Miscellaneous Commands

The only currently implemented miscellaneous command is the "help" command. It is used during interactive use of merp, and prints a summary of the invocation options, function line summary, and parameter definition command formats. Its use in a pre-edited mcf is not recommended.

an Example

The best way to learn to use merp is to study an example. Consider a data set consisting of 8 subjects whose second, fifth, and eighth channels are Fz, Cz, and Pz, respectively. Let’s assume we wish to measure bins 12 and 18 between 300 and 600 msec post-stimulus for the amplitude of the largest positivity (peak) at these scalp sites. The following measurement command file will do the job:


    file ..\data\s1.na
    file ..\data\s2.na
    file ..\data\s3.na
    file ..\data\s4.na
    file ..\data\s5.na
    file ..\data\s6.na
    file ..\data\s7.na
    file ..\data\s8.na
    channels 1 4 7
    pka 12 $ * 300 600 +
    pka 18 $ * 300 600 +

Note that the baseline interval will default to the total presampling period of the averaged data. The order of the measures that will be output will be:


bin 12, chan 1, sub s1.na; .... bin 12, chan 1, sub s8.na
bin 12, chan 4, sub s1.na; .... bin 12, chan 4, sub s8.na
bin 12, chan 7, sub s1.na; .... bin 12, chan 7, sub s8.na
bin 18, chan 1, sub s1.na; .... bin 18, chan 1, sub s8.na
bin 18, chan 4, sub s1.na; .... bin 18, chan 4, sub s8.na
bin 18, chan 7, sub s1.na; .... bin 18, chan 7, sub s8.na

To verify that this is indeed the order of measures, one might invoke merp thus:

merp P3attin.mcf

assuming P3attin.mcf is the name of the file containing the commands listed above. Since the -d (no descriptors) flag was not employed, the measures will be output with information regarding the subject, experiment, condition, and bin as well as a replica of the command line, the measured value, and its units (microvolts in this case). If one wished to view the process, one might invoke merp thus:


merp -ga -5 P3attin.mcf

When finally convinced that the appropriate data are being measured, one can delete the descriptors and save the measures in a file called P3attin.dnd thus:


merp -d P3attin.mcf >P3attin.dnd

Good Luck!


Table of Contents