Table of Contents

Name

merp - measure ERPs (event-related potentials)

Synopsis

merp [options] mcf [mcf2 ... ]
merp [options] -

Description

merp is used to quantify various signal parameters of averaged EEG data. The data to be measured and the measurements to be taken are specified by commands contained in the measurement command file mcf. It is possible to graph all the data as they are measured (see the -ga option), or graph only those data which cannot be measured according to the command specifications (see the -ge option).

merp can also be run interactively by specifying ‘-’ instead of the name of a command file. In this case, commands are read from the standard input (typically the keyboard).

Options

-d
Suppress all descriptive information in the output, output only the measurement values. This is useful when the measures alone are being collected for subsequent analyses.

-lv N
Filter the data by forming a running average of (2*N)+1 points centered on the output data point, where N is a positive integer. Note that the actual time period over which the averaging takes place is dependent upon the sampling rate. This procedure implements a non-causal filter with no phase shift at any frequencies.

-filter type cutoff [cutoff]
Filter the data with a lowpass, highpass, or bandpass filter. type is one of lp (lowpass), hp (highpass), or bp (bandpass), and cutoff is the cutoff frequency, entered as a positive integer. Both low and high cutoff frequencies must be specified for the bandpass filter.

-ga cal
Display the data being measured, setting the scale with a calibration marker of cal microvolts (a good value to start with is 5). If cal is preceded by a minus sign, negative is plotted "up", else positive is plotted "up".

-ge cal
This is similar to the -ga option, 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 ampfile as well as to the standard output.

Measurement Command File

The measurement command file is a text file containing sequences of commands, with one command per line. The commands fall logically into one of two groups: commands that specify the data to be measured, and commands that describe the measurements to be taken. Commands that specify the data usually precede the commands that describe the measurements. Lines beginning with the ‘#’ character are considered comment lines and can appear anywhere in the file.

The commands that specify the data are:

file filename
This command is required, and specifies filename as the name of a data file to be measured. The ordinal position of the file commands determines the order in which files will be processed when a measurement command contains the ‘*’ wildcard in place of a file name. A file command must precede any use of filename or ‘*’ wildcard by a measurement command. If a measurement command uses wildcards to specify both files and channels, all the files will be measured at each channel before the next channel is selected.

channels i j k ...
This command is required only when the ‘$’ wildcard is used in place of the channel number in a measurement command. In such cases, it specifies the channels to be measured, where i, j, and k are decimal integers between 0 and the number of channels in the data minus one. A channels command must precede any use of the ‘$’ wildcard by a measurement command. If a measurement command uses wildcards to specify both files and channels, all the files will be measured at each channel before the next channel is selected.

baseline start stop
This command is used to alter the interval used to calculate the baseline voltage which is subtracted from every point in the data prior to measurement. start and stop are decimal integers which denote the beginning and ending latencies (in ms) of the portion of data which are to be averaged together to form the baseline voltage (note: prior to 2008-09-10 the data point corresponding to the stop latency was included in the baseline average; after 2008-09-10 it is excluded). They are relative to stimulus onset, so if one wanted to use the 50 ms prior to stimulus onset as the baseline interval, one would type "baseline -50 0". Whenever a baseline command appears in an mcf, that baseline is used for every subsequent measurement made until another baseline command is encountered. If no baseline command appears in an 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.

nobaseline
This command specifies to not calculate or subtract any baseline voltage from the data prior to measurement.

The commands that describe the measurements to be taken use the format

func bin chan file lowlat hilat [ ext1 ext2 ext3 ]

where func is one of the measurement functions listed below; bin is the bin number of interest; chan is the channel number of interest (starting at 0) or the wildcard character ‘$’ (see the channels command above); file is the name of the data file to be measured or the wildcard character ‘*’ (see the file command above); lowlat and hilat are the starting and ending latencies (in milliseconds from stimulus onset) within which to perform the measurement; and ext1, ext2, ext3 are up to three extra arguments needed by some measurement functions as described below. Unless otherwise stated, resulting amplitudes are measured in microvolts and resulting latencies are measured in milliseconds from stimulus onset.

