.TH MRGANN 1 "31 July 2002" "WFDB 10.2.7" "WFDB Applications Guide"
.SH NAME
mrgann \- merge annotation files
.SH SYNOPSIS
\fBmrgann -r\fR \fIrecord\fR \fB-i\fR \fIann1 ann2\fR \fB-o\fR \fIann3\fR [ \fIoptions\fR ... ]
.SH DESCRIPTION
.PP
\fBmrgann\fR reads a pair of annotation files (specified by \fIann1\fR,
\fIann2\fR) for the specified \fIrecord\fR and writes a third annotation file
(specified by \fIann3\fR) for the same \fIrecord\fR.  Typical applications of
\fBmrgann\fR include combining annotation files that apply to different signals
within a multi-signal record, and replacing a segment of an annotation file
with annotations from another file (see the examples below).  \fBmrgann\fR
cannot concatenate annotation files from \fIdifferent\fR records (e.g.,
segments of a multi-segment record);  use \fBwfdbcollate\fR(1) for this purpose.
If you wish to merge annotation files in order to be able to study or resolve
the differences between them, \fBbxb\fR(1) (which can also merge annotation
files using its \fB-o\fR or \fB-O\fR options) is almost certainly a better
choice for such an application.
.PP
By default, the output annotation file contains copies of all annotations in
each of the input files (if there are annotations with the same \fBtime\fR and
\fBchan\fR fields in each input file, however, only the annotation from
\fIann1\fR is copied).  This behavior can be modified by command-line
\fIoptions\fR, which include:
.TP
\fB-c\fR \fIn\fR
Map (reset) the \fBchan\fR fields of all annotations from \fIann1\fR to
\fIn\fR.  \fBchan\fR fields may contain integers between 0 and 255 inclusive;
the \fBchan\fR field often specifies the signal number of the signal with which
the annotation is associated.  Specify \fB-c -1\fR to disable \fBchan\fR
mapping for \fIann1\fR (the default).
.TP
\fB-C\fR \fIn\fR
Map (reset) the \fBchan\fR fields of all annotations from \fIann2\fR to
\fIn\fR.  Specify \fB-C -1\fR to disable \fBchan\fR mapping for \fIann2\fR
(the default).
.TP
\fB-h\fR
Print a usage summary.
.TP
\fB-m0\fR \fItime\fR
Discard all annotations from both input annotators, beginning at \fItime\fR,
until the time specified in the next \fB-m\fIx\fR option, or the end of the
data if no other \fB-m\fIx\fR option is given.
.TP
\fB-m1\fR \fItime\fR
Copy all annotations from \fIann1\fR, and discard all annotations from
\fIann2\fR, beginning at \fItime\fR, until the time specified in the next
\fB-m\fIx\fR option, or the end of the data if no other \fB-m\fIx\fR option is
given.
.TP
\fB-m2\fR \fItime\fR
Copy all annotations from \fIann2\fR, and discard all annotations from
\fIann1\fR, beginning at \fItime\fR, until the time specified in the next
\fB-m\fIx\fR option, or the end of the data if no other \fB-m\fIx\fR option is
given.
.TP
\fB-m3\fR \fItime\fR
Copy all annotations from \fIann1\fR and \fIann2\fR, beginning at \fItime\fR,
until the time specified in the next \fB-m\fIx\fR option, or the end of the
data if no other \fB-m\fIx\fR option is given.  Annotations from \fIann2\fR
that match others from \fIann1\fR in both the \fBtime\fR and \fBchan\fR fields
(after any \fIchan\fR mapping has been applied, see above) are discarded.
This mode is the default.
.TP
\fB-v\fR
Verbose mode (warn about simultaneous annotations with matching \fBchan\fR
fields).
.PP
Note that options are interpreted in left-to-right order.  For this reason,
if you specify more than one \fB-m\fIx\fR option, as in the second example
below, be sure to specify them in time order.  It is also possible to use
different \fBchan\fR mapping rules during different segments of the record;
to do this, specify the appropriate \fB-c\fR or \fB-C\fR option(s) \fIbefore\fR
the \fB-m\fIx\fR option that specifies the time when the new mapping rules are
to be applied.
.SH EXAMPLES
.PP
To merge three sets of annotations (named \fBa0\fR, \fBa2\fR, and \fBa3\fR, one
for each of signals 0, 2, and 3 of record \fB999\fR), use the following
commands:
.br
	\fBmrgann -r 999 -a a0 a2 -o tmp -c 0 -C 2\fR
.br
	\fBmrgann -r 999 -a tmp a3 -o all -c -1 -C 3\fR
.br
Note that two passes are needed to merge three annotation files,
since \fBmrgann\fR reads only two annotation files at a time.  The first pass
yields an intermediate result (annotator \fBtmp\fR);  annotator \fBall\fR is
the desired output.  The \fB-c -1\fR option in the second command above
disables \fBchan\fR mapping for annotations in \fBtmp\fR, which have already
been mapped as a result of the first command;  this option could have been
omitted, since \fBchan\fR mapping is disabled by default.
.PP
To replace any annotations in a set (named \fBold\fR) during the interval
between 5 minutes and 6 minutes from the beginning of record \fBxyz\fR, with
annotations from another set (named \fBnew\fR), use the command:
.br
	\fBmrgann -r xyz -a old new -o out -m1 0 -m2 5:0 -m1 6:0\fR
.br
In this command, the desired output is written to annotator \fBout\fR for
record \fBxyz\fR.  The \fB-m1 0\fR option overrides the default behavior and
forces any \fBnew\fR annotations that occur before the 5-minute mark to be
discarded, while existing \fBold\fR annotations are copied to \fBout\fR.
Beginning at the 5-minute mark, the \fB-m2 5:0\fR option changes the rules,
and the \fBold\fR annotations are discarded as the \fBnew\fR ones are copied.
The rules are changed a third and final time at the 6-minute mark by the
\fB-m1 6:0\fR option, which instructs \fImrgann\fR to copy the remaining
\fBold\fR annotations to \fBout\fR, while once again discarding any \fBnew\fR
annotations that occur during this interval.
.SH ENVIRONMENT
.PP
It may be necessary to set and export the shell variable \fBWFDB\fR (see
\fBsetwfdb\fR(1)).
.SH SEE ALSO
\fBbxb\fR(1), \fBsetwfdb(1), \fBwfdbcollate\fR(1)
.SH AUTHOR
George B. Moody (george@mit.edu)
.SH SOURCE
http://www.physionet.org/physiotools/wfdb/app/mrgann.c