.TH WFDBCAL 5 "5 March 2004" "WFDB software 10.3.12" "WFDB Applications Guide"
.SH NAME
wfdbcal \- WFDB calibration file format
.SH DESCRIPTION
.PP
Programs compiled using the WFDB library (see \fBwfdb\fR(3)) require
calibration data in order to convert between sample values (expressed
in analog-to-digital converter units, or adus) and physical units.
Calibration files specify the physical characteristics of calibration
pulses that may be present in various types of signals, and specify
customary scales for plotting these signals. \fBcalsig\fR(1) reads
the signal file(s) for a record, measures the size of the calibration
pulses it finds in adus, and uses specifications from a calibration
file to determine adu-to-physical unit conversion parameters, the
`gain' and `baseline' fields that it writes back into the header file
for the record. Other programs, such as \fBpschart\fR(1), make use of
the `gain' and `baseline' fields from the header file to determine how
to convert adus into physical units, and use customary scale
specifications from a calibration file to determine how to convert
physical units into units of length on a printed page or on-screen.
Most users will find that a single calibration file, perhaps a
system-wide default, can be used with all of their WFDB records.
.PP
Calibration files are line-oriented text files. Lines are separated by
a carriage-return/line-feed pair. Each type of signal to be calibrated is
described by a one-line entry. The format of each entry is:
.br
\fBDESC\fR\fI<tab>\fBLOW HIGH TYPE SCALE UNITS\fR
.br
where \fBDESC\fR is a string, possibly containing embedded
spaces but not tabs, taken from the signal description field of the header
file entry for signals of the desired type; \fBLOW\fR and \fBHIGH\fR
are the physical measurements that correspond to the low- and high-amplitude
phases of the calibration pulse; \fBTYPE\fR specifies the shape
of the calibration pulse (`sine', `square', or `undefined'); \fBSCALE\fR
specifies the customary scale in physical units per centimeter; and
\fBUNITS\fR is a string (without embedded whitespace) that specifies the
physical units of the signal (e.g., `mV', `mmHg', `degrees_Celsius'). If
\fBLOW\fR is `-', the signal is AC-coupled, and \fBHIGH\fR is taken as the
peak-to-peak amplitude of the calibration pulse. \fBLOW\fI must\fR be defined
(i.e., must not be `-') for DC-coupled signals. If \fBHIGH\fR is `-', the size
of the calibration pulse is undefined.
.PP
Lines that begin with `#', empty lines, and improperly formatted lines are
treated as comments and ignored.
.PP
The WFDB library function \fIgetcal\fR, used by programs such as
\fBcalsig\fR(1), \fBpsfd\fR(1), and \fBwave\fR(1) to obtain calibration
data from a calibration file, returns the first entry that matches a signal's
description and units. A calibration file entry is considered to match a
signal if the \fBDESC\fR field is either `*', or an exact match or a prefix of
the signal description as given in the header file, and if the \fBUNITS\fR
field in the calibration file is an exact match of the units field in the
header file. By making use of these two rules, it is possible to write a
calibration file that contains entries for several specific cases followed by a
`catch-all' case for which the \fBDESC\fR field contains only the common
prefix.
.PP
Note that \fBSCALE\fR specifications are advisory, not mandatory. The
intended use of \fBSCALE\fR is to specify the customary size for
signals, and the relative sizes of signals of varying types. When
determining a \fBSCALE\fR for a signal type for which there is no
customary scale, a good rule of thumb is that the typical short-term
range of variation of the plotted signal should be on the order of one
centimeter; keep in mind that it may be useful to make measurements on
plots, however, and choose a scale that makes such measurements easy
to perform. Programs that draw signals at non-standard scales should
generally adjust the scales for all signals by the same factor, unless
the user specifies otherwise.
.SS Examples
.br
# A simple example of a WFDB calibration file
.br
ECG - 1 sine 1 mV
.br
NBP 0 100 square 100 mmHg
.br
IBP 0 - square 100 mmHg
.br
Resp - - undefined 1 l
.br
In this example, the first line is a comment. The second line specifies that
signals whose descriptions begin with `ECG' are AC-coupled, have units of
millivolts (mV), have 1 mV (peak-to-peak) sine-wave calibration signals, and
are customarily drawn at a scale of 1 mV/cm. The third line specifies that
signals of the `NBP' type are DC-coupled, have units of millimeters of mercury
(mmHg), square-wave calibration signals that go from 0 to 100 mmHg, and are
customarily drawn at a scale of 100 mmHg/cm. The fourth line specifies that
signals of the `IBP' type are DC-coupled (since \fBLOW\fR is specified), also
have units of mmHg, and are customarily drawn at a scale of 100 mmHg/cm, but
that calibration pulses may vary in amplitude. The last line specifies that
`Resp' signals are AC-coupled (since \fBLOW\fR is not specified), have
calibration pulses of variable size and shape, and have units of liters [l].
.PP
An entry of the form:
.br
ECG lead I - 1 sine 1 mV
.br
matches `ECG lead II' as well as `ECG lead I', because of the prefix rule (see
above). If `ECG lead I' and `ECG lead II' were to require different
calibrations for some reason, an entry of the form:
.br
ECG lead II - 2 sine 1 mV
.br
should be inserted \fIbefore\fR the entry for `ECG lead I'.
.PP
Programs that display time series extracted from annotation files (e.g.,
\fBwave\fR(1), which can display the sequence of `num' fields in an annotation
file as a signal) can use calibration records to choose an ordinate scale.
These records can be included in the calibration file, with annotator names
used in place of the signal type, and `units' as the units type. An entry
with signal type "ann" can be used as a default for calibrating data from
files whose annotator names do not have entries. For example,
the default calibration file contains these entries:
.br
edr - - undefined 200 units
.br
ann - - undefined 100 units
The first specifies that data from 'edr' annotation files are to be
displayed at a nominal 200 units per centimeter. The second specifies that
files from other types of annotation files are to be displayed at 100 units
per centimeter.
.SH ENVIRONMENT
Programs compiled with the WFDB library use the environment variable
\fBWFDBCAL\fR to determine the name of the calibration file. Calibration files
must be located in one of the directories named by the WFDB path (see
\fIsetwfdb\fR(1)).
.SH SEE ALSO
\fBcalsig\fR(1), \fBsetwfdb\fR(1), \fBannot\fR(5), \fBheader\fR(5).
\fBsignal\fR(5)
.br
\fIWFDB Programmer's Guide\fR
.SH AUTHOR
George B. Moody (george@mit.edu)