pkl polarity
Peak latency. Requires the extra argument polarity, either ‘+’ or ‘-’, to indicate to measure a positive peak or negative peak, respectively. This function finds the latency of the most positive/negative point in the measurement window.

The soft error "no such peak polarity" is generated if the peak is of a different sign than the requested polarity; in this case the measure is still valid. The soft error "bad sign arg" is generated if something other than ‘+’ or ‘-’ was entered for polarity; in this case the measure is invalid.

centroid polarity
Centroid latency. Requires the extra argument polarity, either ‘+’ or ‘-’, to indicate to measure the area under a "positive peak" or "negative peak", respectively. This function finds the latency of the center of "mass" of the area under the waveform in the measurement window. The area is bounded above by the waveform, to the sides by the starting and ending latencies, and below by the most negative (or most positive when using ‘-’ polarity) point in the measurement window (note the lower bound is NOT the baseline). This measure may be useful when one needs sensitivity to changes in waveform morphology, such as skew. The algorithm was taken from Dien, J., Spencer, K.M., and Donchin, E. "Parsing the late positive complex: Mental chronometry and the ERP components that inhabit the neighborhood of the P300." Psychophysiology, 2004, 41:665-678.

The soft error "no such peak polarity" is generated if the peak is of a different sign than the requested polarity; in this case the measure is still valid. The soft error "bad sign arg" is generated if something other than ‘+’ or ‘-’ was entered for polarity; in this case the measure is invalid.

pka polarity
Peak amplitude. Requires the extra argument polarity, either ‘+’ or ‘-’, to indicate to measure a positive peak or negative peak, respectively. This function finds the amplitude of the most positive/negative point in the measurement window.

The soft error "no such peak polarity" is generated if the peak is of a different sign than the requested polarity; in this case the measure is still valid. The soft error "bad sign arg" is generated if something other than ‘+’ or ‘-’ was entered for polarity; in this case the measure is invalid.

pkla polarity
Peak latency and amplitude. Requires the extra argument polarity, either ‘+’ or ‘-’, to indicate to measure a positive or negative peak, respectively. This function finds the latency and amplitude of the most positive/negative point in the measurement window (i.e. it is possible that a positive peak have a negative amplitude). When merp is invoked with the -ga option, manual selection of the latency and amplitude is possible by using the right and left arrow keys to select an alternate point along the waveform.

The soft error "no such peak polarity" is generated if the peak is of a different sign than the requested polarity; in this case the measure is still valid. The soft error "bad sign arg" is generated if something other than ‘+’ or ‘-’ was entered for polarity; in this case the measure is invalid.

fpl polarity fraction
Fractional peak latency. Requires the extra arguments polarity, either ‘+’ or ‘-’; and fraction, the desired fraction of the peak amplitude, entered as a number between 0.0 and 1.0 (e.g. 0.25). This function 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.

The soft error "no such peak polarity" is generated if the peak is of a different sign than the requested polarity; in this case the measure is still valid. The soft error "bad sign arg" is generated if something other than ‘+’ or ‘-’ was entered for polarity; in this case the measure is invalid.

NOTE: on May 8, 2004, this function was changed so that the search for the fractional value continues back to the start of the epoch. Previously, the search (seemingly incorrectly) stopped at the bounds of the measurement window (lowlat), and if the fractional value was not found within the measurement window, lowlat was returned (without error) as the fractional latency.

fplf polarity fraction
Fractional peak latency, forward. Requires the extra arguments polarity, either ‘+’ or ‘-’; and fraction, the desired fraction of the peak amplitude, entered as a number between 0.0 and 1.0 (e.g. 0.25). This function first finds the appropriate peak and then moves toward LARGER latency values until the absolute value of the data at the current latency falls below the fraction times the absolute value of the peak.

