5.10 Annotation Order

WFDB applications may generally assume (and most of them do assume) that all annotations in any given annotation file are in canonical order. Successful use of iannsettime requires that this assumption be correct. The earliest versions of the WFDB library (before version 6.1) defined canonical order as time order. Versions 6.1 through 10.4.11 define canonical order as time and chan order, and versions 10.4.12 and later also use num for ordering (thus annotations are arranged first in time order, and any simultaneous annotations are arranged according to the value of their num fields, from smallest to largest, and those with identical num fields are similarly arranged in chan order).

The combination of the time, num, and chan fields of an annotation defines a unique location in a virtual array of annotations which an annotation file represents. No two annotations may occupy the same location in this virtual array. This restriction was enforced by versions of the WFDB library earlier than version 9.7. In these versions of the WFDB library, putann required that annotations be written in canonical order, and refused to write any out-of-order annotations supplied to it.

Current versions of the WFDB library do not impose this requirement. In version 9.7 and later versions, putann accepts and records out-of-order annotations and multiple annotations that occupy the same location. If any such annotations have been written, the completed annotation file is rewritten in canonical order by wfdbquit or oannclose. This is accomplished by running ‘sortann’ (see the WFDB Applications Guide) as a separate process using the ANSI C system function. If this function is not available, or if ‘sortann’ cannot be run, wfdbquit (or oannclose) emits a warning message describing how to post-process the annotations to put them into canonical order.

Although it is possible using current versions of the WFDB library to write two or more annotations to the same location, only the last annotation written to any given location is retained in the canonically-ordered annotation file. Thus that an application that generates an annotation file can change the anntyp, subtyp, or aux fields of a previously-written annotation simply by writing another annotation to the same location (i.e, with the same time, num, and chan fields). As a special case, an application may delete a previously-written annotation by writing a NOTQRS annotation to the same location. To move an annotation to a different location (i.e., to change its time, num, or chan fields), it is necessary to delete it from the original location, and then to insert it at the desired location, using two separate invocations of putann.

In unusual circumstances, an unsorted annotation file may be useful (for example, as an aid for debugging the application that produced it; ‘rdann’ can be used to list all of the annotations in such a file, in the order in which they were written). In some environments, the use of the ANSI C system function may be a security problem, and you may wish to avoid automatic sorting of annotations for this reason. Set the environment variable WFDBANNSORT to 0 at run time, or define the symbol DEFWFDBANNSORT as 0 when compiling the WFDB library, if you wish to suppress automatic annotation sorting by wfdbquit and oannclose.