.TH XFORM 1 "13 August 1996" "MIT DB software 9.6" "DB applications"
.SH NAME
xform \- sampling frequency, amplitude, and format conversion for DB records
.SH SYNOPSIS
\fBxform -i\fI input-record\fR [ \fIoptions\fR ... ]
.SH DESCRIPTION
\fIxform\fR copies the signal files (and, optionally, annotation files) of the
specified \fIinput-record\fR.  By default, all signals are copied in their
entirety;  using appropriate options, \fIxform\fR can be used to copy only
a portion of the record, or only a subset of the signals, or both.
\fIOptions\fR are:
.TP
\fB-a\fI annotator\fR
Copy the specified \fIannotator\fR as well as the signal files.  Two or more
\fIannotator\fR arguments, separated by spaces, can follow \fB-a\fR.  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.
.TP
\fB-f\fI time\fR
Begin at the specified \fItime\fR in the input record (default: the
beginning of the record).
.TP
\fB-h\fR
Print a usage summary.
.TP
\fB-H\fR
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).
.TP
\fB-n\fI new-record\fR
Create a \fInew-record\fR for the output signal files.
.TP
\fB-N\fI new-record\fR
As above, but copy the signal descriptions from the header file for the
record specified using the \fB-o\fR option (see below) rather than from
the input record.
.TP
\fB-o\fI output-record\fR
The header file for \fIoutput-record\fR (which must exist before running
\fIxform\fR) determines the names, sampling frequency, formats (see
\fIsignal\fR(5)), gains, and ADC zero levels of the output signals.
If the \fB-o\fR option is absent, \fIxform\fR prompts the user for the
output specifications.
.TP
\fB-s\fR \fIsignal-list\fR
Write only the signals named in the \fIsignal-list\fR (one or more input signal
numbers, separated by spaces;  default: write all signals).  This option may be
used to re-order or duplicate signals.
.TP
\fB-t\fI time\fR
Process until the specified \fItime\fR in the input record (default: continue
to the end of the record).
.PP
If a \fInew-record\fR 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 \fB\-a\fR are associated with \fInew-record\fR if it has been
specified, or with \fIoutput-record\fR otherwise.
To process only a segment of the \fIinput-record\fR, specify the starting and
ending times using the \fB-f\fR and \fB-t\fR options.
.PP
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 \fIxform\fR (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 \fIfir\fR(1)) to remove these components before processing
them with \fIxform\fR.  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.
.PP
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.
.PP
Also note that \fIxform\fR writes over any existing data files named in 
the header file for \fIoutput-record\fR;  thus \fIoutput-record\fR 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" \fI8\fR and \fI16\fR and the "local records"
\fI8l\fR and \fI16l\fR will be found useful as output records.
.PP
If signal selection, scaling, and sampling frequency conversion are not needed,
\fIsnip\fR(1) is recommended as a faster alternative to \fIxform\fR.
.PP
The shell variable \fBDB\fR should be set and exported (see \fIsetdb\fR(1)).
.SH DIAGNOSTICS
.PP
As \fIxform\fR 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,
\fIxform\fR issues warnings but continues to process the record.
.SH SEE ALSO
fir(1), setdb(1), snip(1), signal(5)