The soft error "no such peak polarity" is generated if the peak is of a different sign than the requested polarity; in this case the measure is still valid. The soft error "bad sign arg" is generated if something other than ‘+’ or ‘-’ was entered for polarity; in this case the measure is invalid.

fpa polarity fraction
Fractional peak amplitude. Requires the extra arguments polarity, either ‘+’ or ‘-’; and fraction, the desired fraction of the peak amplitude, entered as a number between 0.0 and 1.0 (e.g. 0.25). This function is similar to the fpl function, but returns the amplitude of the waveform at the latency found by fpl.

The soft error "no such peak polarity" is generated if the peak is of a different sign than the requested polarity; in this case the measure is still valid. The soft error "bad sign arg" is generated if something other than ‘+’ or ‘-’ was entered for polarity; in this case the measure is invalid.

NOTE: on May 8, 2004, this function was changed so it returns the amplitude of the waveform at the latency found by fpl, which may be slightly different than the amplitude calculated by fraction multiplied by the peak amplitude, due to the discrete nature of the sample points. Previously, this function (seemingly inaccurately) returned exactly fraction multiplied by the peak amplitude.

fpaf polarity fraction
Fractional peak amplitude, forward. Requires the extra arguments polarity, either ‘+’ or ‘-’; and fraction, the desired fraction of the peak amplitude, entered as a number between 0.0 and 1.0 (e.g. 0.25). This function is similar to the fplf function, but returns the amplitude of the waveform at the latency found by fplf.

The soft error "no such peak polarity" is generated if the peak is of a different sign than the requested polarity; in this case the measure is still valid. The soft error "bad sign arg" is generated if something other than ‘+’ or ‘-’ was entered for polarity; in this case the measure is invalid.

lpkl polarity N
Local peak latency. Requires the extra arguments polarity, either ‘+’ or ‘-’; and N, the number of points around the peak to average. 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. When merp is invoked with the -ga option, manual selection of the latency and amplitude is possible by using the right and left arrow keys to select an alternate point along the waveform.

The soft error "no local maximum" or "no local minimum" is generated if no local peak is found; in this case the peak is determined in the same way as the pkl function. The soft error "bad sign arg" is generated if something other than ‘+’ or ‘-’ is entered for polarity; in this case the measure is invalid.

lpka polarity N
Local peak amplitude. Requires the extra arguments polarity, either ‘+’ or ‘-’; and N, the number of points around the peak to average. This function is similar to the lpkl function, but returns the amplitude of the peak.

lfpl polarity fraction N
Local fractional peak latency. Requires the extra arguments polarity, either ‘+’ or ‘-’; fraction, the desired fraction of the peak amplitude, entered as a number between 0.0 and 1.0 (e.g. 0.25); and N, the number of points around the peak to average (analagous to the N used in the lpkl function). This function is like the fpl function, but works on a local peak.

The soft error "no local maximum" or "no local minimum" is generated if no local peak is found; in this case the peak is determined in the same way as the fpl function. The soft error "no such peak polarity" is generated if the peak is of a different sign than the requested polarity; in this case the measure is still valid. The soft error "bad sign arg" is generated if something other than ‘+’ or‘-’ is entered for polarity; in this case the measure is invalid.

NOTE: on May 8, 2004, this function was changed so that the search for the fractional value continues back to the start of the epoch. Previously, the search stopped at the bounds of the measurement window (lowlat), and if the fractional value was not found within the measurement window, lowlat was returned (without error) as the fractional latency.

fal polarity fraction
Fractional area latency. Requires the extra arguments polarity, one of ‘+’, ‘-’, or ‘+-’, to indicate that only positive area, negative area, or both should be used in the measurement; and fraction, the desired fraction of the total area, entered as a number between 0.0 and 1.0 (e.g. 0.25). This function first determines the total area of the specified polarity in the measurement window; it then, beginning at the low 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.

