|
|
Docs: normerps
Normerps (E1) is a program used to "normalize" averaged ERP data in the ERPSS format. Normalization standardizes ERPSS data files so that numerical values represent definite voltages, since the gain of recording apparatuses can vary with experimental setups as well as between channels. This normalization is performed by measuring the size of a known calibration pulse separately for each channel, and then scaling each data channel, given the desired data resolution. Normalization also establishes the polarity of the data, inverting it if necessary so that positive values represent positive voltages. Averaged data from averaging programs requires normalization prior to plotting, measurement, and other forms of data manipulation. By convention, one records calibration pulses of a known size simultaneously on all channels of a recording configuration, and averages these pulses together in bin 0 of an averaged data file.
Note that differences in gains between channels can arise at the polygraph, an analog instrumentation recorder (if employed), or any other intermediate signal processing step. Hence, it is always necessary to record calibration pulses and process them in exactly the same way as the ERPs themselves. If all the processing steps are linear operations and the calibration pulses are of reasonable size, normerps will properly normalize all channels to the same gain and fix the resolution of the stored digital data.
One generally employs normerps with a display device so that the calibration pulses can be viewed and cursors can be placed on the waveform that accurately measure the size of the pulses. If desired, one can average a number of points around the cursors to achieve higher accuracy if the pulses are noisy. The latencies for the low and high cursors is requested from the standard input; these are demarcated on the display of the data by wider traces. The size of the calibration pulses, the polarity of the data (positive or negative "up"), and the desired resolution of the output data (as a number of "points" per microvolt) are then requested. An interactive session then begins wherein one can alter various parameters relating to the normalization process and the display of the data. When satisfied that the parameters are appropriate, normalization begins.
One can also invoke normerps in a non-display, non-interactive, "silent" mode, if desired, where the required parameters are supplied on the command line. This should only be done if one is certain that the parameters are appropriate for the data at hand.
Normerps is invoked thusly:
Even though it is possible to renormalize previously normalized data, normerps employs separate input and output data files. This maneuver is designed to allow one to backtrack if valuable averaged data is accidentally clobbered by supplying invalid or incorrect parameters to normerps. The in_data_file is not altered by normerps, and can thus be reused as input to normerps, if necessary. Once one has verified that the data are properly normalized and intact, it is relatively safe to remove the unnormalized data file; doing so conserves disk space.
Options for normerps are selected by supplying additional arguments on the invocation line that begin with "-". An option may have none, one, or many arguments of its own. In the case of normerps, each option has a specified number of arguments as described below. Since there is no easy way to detect omitted option arguments if more than one option is requested, be sure the invocation line is correct. Many of the options duplicate functions that can be invoked once the interactive session begins. They are available on the invocation line both so that one can, for example, view the data with a better display magnification or select the channels to be displayed at the outset, as well as so that data can be measured non-interactively with certain other options in effect.
Here are the options that are currently implemented:
-a lobeavgpts
The -a option causes normerps to average lobeavgpts on both sides of the cursors and the cursor itself to calculate the data values. This can reduce the error if noisy calibration pulses have been recorded. Since the argument is a count for a single side, the total number of points averaged will be 2 * lobeavgpts + 1. This parameter can also be changed in interactive mode.
-s scaleplot
One can select a magnification for the data display by supplying an integer scaleplot with this option. This factor is multiplied by the data, and the result divided by 100 when the data are displayed on the disp_dev. Since the display of data involves certain arbitrary translations and scalings in any case, and changes in the plotted data do not affect the normalization or measurements, one should select a plotting scale factor that facilitates accurate placement of the cursors and an easily viewed display. The actual scaling factor is (thus) scaleplot / 100. The use of an integer in place of an actual floating point magnification speeds the drawing calculations. The plotting scale factor can also be altered with an interactive mode command.
-f caldatafile
One can normalize one data file using the unnormalized calibration pulses from another file, caldatafile. This is useful in a number of situations, such as when the calibration pulses had to be recorded post-hoc or failed to be recorded, and one wishes to employ pulses recorded in another file. It is also useful when one wishes to process the cal pulses using another program (e.g. filter them) prior to measurement and normalization. This can be accomplished by extracting the calibration data bin from the unnormalized file using datacat, filtering it, and then supplying the name of the file containing the filtered pulses to normerps using the -c option.
-c calbin
Although bin 0, by convention, contains the calibration pulses in an unnormalized ERPSS data file, the enforcement of this convention is lax and it may be useful on occasion to have more than one bin containing calibration data. This -c option allows one to specify the bin which contains the appropriate calibration data. This bin, calbin, refers to the input data file, unless the -f option is in effect, in which case the specified bin in the calibration data file is used.
-d dchanlist
If desired, when normerps is being used in interactive mode, the data channels that should be displayed in the initial plot can be specified using the -d option. The channels to be plotted form the argument in the form of a comma-separated list of channels and/or ranges (see getilist (E3u)). For example, to display channels 0, 1, 2, 3, 6, 7, 8, and 9, one could use:
-d 0-3,6-9or, equivalently,
-d 0,1,2,3,6,7,8,9Note that no white space (spaces or tabs) are allowed in the list. Since the display devices have a limited resolution and when many data channels have been recorded it can be difficult to separate the traces unless the plotting scale factor is very small, it is useful to visually confirm the placement of the cursors by displaying subsets of the data channels at a time. One can alter the channels on the display using an interactive normerps command, as needed, to view all the data.
-p
If desired, normerps (E1) will print the measured sizes of the calibration pulses on each channel, as well as the normalization scaling factor that will be applied to the data when the -p option is used. Note that the measured sizes are in "points", and both the size and the scaling factor will be negative if a polarity inversion is necessary to achieve standardized form.
-n lo_cursor hi_cursor cal_size polarity resolution
This option prevents normerps from entering an interactive session, and the display device is not opened (and hence does not need to be valid). The information needed to perform the normalization is taken from the five arguments for this option, and consist of the latencies for the low and high cursors (lo_cursor and hi_cursor), the size of the calibration pulses (cal_size) as an integer, the polarity of the data (polarity) as either a + or -, and the desired resolution of the output file (resolution) as an integer number of points per microvolt. These parameters are the same as would be supplied during interactive acquisition, and hence the same considerations apply. While normerps will complain if the parameters are out of range, inaccuracy during the data normalization will occur if the parameters are not appropriate for the data at hand. Thus, care should be used when the -n is employed.
Four basic parameters control the normalization of data by normerps (E1). These are the size of the calibration pulses in the recorded data (this differs from channel to channel), the actual size, in microvolts, of the calibration pulses when the data were recorded, the polarity of the data, and the desired resolution for the data in the output file, in points per microvolt. The size of the calibration pulses in the recorded data is derived separately for each channel by measuring the data values at two cursors, hence normerps requires that five parameters be set before normalization can occur, whether it be by interactive adjustment of parameters while viewing the data, or by way of the -n invocation option.
In either case, given the normalization parameters, the absolute values of the difference between the data measured at the cursors is used, along with the specified polarity, desired resolution, and size of the calibration pulses, to determine the scaling constant for each channel. Normerps then multiplies the data for each channel by the corresponding normalization constant. This is repeated for each processing function and bin in the input data file, and the result placed in the output data file. The reference header for the output data file is updated to indicate that the data are normalized. Tips and suggestions on how to specify the normalization parameters are contained in the detailed descriptions below.
It should be stressed at this point that the actual size of the calibration pulses delivered to the recording system and the manner in which the calibration device was connected in comparison to the manner in which the subject was connected are critical pieces of information that cannot be reconstructed solely from viewing the data. Careful written records or notes about the recording from each subject are recommended. In addition to these parameters, the recording settings (e.g. filter settings, etc) and a list of abnormal events that occurred can be very helpful down the line, and can often save considerable grief later.
Since the amplification accuracy of the data ultimately relies on the size of the calibration pulses as they are measured in the unnormalized data file, one should be careful when setting the low and high measurement cursors. The goal is to accurately assess the size of the pulse in all channels simultaneously. One should ensure that the cursors do not lie on a portion of the waveform that contains overshoot or noise. Since any high-pass filtering will cause square pulses to decay towards the baseline, usually one will attempt to get as close as possible to the leading edge of the pulse with the low cursor while still measuring the pre-pulse data value, and also attempting to stay as close to the leading edge of the pulse with the high cursor but after it has attained its active value. In some cases it may be advantageous to measure the falling edge of the calibration pulses if, for instance, the leading edges have excessive noise, artifactual contamination, or overshoot that is not present on the falling edge. Small random variations in the data values from point to point can be mitigated by averaging a number of points in the vicinity of the cursors together to obtain the data values. This can be accomplished by the -a invocation option, or selected interactively.
This parameter is straightforward, but its accuracy is crucial to the normalization process. One supplies the size of the calibration pulse delivered to the recording apparatus when the pulses were recorded. This value must be an integer, and since one is the smallest integer, some anticipation of this requirement may be necessary if the calibration device cannot supply arbitrary voltages.
The question of the polarity of the recorded data can be confusing, but need not be. A simple rule will allow an accurate determination of the polarity of the data, regardless of whether interposed devices invert the data before digitization or not, or how the various connectors are labeled on the polygraph.
Polarity Rule: - IF: the active lead of the amplifier (e.g. vertex) was connected to the positive side of the calibration source? IF: if the pulses are displayed going upward on the plot, positive is up, type a +... ELSE: negative is up, type a -... ELSE IF: the active lead of the polygraph amplifier was connected to the negative side of the calibration source? IF: the pulses are displayed going upward, negative is up, type a -... ELSE: positive is up, type a +...
This rule always works for referential recordings and, indeed, no other type of recording need be made, as the ERPSS software allows computation of arbitrary derivations from "referential" recordings. However, if a number of "bipolar" data channels are included in the data, one should take care that they are recorded in a manner that will allow them to be properly normalized with normerps.
The resolution with which the data in the output file will be stored is set by this parameter. It is a tradeoff between the range of voltages that can be represented in a signed 16 bit integer (-32767 to 32767), and the precision of the smallest difference in data values that can be stored. Many of the ERPSS programs employ a default value of 100 points per microvolt, allowing a data range of -327.67 to 327.67 microvolts. This is on the safe side in terms of probability of a data overflow, since even single trials will almost never be this large for scalp-recorded data, and implies a precision of .01 microvolts. A value of 500 gives .002 microvolt precision, yet still allows a range of -65.5 to 65.5 microvolts, generally plenty for averaged ERPs. Nonetheless, the resolution should be chosen according to the type of data and experiment. In any case, it is not too important as long as information is not degraded, as all ERPSS programs consider the data resolution for each file separately when the data are processed, adjusting the values internally if necessary.
In interactive use, the following sequence of steps is performed by normerps after invocation. First, the input data file is opened, the output data file created, and a description of the data is printed on the standard output. If the -c option is in effect, the calibration data file is opened and checked to ensure that it has the same number of channels as the input data file. Next, the display device is opened and the data are plotted, along with a time base and descriptions of the channels. Note that if a different file is being used for the calibration pulse data, the descriptions will refer to those data, not the input data file, although the descriptions and parameters from the input data file will be transferred to the output file. At this point, normerps requests the required parameters. The data are then re-drawn with the cursor locations (along with any possible averaging of neighboring points) shown with a thicker trace, to enable easy identification of the data that would be used to determine the size of the cal pulse.
An interactive mode is then entered, where normerps accepts single-letter commands from the standard input that alter various parameters. When accepting commands, one does not need to type a return; however, when arguments or parameters are being gathered for a command, a return is needed. When one is satisfied that the parameters are correct, indicate that it's OK to normalize the data. The plot device is then closed, and the input data file is normalized and placed in the output data file. The total number of bins is then printed to indicate that normalization is complete.
In interactive mode, the five required parameters are requested from the standard input; these take values as described above in the section entitled Normalization Parameters. The interactive session then begins, and one selects various functions using single letters without carraige returns. The case of the letters is unimportant, both upper and lower case characters of the same letter have the same function. The five required parameters can, of course, be changed. However, additional commands can be invoked to perform certain optional functions or set optional parameters. When a command requires an argument, normerps prints a brief prompt and waits for input which must be terminated with a carriage return. If the argument is out of range, either in an absolute sense or in relation to other current parameters, normerps repeats the request. Whenever a parameter that affects the display of the data is changed, the plot is re-drawn. In any case where a parameter is changed, normerps prints a summary of the current values of the parameters on the standard output. If an unimplemented command is typed, a brief synopsis of the implemented commands is printed on the standard output. Here follows a detailed description of the optional commands and their functions.
Plot Scaling
The size with which the unnormalized data are plotted on the display device can be changed interactively by using the s command. The argument is the same as described above under Command Line Options. The value should be chosen to maximize the utility of the plot on the display device.
Displayed Channels
The subset of all the channels that are displayed on the display device can be altered using the d command. The argument is the same as described above under Command Line Options; that is, a comma-separated list of channels to display.
Number of Points to Average
The parameter, again, is the same as described above under Command Line Options. Remember that this parameter is the number of points on each side of the cursors, and hence the total number of points being averaged is twice this value plus one, centered on each cursor. One should take care that all the points being averaged together are propitiously located on the calibration pulses, as denoted by the thicker portions of the traces on the display device.
Quit Immediately
This command immediately exits from normerps, removing the output file.
Help
By typing a question mark, a brief description of the purpose of normerps and the various parameters is printed on the standard output.
OK to Normalize
When one is certain that all the parameters have appropriate values, invoke this command. Normerps will ask "Are you sure?", and, if one is sure, type a Y, yes, or anything beginning with a y. Any other characters cause normerps to revert to the interactive session.
There are hundreds of primitive operations that can generate errors during the operation of normerps, and a detailed description of each is not worthwhile, as most are self-explanatory. In all cases each nested routine prints the proximal cause of the error, thus giving substantial diagnostic information. Note that most errors are fatal, and cause the removal of the output data file. In addition, during execution, most signals are caught and also cause premature termination with the removal of the output data file.
Three common problems should be discussed. First, to prevent inadvertent destruction of a data file, normerps will not create a data file that already exists! The solution for this is to remove the existing file, if it is no longer wanted, or to use another name for the output data file. The second problem that can crop up is a data overflow. This can be solved by reducing the requested output resolution. Third, if the measured sizes of the calibration pulses is too small, normerps will complain. This is best corrected by increasing the gain of the amplification system during the recording session.
Except for parameters being out of range, other errors generally indicate something is seriously wrong.