XFORM(1)

NAME
xform - sampling frequency, amplitude, and format conversion for DB records

SYNOPSIS
xform -i input-record [ options ... ]

DESCRIPTION
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.

-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 signal files 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).

-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).

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.

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

DIAGNOSTICS

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.

SEE ALSO
fir(1), setdb(1), snip(1), signal(5)