xform - sampling frequency, amplitude, and format conversion for WFDB
records
xform -i input-record [ options ... ]
xform copies
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.
- -c
- 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.
- -f time
- Begin at the specified time
in the input record (default: the beginning of the record).
- -h
- Print a usage
summary.
- -H
- 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).
- -M
- 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)
), gains, 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, separated by spaces; default: write all signals).
This option may be used to re-order or duplicate signals.
- -t time
- Process
until the specified time in the input record (default: continue to the
end of the record).
- -u
- 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 -t options.
Sampling frequency changes are
performed by linear interpolation; any combination of input and output
sampling frequencies is permissible, provided that both are integers (if
non-integer sampling frequencies are specified, they are truncated to multiples
of 1 Hz before the interpolation/decimation parameters are determined).
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.
Normally, 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, if any.
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.
fir(1)
, setwfdb(1)
, snip(1)
, signal(5)
George
B. Moody (george@mit.edu)
http://www.physionet.org/physiotools/wfdb/app/xform.c
Table of Contents
Up: WFDB Applications Guide
Please e-mail your comments and suggestions to webmaster@physionet.org, or post them to:
PhysioNet
MIT Room E25-505A
77 Massachusetts Avenue
Cambridge, MA 02139 USA
Updated 24 February 2003