xform - sampling frequency, amplitude, and format conversion for WFDB
xform -i input-record [ options ... ]
the signal files (and, optionally, annotation files) of the specified input-record.
By default, all signals are copied in their entirety; using appropriate
options, xform can be used to copy only a portion of the record, or only
a subset of the signals, or both. Options are:
- -a annotator
- Copy the specified
annotator as well as the signal files. Two or more annotator arguments,
separated by spaces, can follow -a. An annotator supplied via the standard
input may be specified using ‘-’, but only immediately after -a; in this case
only, annotations are copied to the standard output.
- Clip the output (set
any sample values that would fall outside of the range supported by the
selected format to the maximum or minimum supported values). By default,
the output is not clipped; rather, the values are wrapped around modulo
the supported range (i.e., the excess high-order bits are simply discarded).
Use of wrap-around can result in bizarre artifacts, but has the advantage
that the affected portions of the output signals can (usually) be interpreted
properly. Clipping mode is appropriate for testing algorithms or devices
that must operate using a more restricted amplitude range than was used
when digitizing the original record.
- Dither the input by adding a pseudo-random
value to each sample. The pseudo-random values are selected from a triangular
probability density function between -1 and +1. Dithering is appropriate
whenever the output has a lower resolution than the input, as may occur
when changing the sampling frequency or gain. The -d option has no effect
unless the sampling frequency or gain are changed in the output record.
Note that the RNG used to generate the pseudo-random values is started
with a fixed seed, so that xform’s output is strictly reproducible. Change
the seed in the source and recompile to obtain a different realization
of dither if desired.
- -f time
- Begin at the specified time in the input record
(default: the beginning of the record).
- Print a usage summary.
- Read the
signals in high-resolution mode (default: standard mode). These modes are
identical for ordinary records. For multifrequency records, the standard
decimation of oversampled signals to the frame rate is suppressed in high-resolution
mode (rather, all other signals are resampled at the highest sampling frequency).
- Read the signals in multifrequency mode. Each signal (in a multifrequency
record) is copied to the output record without changing its sampling frequency.
In an ordinary record, this option has no effect other than to force the
input and output sampling frequencies to be equal.
- -n new-record
- Create a
new-record for the output signal files.
- -N new-record
- As above, but copy the
signal descriptions from the header file for the record specified using
the -o option (see below) rather than from the input record.
- -o output-record
- The header file for output-record (which must exist before running xform)
determines the names, sampling frequency, formats (see signal(5)
and ADC zero levels of the output signals. If the -o option is absent, xform
prompts the user for the output specifications.
- -s signal-list
- Write only
the signals named in the signal-list (one or more input signal numbers or
names, separated by spaces; default: write all signals). This option may
be used to re-order or duplicate signals.
- -S script
- Take answers to prompts
from the specified script (a text file).
- -t time
- Process until the specified
time in the input record (default: continue to the end of the record).
- Adjust annotation times as needed so that they are unique. If the output
sampling frequency is less than that of the input, the times of closely-spaced
annotations may coincide in the output, which may cause problems for some
older WFDB applications. The -u option avoids this.
If a new-record is specified,
a new header file is created after the signal file transformation is complete.
The new header file, if created, contains the correct sample counts and
checksums for the new signal files. Any output annotation files that are
created as a result of using -a are associated with new-record if it has
been specified, or with output-record otherwise. To process only a segment
of the input-record, specify the starting and ending times using the -f and
Sampling frequency changes are performed by linear interpolation;
any combination of input and output sampling frequencies is permissible.
This interpolation method has the advantage of being reasonably fast,
an important consideration since it is often necessary to operate on a
million or more samples. Resampling noise is not a significant problem
for the typical applications of xform (changing the sampling frequency
by factors of five or less). Aliasing can be a problem, however, when the
input sampling frequency is greater than the output sampling frequency.
In such cases, if the input signals contain frequency components at or
above half of the output sampling frequency, the input signals should be
low-pass filtered (using, for example fir(1)
) to remove these components
before processing them with xform. Conversely, if the output sampling frequency
is substantially greater than the input sampling frequency, resampling
noise introduced at frequencies in excess of half of the input sampling
frequency can be removed by low-pass filtering the output signals.
the ADC resolution fields in the header files are ignored, and scaling
is determined by the ratios of the gain fields. An undefined (0) gain is
considered equivalent to a gain of 200 ADC units per physical unit. An exception
to this rule occurs if both input and output gains are undefined; in this
case, scaling is determined by the difference in the ADC resolution fields,
Also note that xform writes over any existing data files named in
the header file for output-record; thus output-record should not be the
name of an ordinary database record. Normally, the database signal files
are read-only, and attempts to overwrite them are futile. For many applications
the "piped records" 8 and 16 and the "local records" 8l and 16l will be
found useful as output records.
If signal selection, scaling, and sampling
frequency conversion are not needed, snip(1)
is recommended as a faster
alternative to xform.
It may be necessary to set and export the
shell variable WFDB (see setwfdb(1)
As xform runs, it prints
a ‘.’ on the standard error output for each minute processed. If any of the
output samples fall outside the range of values that can be properly represented
using the specified output format, xform issues warnings but continues
to process the record.
B. Moody (email@example.com)
Table of Contents
Up: WFDB Applications Guide
Please e-mail your comments and suggestions to firstname.lastname@example.org, or post them to:PhysioNet
MIT Room E25-505A
77 Massachusetts Avenue
Cambridge, MA 02139 USA
Updated 8 March 2019