Table of Contents
merp - measure ERPs (event-related potentials)
merp [options]
mcf [mcf2 ... ]
merp [options] -
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).
- -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.
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.
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.
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.
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.
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