The soft error "no such area polarity" is generated if there are no data of the specified polarity within the measurement window; in this case the measure is 0. The soft error "bad sign arg" is generated if something other than ‘+’ or ‘-’ is entered for polarity; in this case the measure is 0.

faa polarity fraction
Fractional area amplitude. Requires the extra arguments polarity, one of ‘+’, ‘-’, or ‘+-’, to indicate that only positive area, negative area, or both should be used in the measurement; and fraction, the desired fraction of the total area, entered as a number between 0.0 and 1.0 (e.g. 0.25). This function is similar to the fal function, except the output is the fraction times the total accumulated area (not the absolute value) and has units of microvolts * milliseconds.

ppa
Peak to peak amplitude. This function calculates the maximum minus the minimum voltage over the measurement window.

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.

The soft error "subsequent largest positive peak is beyond measurement window" is returned if the subsequent positive peak is after hilat; in this case the most positive subsequent value within the measurement window is used as the positive peak.

pnppa
Positive then negative peak to peak amplitude. This function measures a peak to peak amplitude by first finding the largest positive peak in the measurement window and then determining the largest negative peak subsequent to the positive peak. The amplitude difference is the value returned.

The soft error "subsequent largest negative peak is beyond measurement window" is returned if the subsequent negative peak is after hilat; in this case the most negative subsequent value within the measurement window is used as the negative peak.

lnpppa N
Local negative then positive peak to peak amplitude. Requires the extra argument N, the number of points to average. This function is a hybrid of the npppa and lpka functions, using local maxima and minima instead of absolute maxima and minima in the measurement window.

The soft error "no local maximum" or "no local minimum" is generated if no local maximum and/or minimum can be found; in this case the absolute maximum or minimum is used instead.

lpnppa N
Local positive then negative peak to peak amplitude. Requires the extra argument N, the number of points to average. This function is a hybrid of the pnppa and lpka functions, using local maxima and minima instead of absolute maxima and minima in the measurement window.

The soft error "no local maximum" or "no local minimum" is generated if no local maximum and/or minimum can be found; in this case the absolute maximum or minimum is used instead.

abblat polarity duration
Above or below baseline latency. Requires the extra arguments polarity, either ‘+’ or ‘-’; and duration, a positive integer in milliseconds. This function is one method of attempting to estimate the onset latency of a monophasic waveform. 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 of the wrong polarity is encountered, the procedure begins again at that point.

The soft error "bad sign arg" is generated if something other than ‘+’ or‘-’ is entered for polarity; in this case the measure is invalid. The soft error "bad stretch length" is returned if something other than a positive number is entered for duration; in this case the measure is invalid. The soft error "no stretch exceeds x msec" is generated if the search for subsequent points of the proper polarity fails within the measurement window; in this case the measure is invalid.

bonslat polarity factor
Baseline onset latency. Requires the extra arguments polarity, either ‘+’ or ‘-’; and factor, a decimal numeric factor. This function is another way of attempting to determine the onset latency of a monophasic waveform. The baseline period is searched for either the largest positive (polarity = +) or largest negative (polarity = -) contiguous area. Then, a search is 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.

The soft error "bad sign arg" is generated if something other than ‘+’ or‘-’ is entered for polarity; in this case the measure is invalid. The soft error "bad factor" is generated if something other than a positive number is entered for factor; in this case the measure is invalid. The soft error "no stretch exceeds factor*baseline" is generated if the search for the contiguous area fails within the measurement window; in this case the measure is invalid.

pxonslat fraction1 fraction2
Positive extrapolated onset latency. Requires the extra arguments fraction1 and fraction2, numbers between 0.0 and 1.0 that represent fractions of the positive peak in the measurement window. Yet another way to determine the onset latency of a peak. 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, fraction1 must be less than fraction2.

