MRGANN(1)

NAME
mrgann - merge annotation files

SYNOPSIS
mrgann -r record -i ann1 ann2 -o ann3 [ options ... ]

DESCRIPTION

mrgann reads a pair of annotation files (specified by ann1, ann2) for the specified record and writes a third annotation file (specified by ann3) for the same record. Typical applications of mrgann 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). mrgann cannot concatenate annotation files from different records (e.g., segments of a multi-segment record); use dbcollate(1) for this purpose. If you wish to merge annotation files in order to be able to study or resolve the differences between them, bxb(1) (which can also merge annotation files using its -o or -O options) is almost certainly a better choice for such an application.

By default, the output annotation file contains copies of all annotations in each of the input files (if there are annotations with the same time and chan fields in each input file, however, only the annotation from ann1 is copied). This behavior can be modified by command-line options, which include:

-c n
    Map (reset) the chan fields of all annotations from ann1 to n. chan fields may contain integers between 0 and 255 inclusive; the chan field often specifies the signal number of the signal with which the annotation is associated. Specify -c -1 to disable chan mapping for ann1 (the default).

-C n
    Map (reset) the chan fields of all annotations from ann2 to n. Specify -C -1 to disable chan mapping for ann2 (the default).

-h  Print a usage summary.

-m0 time
    Discard all annotations from both input annotators, beginning at time, until the time specified in the next -mx option, or the end of the data if no other -mx option is given.

-m1 time
    Copy all annotations from ann1, and discard all annotations from ann2, beginning at time, until the time specified in the next -mx option, or the end of the data if no other -mx option is given.

-m2 time
    Copy all annotations from ann2, and discard all annotations from ann1, beginning at time, until the time specified in the next -mx option, or the end of the data if no other -mx option is given.

-m3 time
    Copy all annotations from ann1 and ann2, beginning at time, until the time specified in the next -mx option, or the end of the data if no other -mx option is given. Annotations from ann2 that match others from ann1 in both the time and chan fields (after any chan mapping has been applied, see above) are discarded. This mode is the default.

-v  Verbose mode (warn about simultaneous annotations with matching chan fields).

Note that options are interpreted in left-to-right order. For this reason, if you specify more than one -mx option, as in the second example below, be sure to specify them in time order. It is also possible to use different chan mapping rules during different segments of the record; to do this, specify the appropriate -c or -C option(s) before the -mx option that specifies the time when the new mapping rules are to be applied.

EXAMPLES

To merge three sets of annotations (named a0, a2, and a3, one for each of signals 0, 2, and 3 of record 999), use the following commands:
    mrgann -r 999 -a a0 a2 -o tmp -c 0 -C 2
    mrgann -r 999 -a tmp a3 -o all -c -1 -C 3
Note that two passes are needed to merge three annotation files, since mrgann reads only two annotation files at a time. The first pass yields an intermediate result (annotator tmp); annotator all is the desired output. The -c -1 option in the second command above disables chan mapping for annotations in tmp, which have already been mapped as a result of the first command; this option could have been omitted, since chan mapping is disabled by default.

To replace any annotations in a set (named old) during the interval between 5 minutes and 6 minutes from the beginning of record xyz, with annotations from another set (named new), use the command:
    mrgann -r xyz -a old new -o out -m1 0 -m2 5:0 -m1 6:0
In this command, the desired output is written to annotator out for record xyz. The -m1 0 option overrides the default behavior and forces any new annotations that occur before the 5-minute mark to be discarded, while existing old annotations are copied to out. Beginning at the 5-minute mark, the -m2 5:0 option changes the rules, and the old annotations are discarded as the new ones are copied. The rules are changed a third and final time at the 6-minute mark by the -m1 6:0 option, which instructs mrgann to copy the remaining old annotations to out, while once again discarding any new annotations that occur during this interval.

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

SEE ALSO
bxb(1), dbcollate(1), setdb(1)

AVAILABILITY
This program is included in version 9.3 and later versions of the DB Software Package.