.TH WRSAMP 1 "21 January 2010" "WFDB 10.4.25" "WFDB Applications Guide"
.SH NAME
wrsamp \- write WFDB signal files
.SH SYNOPSIS
\fBwrsamp\fR [ \fIoptions\fR ... ] [ \fIcolumn\fR ... ]
.SH DESCRIPTION
\fBwrsamp\fR reads text-format input and writes the specified \fIcolumns\fR in
WFDB signal file format 16 (see \fBsignal\fR(5)), either to the standard output
or to a disk file (see the \fB-o\fR option below). If no \fIcolumns\fR are
specified, all columns are written (but see the \fB-z\fR option below).
.PP
Normally, \fBwrsamp\fR's input is line- and column-oriented, with
\fIline separator characters\fR (usually ASCII linefeeds) separating
input lines, and \fIfield separator characters\fR (usually tabs,
spaces, or commas) separating columns within each line. Columns need
not be of constant width; the only requirement is that one or more
field separator characters appear between adjacent columns. The
output of \fBrdsamp\fR(1) is an example of an acceptable input format,
as is CSV (comma-separated value) format.
.PP
If the first input line contains any alphabetic character, it is
assumed to contain signal names (column headings), and these are
copied to the output header file (see the \fB-o\fR option below). In
this case, if the second input line also contains any alphabetic
character, it is assumed to contain unit names (i.e., the names of the
physical units of each signal), and these are also copied to the
output header file. Spaces embedded within unit names are written
as underscores in the header file.
.PP
Lines are identified by line number. The first line of input not
containing any alphabetic character is line 0. Similarly, columns are
identified by column number, and the leftmost column is column 0.
Columns may be selected in any order, and any given column may be
selected more than once, or omitted. The order of \fIcolumn\fR
arguments determines the order of the signals in the output (data from
the first \fIcolumn\fR specified are written as signal 0, etc.) If an
entry in a specified column is "-" (i.e., flagged as missing or
invalid), or if an entry in a specified column is any other
non-numeric value, \fBwrsamp\fR records it as an invalid sample in its
output.
.PP
If line 0 appears to begin with a timestamp (a field of the form
\fI[hh:mm:ss.sss dd/mm/yyyy]\fR), \fBwrsamp\fR records it as the
base time (starting time) in the output header file.
.PP
\fIOptions\fR include:
.TP
\fB-c\fR
Check that each input line contains the same number of fields. (This test is
normally disabled, to allow for input files containing preambles, trailers,
or occasional extra fields not intended to be read as samples.)
.TP
\fB-d\fR
Dither the input before converting it to integer output, by adding a random
value to each sample. The 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. Note that the RNG
used to generate the pseudo-random values is started with a fixed seed, so
that \fBwrsamp\fR's output is strictly reproducible. Change the seed in the
source and recompile to obtain a different realization of dither if desired.
.TP
\fB-f\fR \fIn\fR
Start copying with line \fIn\fR. By default, \fBwrsamp\fR starts at the
beginning of its standard input (line 0).
.TP
\fB-F\fR \fIn\fR
Specify the sampling frequency (in samples per second per signal) for the
output signals (default: 250). This option is useful only in conjunction with
\fB-o\fR, since it affects the output header file only. This option has no
effect on the output signal file, which contains one sample per signal for each
line of input. If you wish to change the sampling frequency in the signal
file, see \fBxform\fR(1).
.TP
\fB-G\fR \fIn\fR
Specify the gain (in A/D units per millivolt) for the output signals (default:
200). To specify different gains for each output signal, provide a quoted
list of values in place of \fIn\fR (see the examples below). This option is
useful only in conjunction with \fB-o\fR, since it affects the output header
file only. This option has no effect on the output signal file. If you wish
to rescale samples in the signal file, use \fB-x\fR.
.TP
\fB-h\fR
Print a usage summary.
.TP
\fB-i\fR \fIfile\fR
Read input from the specified \fIfile\fR (default: standard input).
.TP
\fB-l\fR \fIn\fR
Read up to \fIn\fR characters in each line (default: 1024). Longer lines are
truncated (with a warning message identifying the line number of the offending
line).
.TP
\fB-o\fR \fIrecord\fR Write the signal file in the current directory
as \fIrecord\fB.dat\fR, and create a header file in the current
directory for the specified \fIrecord\fR. By default, \fIwrsamp\fR
writes the signal file to its standard output, and does not create a
header file.
.TP
\fB-O\fR \fIformat\fR
Write the signal file in the specified \fIformat\fR (default: 16). See
\fBsignal\fR(5) for descriptions and names of available formats.
.TP
\fB-r\fR \fIc\fR
Interpret \fIc\fR as the input line separator (default: \\n, the ASCII linefeed
character). This option may be useful, for example, to read Macintosh files
containing carriage-return delimited lines. Note that no special treatment is
required for files containing both carriage returns and linefeeds.
.TP
\fB-s\fR \fIc\fR
Interpret \fIc\fR as the input field separator (default: both spaces and tabs
are treated as input field separators). If this option is used, \fIc\fR is
the \fIonly\fR character treated as a field separator.
.TP
\fB-t\fR \fIn\fR
Stop copying at line \fIn\fR (line \fIn\fR is not processed). By default,
\fBwrsamp\fR stops when it reaches the end of file on its standard input.
.TP
\fB-x\fR \fIn\fR
Multiply all input samples by \fIn\fR (default: 1) before writing them to the
output signal file. To specify different scaling factors for each signal,
provide a quoted list of values in place of \fIn\fR (see the examples below).
.TP
\fB-z\fR
Don't copy column 0 unless explicitly specified.
.SH ENVIRONMENT
.PP
It may be necessary to set and export the shell variable \fBWFDB\fR (see
\fBsetwfdb\fR(1)).
.SS Examples
.br
\fBrdsamp -r 100s | wrsamp -o 100w -F 360 1 2\fR
.br
This command creates a record named `100w' that is a copy of record `100s'
(although the signal file format is different). If the \fB-F 360\fR option
were omitted, the output signal file (`100w.dat') would be unchanged, but the
header file for record `100w' would indicate that the sampling frequency was
(the default) 250 Hz, rather than 360 Hz as in record 100s; this is because
\fBwrsamp\fR has no other way of determining the sampling frequency of its
input. Note that columns 1 and 2 of \fIwrsamp\fR's input correspond to signals
0 and 1 respectively; column 0 is the sample number, not useful to
\fBwrsamp\fR.
.br
\fBwrsamp -i in.txt -o out -G "100 100 50" -x "1 .5 -10 2" 4 1 0 3\fR
.br
This command creates a record named `out' that contains signals derived from
four columns of its input (`in.txt'). Notice that the argument of the -G
(gain) option is the quoted string "100 100 50"; the effect is that the
gains of the first two output signals are set to 100, and that of the third
is 50. Since no explicit gain is specified for the fourth signal, it is
assigned the same gain as the previous (third) signal (i.e., 50). Similarly,
the quoted argument of the -x option specifies scaling factors applied to the
samples before they are written to the output signal file: output signal 0
will be unscaled (scale factor 1), signal 1 will be halved (.5), signal 2
will be scaled by 10 and inverted (-10), and signal 3 will be doubled (2).
Finally, note that the four columns selected from the input file have been
rearranged, so that the leftmost column (0) will become output signal 2, etc.
.SH SEE ALSO
\fBrdsamp\fR(1), \fBsetwfdb\fR(1), \fBxform\fR(1), \fBsignal\fR(5)
.SH AUTHOR
George B. Moody (george@mit.edu)
.SH SOURCE
http://www.physionet.org/physiotools/wfdb/app/wrsamp.c