The soft error "no such peak polarity" is generated if the positve peak has a negative amplitude; in this case the measure is still valid. The soft error "reversed latency" is generated if the second point has a latency less than the first point; in this case the measure is invalid. The soft error "poorly shaped peak" is generated if the second point has an amplitude less than the first point; in this case the measure is invalid.

nxonslat fraction1 fraction2
Negative extrapolated onset latency. Requires the extra arguments fraction1 and fraction2, numbers between 0.0 and 1.0 that represent fractions of the negative peak in the measurement window. This function is the same as the pxonslat function, except for negative peaks.

The soft error "no such peak polarity" is generated if the negative peak has a positive amplitude; in this case the measure is still valid. The soft error "reversed latency" is generated if the second point has a latency less than the first point; in this case the measure is invalid. The soft error "poorly shaped peak" is generated if the second point has an amplitude less than the first point; in this case the measure is invalid.

rms
Root mean square. This is a measure of signal power over the measurement window. It is the square root of the mean sum of squares over the interval.

meana
Mean amplitude. This function calculates the mean amplitude over the measurement window.

mnarndpk polarity windowsize
Mean amplitude around peak. Requires the extra arguments polarity, either ‘+’ or ‘-’; and windowsize, the size of the window (in milliseconds) around the peak. This function finds a peak as in the pka function, then finds the mean amplitude in a window surrounding the peak.

The soft error "bad sign arg" is generated if something other than ‘+’ or ‘-’ is entered for polarity; in this case the measure is invalid. The soft error "window goes outside of epoch" is generated if windowsize specifies a window that extends beyond the bounds of the epoch; in this case the measure is invalid.

slope N
Slope. Requires the extra argument N, the number of points to average at lowlat and hilat. This function returns the slope of the line drawn through the points on the waveform at lowlat and at hilat. The positive integer N indicates the number of points to average at lowlat and hilat when determining the amplitude of the waveform at these latencies (1 indicates no averaging). The units are microvolts/second. When merp is invoked with the -ga option, manual display of latencies and amplitudes is possible by using the right and left arrow keys to select various points along the waveform; this is for accurately determining latencies of features in the waveform, it does not affect the calculated slope in any way.

The soft error "0 points to average" is generated if something other than a positive integer is entered for N; in this case the measure is invalid.

pks polarity
Peak slope. Requires the extra argument polarity, either ‘+’ or ‘-’. This function first finds the appropriate peak (p2) and then moves toward smaller latency values until crossing the baseline (p1). It then returns the slope of the line drawn through p1 and p2. The units are in microvolts/second.

The soft error "bad sign arg" is generated if something other than ‘+’ or ‘-’ is entered for polarity; in this case the measure is invalid.

Running Interactively

merp can be run interactively by specifying ‘-’ instead of the name of a measurement command file:


merp -

merp will then expect commands to be entered from the keyboard. As each measurement command is entered merp will perform the indicated function and then return for more input. A CTRL-D will end input from the keyboard, and merp will terminate.

Saving the Measures

Normally the measures and their descriptions are output to the screen, but the measures alone can be saved to a file for subsequent analyses by using the -d option and redirecting standard output:


merp -d negpk501.mcf > negpk501.dat

When one first creates a measurement command file, it is wise to allow the descriptions 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 the measurement command file has been verified as containing the proper commands, the measures alone can be saved for subsequent analyses as shown above.

Errors During Measurement

There are two 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 measurement window will produce a 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 measurement 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 screen, 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 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 screen. In those infrequent cases where one can ignore soft errors, this will prevent the file containing the measures being cluttered with error messages.

Example

A measurement command file to measure mean amplitudes might look like:


# merp mcf
file wm4.avg
file wm6.avg
file wm7.avg
file wm10.avg
file wm11.avg
file wm15.avg
file wm19.avg
file wm21.avg
file wm22.avg
file wm23.avg
file wm24.avg
file wm25.avg
channels 2 4 6 8 10 12 3 5 7 9 11 13 
meana 7 $ * 300 500
meana 18 $ * 300 500
# that’s all!


Table of Contents