CALIBRATE(1)

NAME
calibrate - calibrate signals of a DB record

SYNOPSIS
calibrate -r record [ options ... ]

DESCRIPTION

calibrate rewrites the header file for a DB record, setting the gain and baseline fields based on measurements it makes, and setting the units fields based on input from the user or from a calibration file. Normally, calibrate is used by specifying a time interval for the measurements; best results will be achieved if the specified interval is restricted to one or more square-wave calibration pulses in each signal to be calibrated, although sine-wave pulses may be usable if the sampling frequency and/or ADC resolution is high enough.

The program constructs a smoothed amplitude histogram for each signal and identifies its two principal modes. Initially, each bin of the histogram counts the number of samples in the analysis interval for which the amplitude has a specified value. The histogram is smoothed by applying a low-pass filter that replaces the contents of each bin by a weighted sum of fifteen bins centered on the bin of interest. The two principal modes in the smoothed histogram must be separated by at least one bin with a count that is less than one-eighth the count of the larger mode. If this criterion is not satisfied for a given signal, calibrate warns the user and does not adjust the gain or baseline for the affected signal.

If a signal list is specified using the -s option (see below), only the specified signals are calibrated, and the gain, baseline, and units fields for any other signals are left unchanged. Thus, if calibration pulses are not simultaneously available in all signals to be calibrated, calibrate may be run repeatedly with different time intervals and signal lists.

Options include:

-c file
    Obtain calibration pulse specifications from the specified file (see dbcal(5); default: obtain this information from the file specified by the environment variable DBCAL, or interactively).

-f time
    Begin at the specified time in record (default: the beginning of record).

-h  Print a usage summary.

-q  Instead of using the standard method for calibration, get a `quick-and-dirty' estimate by taking the signal amplitudes at the starting and ending times (as specified by -f and -t) as representative of the low- and high-amplitude phases of the calibration pulse. Use this option only if the standard method fails; the standard method is more accurate.

-Q  Use an alternate `quick-and-dirty' estimate based on the range of signal amplitudes over the interval specified by -f and -t. This method may be easier to use than -q for signals with significant high-frequency content, since it does not require precise location of signal extrema. As noted above, the standard method is more accurate if it can be used.

-s signal-list
    Calibrate only the signals named in the signal-list (one or more input signal numbers, separated by spaces; default: calibrate all signals).

-t time
    Process until the specified time in record (default: 1 second after the starting time).

-v  Ask for calibration pulse limits (default: read limits from the calibration file).

Calibration files must be located in one of the directories named in the database path (see setdb(1)). If the environment variable DBCAL is set, it names a calibration file that will be read unless the -c option is used to specify a different calibration file. At most one calibration file is read; if more than one -c option is given, only the last one is effective. If the calibration file does not contain an entry for the type of signal to be calibrated, calibrate obtains the information from the user interactively. If the calibration file contains two or more entries for the same signal type, only the first entry is used.

The shell variable DB should be set and exported (see setdb(1)).

BUGS
Under MS-DOS, this program is known as calibr8.

SEE ALSO
setdb(1), dbcal(5)