Programs compiled
using the WFDB library (see wfdb(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. calsig(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 pschart(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.

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: DESC<tab>LOW HIGH TYPE SCALE UNITS

where DESC 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; LOW and HIGH are the physical measurements that correspond
to the low- and high-amplitude phases of the calibration pulse; TYPE specifies
the shape of the calibration pulse (‘sine’, ‘square’, or ‘undefined’); SCALE
specifies the customary scale in physical units per centimeter; and UNITS
is a string (without embedded whitespace) that specifies the physical units
of the signal (e.g., ‘mV’, ‘mmHg’, ‘degrees_Celsius’). If LOW is ‘-’, the signal is
AC-coupled, and HIGH is taken as the peak-to-peak amplitude of the calibration
pulse. LOW must be defined (i.e., must not be ‘-’) for DC-coupled signals. If
HIGH is ‘-’, the size of the calibration pulse is undefined.

Lines that begin
with ‘#’, empty lines, and improperly formatted lines are treated as comments
and ignored.

The WFDB library function getcal, used by programs such as
calsig(1)
, psfd(1)
, and wave(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 DESC field
is either an exact match or a prefix of the signal description as given
in the header file, and if the UNITS 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 DESC
field contains only the common prefix.

Note that SCALE specifications are
advisory, not mandatory. The intended use of SCALE is to specify the customary
size for signals, and the relative sizes of signals of varying types. When
determining a SCALE 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.

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 LOW 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 LOW is not specified), have calibration
pulses of variable size and shape, and have units of liters [l].

An entry
of the form: ECG lead I - 1 sine 1 mV

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: ECG lead II - 2 sine 1 mV

should be inserted before the entry for ‘ECG lead I’.

Programs that display
time series extracted from annotation files (e.g., wave(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:
edr - - undefined 200 units

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.

Programs compiled with the WFDB library use the
environment variable WFDBCAL to determine the name of the calibration file.
Calibration files must be located in one of the directories named by the
WFDB path (see setwfdb(1)
).