This is wpg, produced by makeinfo version 4.0b from wpg.tex.

INFO-DIR-SECTION Libraries
START-INFO-DIR-ENTRY
* WFDB library: (wpg).		The Waveform Database library.
END-INFO-DIR-ENTRY


File: wpg,  Node: WFDB_Siginfo structures,  Next: WFDB_Calinfo structures,  Prev: Data Types,  Up: Data Types

Signal Information Structures
=============================

   The SIARRAY argument for `isigopen', `osigopen', `wfdbinit', and
`osigfopen' is a pointer to an array of objects of type `WFDB_Siginfo'.
The first three of these functions fill in the `WFDB_Siginfo' objects
to which SIARRAY points, but the caller must supply initialized
`WFDB_Siginfo' objects to `osigfopen'.  Each object specifies the
attributes of a signal:

`char *fname'
     a pointer to a null-terminated string that names the file in which
     samples of the associated signal are stored.  Input signal files
     are found by prefixing `fname' with each of the components of the
     database path in turn (*note WFDB path::).  `fname' may include
     relative or absolute path specifications if necessary; the use of
     an absolute pathname, combined with an initial null component in
     `WFDB', reduces the time needed to find the signal file to a
     minimum.  If `fname' is `-', it refers to the standard input or
     output.

`char *desc'
     a pointer to a null-terminated string without embedded newlines
     (e.g., `ECG lead V1' or `trans-thoracic impedance').  The length of
     the `desc' string is restricted to a maximum of `WFDB_MAXDSL'
     (defined in `<wfdb/wfdb.h>') characters, not including the null.

`char *units'
     a pointer to a null-terminated string without embedded whitespace.
     The string specifies the physical units of the signal; if NULL,
     the units are assumed to be millivolts.  The length of the `units'
     string is restricted to a maximum of `WFDB_MAXUSL' (defined in
     `<wfdb/wfdb.h>') characters (not including the null).

`WFDB_Gain gain'
     the number of analog-to-digital converter units (adus) per
     physical unit (see previous item) relative to the original analog
     signal; for an ECG, this is roughly equal to the amplitude of a
     normal QRS complex.  If `gain' is zero, no amplitude calibration
     is available; in this case, a `gain' of `WFDB_DEFGAIN' (defined in
     `<wfdb/wfdb.h>') may be assumed.

`WFDB_Sample initval'
     the initial value of the associated signal (i.e., the value of
     sample number 0).

`WFDB_Group group'
     the signal group number.  All signals in a given group are stored
     in the same file.  If there are two or more signals in a group,
     the file is called a "multiplexed signal file".  Group numbers
     begin at 0; arrays of `WFDB_Siginfo' structures are always kept
     ordered with respect to the group number, so that signals
     belonging to the same group are described by consecutive entries
     in SIARRAY.

`int fmt'
     the signal storage format.  The most commonly-used formats are
     format 8 (8-bit first differences), format 16 (16-bit amplitudes),
     and format 212 (pairs of 12-bit amplitudes bit-packed into byte
     triplets).  See `<wfdb/wfdb.h>' for a complete list of supported
     formats.  All signals belonging to the same group must be stored
     in the same format.

`int spf'
     the number of samples per frame.  This is 1, for all except
     oversampled signals in multi-frequency records, for which `spf'
     may be any positive integer.  Note that non-integer values are not
     permitted (thus the frame rate must be chosen such that all
     sampling frequencies used in the record are integer multiples of
     the frame rate).

`int bsize'
     the block size, in bytes.  For signal files that reside on Unix
     character device special files (or their equivalents), the `bsize'
     field indicates how many bytes must be read or written at a time
     (*note Special Files::).  For ordinary disk files, `bsize' is zero.
     All signals belonging to a given group have the same `bsize'.

`int adcres'
     the ADC resolution in bits.  Typical ADCs have resolutions between
     8 and 16 bits inclusive.

`int adczero'
     the ADC output given an input that falls exactly at the center of
     the ADC range (normally 0 VDC).  Bipolar ADCs produce two's
     complement output; for these, `adczero' is usually zero.  For the
     MIT DB, however, an offset binary ADC was used, and `adczero' was
     1024.

`int baseline'
     the value of ADC output that would map to 0 physical units input.
     The value of `adczero' is not synonymous with that of `baseline'
     (the isoelectric or physical zero level of the signal);  the
     `baseline' is a characteristic of the _signal_, while `adczero' is
     a characteristic of the _digitizer_.  The value of `baseline' need
     not necessarily lie within the output range of the ADC;  for
     example, if the `units' are `degrees_Kelvin', and the ADC range is
     200-300 degrees Kelvin, `baseline' corresponds to absolute zero,
     and lies well outside the range of values actually produced by the
     ADC.

`long nsamp'
     the number of samples in the signal.  (Exception: in
     multi-frequency records, `nsamp' is the number of samples divided
     by `spf', see above, i.e., the number of frames.)  All signals in
     a given record must have the same `nsamp'.  If `nsamp' is zero,
     the number of samples is unspecified, and the `cksum' (see the
     next item) is not used; this is useful for specifying signals that
     are obtained from pipes, for which the length may not be known.

`int cksum'
     a 16-bit checksum of all samples.  This field is not usually
     accessed by application programs; `newheader' records checksums
     calculated by `putvec' when it creates a new `hea' file, and
     `getvec' compares checksums that it calculates against `cksum' at
     the end of the record, provided that the entire record was read
     through without skipping samples.

   The number of `WFDB_Siginfo' structures in SIARRAY is given by the
NSIG argument of the functions that open signal files.  Input and
output signal numbers are assigned beginning with 0 in the order in
which the signals are given in SIARRAY.  Note that input signal 0 and
output signal 0 are distinct.  Input signal numbers are supplied to
`aduphys', `physadu', `adumuv', and `muvadu' in their first arguments.
*Note Example 5::, for an illustration of how to read signal
specifications from `WFDB_Siginfo' structures.


File: wpg,  Node: WFDB_Calinfo structures,  Next: WFDB_Anninfo structures,  Prev: WFDB_Siginfo structures,  Up: Data Types

Calibration Information Structures
==================================

   The CAL argument for `getcal' and `putcal' is a pointer to an object
of type `WFDB_Calinfo'.  A `WFDB_Calinfo' object contains information
about signals of a specified type:

`char *sigtype'
     a pointer to a null-terminated string without embedded tabs or
     newlines.  This field describes the type(s) of signals to which
     the calibration specifications apply.  Usually, `sigtype' is an
     exact match to (or a prefix of) the `desc' field of the
     `WFDB_Siginfo' object that describes a matching signal.

`char *units'
     a pointer to a null-terminated string without embedded whitespace.
     This field specifies the physical units of signals to which the
     calibration specifications apply.  Usually, the `units' field of a
     `WFDB_Calinfo' structure must exactly match the `units' field of
     the `WFDB_Siginfo' structure that describes a matching signal.

`double scale'
     the customary plotting scale, in physical units per centimeter.
     WFDB applications that produce graphical output may use `scale' as
     a default.  Except in unusual circumstances, signals of different
     types should be plotted at equal multiples of their respective
     `scale's.

`double low'
`double high'
     values (in physical units) corresponding to the low and high
     levels of a calibration pulse.  If the signal is AC-coupled (see
     below), `low' is zero, and `high' is the pulse amplitude.

`int caltype'
     a small integer that specifies the shape of the calibration pulse
     (see `<wfdb/wfdb.h>' for definitions).  `caltype' is even if
     signals of the corresponding `sigtype' are AC-coupled, and odd if
     they are DC-coupled.

   The calibration list is a memory-resident linked list of
`WFDB_Calinfo' structures.  It is accessible only via `calopen',
`getcal', `putcal', `newcal', and `flushcal'.


File: wpg,  Node: WFDB_Anninfo structures,  Next: WFDB_Annotation structures,  Prev: WFDB_Calinfo structures,  Up: Data Types

Annotator Information Structures
================================

   The AIARRAY argument for `annopen' and `wfdbinit' is a pointer to an
array of objects of type `WFDB_Anninfo'.  Each member of the array
contains information provided to `annopen' and `wfdbinit' about an
annotation file associated with the record:

`char *name'
     the annotator name.  The name `atr' is reserved for a "reference
     annotation file" supplied by the creator of the database record to
     document its contents as accurately and thoroughly as possible.
     You may use other annotator names to identify annotation files
     that you create; unless there are compelling reasons not to do so,
     follow the convention that the annotator name is the name of the
     file's creator (a program or a person).  To avoid confusion, do
     not use `dat', `dataN', `dN', or `hea' (all of which are commonly
     used as parts of WFDB file names) as annotator names.  The special
     name `-' refers to the standard input or output.  Other annotator
     names may contain upper- or lower-case letters, digits, and
     underscores.  Annotation files are normally created in the current
     directory and found in any of the directories in the database path
     (*note WFDB path::).

`int stat'
     the file type/access code.  Usually, `stat' is either `WFDB_READ'
     or `WFDB_WRITE', to specify standard ("MIT format") annotation
     files to be read by `getann' or to be written by `putann'.  Both
     MIT DB and AHA DB annotation files are kept on-line in MIT format.
     The symbols `WFDB_READ' and `WFDB_WRITE' are defined in
     `<wfdb/wfdb.h>'. An AHA-format annotation file can be read by
     `getann' or written by `putann' if the `stat' field is set to
     `WFDB_AHA_READ' or `WFDB_AHA_WRITE' before calling `annopen' or
     `wfdbinit' (*note Example 2::).  Other formats may be supported
     via a similar mechanism; consult `<wfdb/wfdb.h>' for more
     information.

   The number of `WFDB_Anninfo' objects in AIARRAY is given by the NANN
argument of `annopen' and `wfdbinit'.  The annotation-reading function,
`getann', knows the annotators by number only; `annopen' and `wfdbinit'
assign input annotator numbers beginning with 0 in the order in which
they are given in the array of `WFDB_Anninfo' objects.  Output
annotator numbers used by `putann' also start at 0; note that input
annotator 0 and output annotator 0 are distinct.  Annotator numbers are
supplied to `getann' and `putann' in their first arguments.  *Note
annopen::, for an example of how to set the contents of an array of
`WFDB_Anninfo' objects.


File: wpg,  Node: WFDB_Annotation structures,  Prev: WFDB_Anninfo structures,  Up: Data Types

Annotation Structures
=====================

   The ANNOT argument of `getann' and `putann' is an object of type
`WFDB_Annotation' containing these fields:

`long time'
     time of the annotation, in samples from the beginning of the
     record.  The times of beat annotations in the `atr' files for the
     MIT DB generally coincide with the R-wave peak in signal 0; for
     the AHA DB, they generally coincide with the PQ-junction.

`char anntyp'
     annotation code; an integer between 1 and `ACMAX'.  *Note
     Annotation Codes::, for a list of legal annotation codes.  `ACMAX'
     is defined in `<wfdb/ecgcodes.h>'.

`signed char subtyp'
`signed char chan'
`signed char num'
     numbers between -128 and 127.  In MIT DB `atr' files, the `subtyp'
     field is used with noise and artifact annotations to indicate
     which signals are affected (*note Annotation Codes::).  The `chan'
     field is intended to indicate the signal to which the annotation
     is attached.  More than one annotation may be written with the
     same `time' if the `chan' fields are distinct and in ascending
     order.  The semantics of the `chan' field are unspecified,
     however; users may assign any desired meaning, which need not have
     anything to do with signal numbers.  In user-created annotation
     files, these fields can be used to store arbitrary small integers.
     The `subtyp' field requires no space in a standard annotation file
     unless it is non-zero; the `chan' and `num' fields require no
     space unless they have changed since the previous annotation.

`char *aux'
     a free text string.  The first byte is interpreted as an `unsigned
     char' that specifies the number of bytes that follow (up to 255).
     In MIT DB `atr' files, the `aux' field is used with rhythm change
     annotations to specify the new rhythm, and with comment
     annotations to store the text of the comment The string can
     contain arbitrary binary data, including embedded nulls.  It is
     unwise to store anything but ASCII strings, however, if the
     annotation file may be transported to a system with a different
     architecture (e.g., on which multiple-byte quantities may have
     different sizes or byte layouts).  The `aux' field requires no
     space in a standard annotation file if it is `NULL'.  Note that
     conversion of annotation files to other formats may entail
     truncation or loss of the `aux' string.  Note also that the `aux'
     pointer returned by `getann' points to a small static buffer
     (separately allocated for each input annotator beginning with WFDB
     library version 9.4) that may be overwritten by subsequent calls.

   *Note Example 3::, for a short program that examines the contents of
a `WFDB_Annotation'.


File: wpg,  Node: Annotation Codes,  Next: Database Files,  Prev: Data Types,  Up: Top

Annotation Codes
****************

* Menu:

* Mapping macros::		Macros for mapping annotation codes.

   Application programs that deal with annotations should include the
line

     #include <wfdb/ecgcodes.h>

which provides the symbolic definitions of annotation codes given in the
first column of the table below.  (The second column of the table shows
the strings returned by `annstr' and `ecgstr'.)

     _Beat annotation codes:_
     NORMAL   N   Normal beat
     LBBB     L   Left bundle branch block beat
     RBBB     R   Right bundle branch block beat
     BBB      B   Bundle branch block beat (unspecified)
     APC      A   Atrial premature beat
     ABERR    a   Aberrated atrial premature beat
     NPC      J   Nodal (junctional) premature beat
     SVPB     S   Supraventricular premature or ectopic beat (atrial or nodal)
     PVC      V   Premature ventricular contraction
     RONT     r   R-on-T premature ventricular contraction
     FUSION   F   Fusion of ventricular and normal beat
     AESC     e   Atrial escape beat
     NESC     j   Nodal (junctional) escape beat
     SVESC    n   Supraventricular escape beat (atrial or nodal) [1]
     VESC     E   Ventricular escape beat
     PACE     /   Paced beat
     PFUS     f   Fusion of paced and normal beat
     UNKNOWN  Q   Unclassifiable beat
     LEARN    ?   Beat not classified during learning
     
     _Non-beat annotation codes:_
     VFON     [   Start of ventricular flutter/fibrillation
     FLWAV    !   Ventricular flutter wave
     VFOFF    ]   End of ventricular flutter/fibrillation
     NAPC     x   Non-conducted P-wave (blocked APC) [4]
     WFON     (   Waveform onset [4]
     WFOFF    )   Waveform end [4]
     PWAVE    p   Peak of P-wave [4]
     TWAVE    t   Peak of T-wave [4]
     UWAVE    u   Peak of U-wave [4]
     PQ       `   PQ junction
     JPT      '   J-point
     PACESP   ^   (Non-captured) pacemaker artifact
     ARFCT    |   Isolated QRS-like artifact [2]
     NOISE    ~   Change in signal quality [2]
     RHYTHM   +   Rhythm change [3]
     STCH     s   ST segment change [1,3]
     TCH      T   T-wave change [1,3,4]
     SYSTOLE  *   Systole [1]
     DIASTOLE D   Diastole [1]
     MEASURE  =   Measurement annotation [1,3]
     NOTE     "   Comment annotation [3]
     LINK     @   Link to external data [5]

*Notes:*
  1. Codes `SVESC', `STCH', and `TCH' were first introduced in WFDB
     library version 4.0.  Codes `SYSTOLE', `DIASTOLE', and `MEASURE'
     were first introduced in WFDB library version 7.0.

  2. In MIT and ESC DB `atr' files, each non-zero bit in the `subtyp'
     field indicates that the corresponding signal contains noise (the
     least significant bit corresponds to signal 0).

  3. The `aux' field contains an ASCII string (with prefixed byte count)
     describing the rhythm, ST segment, T-wave change, measurement, or
     the nature of the comment.  By convention, the character that
     follows the byte count in the `aux' field of a `RHYTHM' annotation
     is `('.  See the `MIT-BIH Arrhythmia Database Directory' for a
     list of rhythm annotation strings.

  4. Codes `WFON', `WFOFF', `PWAVE', `TWAVE', and `UWAVE' were first
     introduced in DB library version 8.3.  The `p' mnemonic now
     assigned to `PWAVE' was formerly assigned to `NAPC', and the `t'
     mnemonic now assigned to `TWAVE' was formerly assigned to `TCH'.
     The obsolete codes `PQ' (designating the PQ junction) and `JPT'
     (designating the J-point) are still defined in
     `<wfdb/ecgcodes.h>', but are identical to `WFON' and `WFOFF'
     respectively.

  5. The `LINK' code was first introduced in WFDB library version 9.6.
     The `aux' field of a `LINK' annotation contains a URL (a uniform
     resource locator, in the form `http://machine.name/some/data',
     suitable for passing to a Web browser such as Netscape or Mosaic).
     `LINK' annotations may be used to associate extended text,
     images, or other data with an annotation file.  If the `aux' field
     contains any whitespace, text following the first whitespace is
     taken as descriptive text to be displayed by a WFDB browser such
     as `WAVE'.


   The annotation codes in the table above are the predefined values of
the `anntyp' field in a `WFDB_Annotation'.  Other values in the range
of 1 to `ACMAX' (defined in `<wfdb/ecgcodes.h>') are legal but do not
have preassigned meanings.  The constant `NOTQRS', also defined in
`<wfdb/ecgcodes.h>', is not a legal value for `anntyp', but is a
possible output of the macros discussed below.


File: wpg,  Node: Mapping macros,  Prev: Annotation Codes,  Up: Annotation Codes

Macros for Mapping Annotation Codes
===================================

   Application programs that use the macros described in this section
should include the line
     #include <wfdb/ecgmap.h>

which will make their definitions, and those in `<wfdb/ecgcodes.h>',
available.

`isann(C)'
     true (1) if C is a legal annotation code, false (0) otherwise

`isqrs(C)'
     true (1) if C denotes a QRS complex, false (0) otherwise

`map1(C)'
     maps C into one of the set {`NOTQRS', `NORMAL', `PVC', `FUSION',
     `LEARN'}

`map2(C)'
     maps C into one of the set {`NOTQRS', `NORMAL', `SVPB', `PVC',
     `FUSION', `LEARN'}

`annpos(C)'
     maps C into one of the set {`APUNDEF', `APSTD', `APHIGH', `APLOW',
     `APATT', `APAHIGH', `APALOW'} (see `<wfdb/ecgmap.h>' for
     definitions of these symbols;  this macro was first introduced in
     WFDB library version 6.0)

   If you define your own annotation codes, you may wish to modify the
tables used by the macros above.  The file `<wfdb/ecgmap.h>' also
defines `setisqrs(C, X)', `setmap1(C, X)', `setmap2(C, X)', and
`setannpos(C, X)' for this purpose.  In each case, X is the value to be
returned when the corresponding mapping macro is invoked with an
argument of C.  (These macros were first introduced in WFDB library
version 6.0.)

   The macros below convert between AHA and MIT annotation codes;  they
are also defined in `<wfdb/ecgmap.h>'.

`ammap(A)'
     maps A (an AHA annotation code) into an MIT annotation code (one
     of the set {`NORMAL', `PVC', `FUSION', `RONT', `VESC', `PACE',
     `UNKNOWN', `VFON', `VFOFF', `NOISE', `NOTE'}), or `NOTQRS'

`mamap(C, S)'
     maps C (an MIT annotation code) into an AHA annotation code (one
     of the set {`N', `V', `F', `R', `E', `P', `Q', `[', `]', `U',
     `O'}); S is the MIT annotation `subtyp' (significant only if C is
     `NOISE')


File: wpg,  Node: Database Files,  Next: Examples,  Prev: Annotation Codes,  Up: Top

Database Files
**************

   The WFDB library has been constructed to provide a standard interface
between the database files and application programs.  Alternate means of
access to database files is strongly discouraged, since file formats may
change.  Database files are located in the directories specified by
`WFDB' (*note WFDB path::).

   Recall that a WFDB record is not a file; rather, it is an extensible
_collection_ of database files (*note Records: Concepts 1.).  Thus, for
example, record 100 of the MIT-BIH Arrhythmia Database consists of the
files named `100.hea', `100.dat', and `100.atr' in the `mitdb'
directory of the MIT-BIH Arrhythmia Database CD-ROM (or in PhysioBank,
within `http://www.physionet.org/physiobank/database/mitdb/'), together
with any additional files in other directories that you may have
associated with record 100 (such as your own annotation file).  All
files associated with a given record include the record name as the
first part of the file name.  No explicit action (other than choosing
the file name, and locating the file in the WFDB path) is needed in
order to associate a new file with an existing WFDB record.

   To find the location of a database file easily, you can use
`wfdbwhich', an application included with the WFDB Software Package.
Type `wfdbwhich' for brief instructions on its use, or see the `WFDB
Applications Guide'.

File Types
==========

   There are four types of files supported by the WFDB library:

* Menu:

* Header Files::		contain signal file names and attributes.
* Signal Files::		contain signals.
* Annotation Files::		contain annotations.
* Calibration Files::		contain signal calibration specifications.

The other topics in this section deal with special types of database access:

* AHA Format Files::		not used for on-line WFDB records.
* Standard I/O::		pipes and I/O redirection for WFDB files.
* Multiplexed Signal Files::	signal groups.
* Multi-Frequency Records::     signals sampled at different frequencies within
                                 within a given record.
* Multi-Segment Records::       concatenated records.
* Multiple Record Access::	how to have more than one record open.
* Special Files::		signal I/O using block and character devices.
* Piped and Local Records::	records for use with user-created signals.
* NETFILES::			input directly from web and FTP servers.
* Annotation Order::            the canonical order for annotations:
                                 how and why to break the rules, and how
                                 to deal with the consequences of doing so.


File: wpg,  Node: Header Files,  Next: Signal Files,  Prev: Database Files,  Up: Database Files

Header Files
------------

   "Header files" have names of the form `RECORD.hea', where RECORD is
the record name.  (MIT DB records are named 100-124 and 200-234 with
some numbers missing.  AHA DB records are named 1001-1010, 2001-2010,
3001-3010, 4001-4010, 5001-5010, 6001-6010, 7001-7010, and 8001-8010.
ESC DB records are named e0103-e1304, with many numbers missing.)
Header files are text files, with lines terminated by ASCII
carriage-return/line-feed pairs, created by `newheader', `setheader',
or `setmsheader', from which `isigopen', `osigopen', and `wfdbinit'
read the names of the signal files and their attributes as given in the
array of `WFDB_Siginfo' objects; `sampfreq' also reads a header file to
determine the sampling frequency used for a record.


File: wpg,  Node: Signal Files,  Next: Annotation Files,  Prev: Header Files,  Up: Database Files

Signal Files
------------

   "Signal files" usually have names of the form `RECORD.dat'.  (The
`.dat' suffix is conventional, but not required; any file name
acceptable to the operating system is permissible.)  Signal files are
binary, and usually contain either 16-bit amplitudes (format 16), pairs
of 12-bit amplitudes bit-packed into byte triplets (format 212), or
8-bit first differences (format 8).  (See `<wfdb/wfdb.h>' for
information about other formats that are supported.)  The functions
that read and write signal files perform appropriate transformations so
that the samples visible to the application program are always
amplitudes of type `int' (at least 16 bits), regardless of the signal
file format.


File: wpg,  Node: Annotation Files,  Next: Calibration Files,  Prev: Signal Files,  Up: Database Files

Annotation Files
----------------

   "Annotation files" have names of the form `RECORD.ANNOTATOR'.  Those
named `RECORD.atr' are reference annotation files (assumed to be
correct).  Annotation files are binary, and contain records of variable
length that average slightly over 16 bits per annotation.


File: wpg,  Node: Calibration Files,  Next: AHA Format Files,  Prev: Annotation Files,  Up: Database Files

Calibration Files
-----------------

   Unlike header, signal, and annotation files, "calibration files" are
not associated with individual records.  A calibration file is needed
only if you have records containing signals other than ECGs;  in this
case, it is likely that a single calibration file will be adequate for
use with all of your records.  Calibration files are text files, with
lines terminated by ASCII carriage-return/line-feed pairs, created by
`newcal', from which `calopen' reads the calibration list (*note
WFDB_Calinfo structures::).  The WFDB Software Package includes a
standard calibration file, `wfdbcal', in the `data' directory.


File: wpg,  Node: AHA Format Files,  Next: Standard I/O,  Prev: Calibration Files,  Up: Database Files

AHA Format Files
----------------

   The "AHA Format" was defined in 1980 for storage of database records
on 9-track digital tape.  Signal files in AHA format are in format 16,
with two signals multiplexed into one file (*note Multiplexed Signal
Files::), and may be read and written using `getvec' and `putvec'.
AHA-format annotation files are binary, and contain fixed-length
(16-byte) annotation records.  An annotation file in AHA format may be
read or written using `getann' or `putann', if the `stat' field of the
`WFDB_Anninfo' object is set to `WFDB_AHA_READ' or `WFDB_AHA_WRITE'
before opening the file.  `annopen' recognizes the format of input
annotation files automatically and prints a warning if the format does
not match what was expected on the basis of `stat'.  AHA format
annotation files may be converted to standard format without loss of
information, and doing so reduces the storage requirement by a factor
of eight.

   Yet another format has been used more recently for distribution of
AHA DB files on floppy diskettes and CD-ROMs.  This format is
compatible with neither the original AHA format nor with any of the
formats supported directly by the WFDB library.  Programs `a2m' and
`ad2m', supplied with the WFDB Software Package, can convert files in
this format (as well as those in the original AHA format) to the
standard formats.


File: wpg,  Node: Standard I/O,  Next: Multiplexed Signal Files,  Prev: AHA Format Files,  Up: Database Files

Using Standard I/O for Database Files
=====================================

   If `-' is supplied as a record name to any of the functions that
read or write header files, the `hea' file is taken to be the standard
input or output, as appropriate.  If the name of a signal file is
specified in the `hea' file (or in the array of `WFDB_Siginfo' objects
passed to `osigfopen') as `-', the standard input (output) is used by
`getvec' (`putvec').  If the name of an annotator is given in the array
of `WFDB_Anninfo' objects as `-', the standard input (output) is used
by `getann' (`putann').  If the name of a calibration file is given as
`-', the standard input (output) is used by `calopen' (`newcal').

   Under MS-DOS, these features may not always be usable, since the
standard input and output are usually opened in "text" mode (which is
unsuitable for binary database files).

   Although the WFDB library does not forbid the use of the standard
input or output for more than one function (e.g., as both a signal file
and an annotation file), such use is in general a gross error that is
likely to lead to unintended results.


File: wpg,  Node: Multiplexed Signal Files,  Next: Multi-Frequency Records,  Prev: Standard I/O,  Up: Database Files

Multiplexed Signal Files
========================

   Multiplexed signal files may be identified by examining the `group'
fields of the array of `WFDB_Siginfo' objects returned by `isigopen' or
`wfdbinit'.  Signals belonging to the same group are multiplexed
together in the same file.  If all signals in a given signal file have
been sampled at the same frequency, and there are N signals in the
file, then each group of N successive samples in that file contains a
sample from each signal, always in the same order (but *note
Multi-Frequency Records::).

   Multiplexed signal files can be useful if the storage device is
sequential-access only (e.g., 9-track tape), if the storage device has
lengthy seek times (e.g., optical disk), if many signals must be
recorded and Unix's per-process limit on open files would otherwise be
exceeded, or if very high speed is required while the file is being
created (because of sampling constraints).  CD-ROM signal files, and
those available from PhysioNet, are multiplexed unless the record
contains only one signal.


File: wpg,  Node: Multi-Frequency Records,  Next: Multi-Segment Records,  Prev: Multiplexed Signal Files,  Up: Database Files

Multi-Frequency Records
=======================

   When signals of different types are recorded simultaneously and for
lengthy periods, it may be appropriate to choose different sampling
frequencies in order to reduce the storage requirements for signals of
limited bandwidth.  The support for multi-frequency records provided in
WFDB library version 9.0 (and later versions) allows application
programs to read and write records containing signals digitized at
multiple sampling frequencies.  In a multi-frequency record, a "frame"
of samples contains one _or more_ samples from each signal.  The "frame
rate" (base sampling frequency) of the record, as recorded in the
header file and as normally returned by `sampfreq', is defined as the
number of frames per second.  Signals sampled at multiples of the frame
rate are referred to as "oversampled signals".  For each signal, a
frequency multiplier specifies how many samples are included in each
frame.  The frequency multiplier (1 by default) is an integer, encoded
within the format field in the header file, and specified in the `spf'
field of the `WFDB_Siginfo' structure for the signal.

   A frame can be read as it was written (*note getframe::) by an
application that has been written to make use of multi-frequency
records.  Applications that are not "multi-frequency aware" can still
read signals using the standard `getvec' interface, which returns (as
always) one sample per signal on each invocation.  By default, `getvec'
reads multi-frequency records in "low-resolution" mode.  In this mode,
each oversampled signal is resampled at the frame rate by averaging all
of its samples in each frame.

   The function `setgvmode' can be used to select "high-resolution"
mode, in which `getvec' replicates samples of signals digitized at less
than the maximum sampling frequency (i.e., using zero-order
interpolation) so that each sample of an oversampled signal appears in
at least one sample vector returned by `getvec'.  In this mode,
`sampfreq' returns the number of samples per signal returned by
`getvec' per second of the record.  Furthermore (when using WFDB
library version 9.6 and later versions), all time quantities passed to
and from the WFDB library functions are understood to be in units of
these shorter sampling intervals; thus, for example, `getann' converts
times in frame numbers (as recorded in annotation files) into times in
sample numbers before filling in the caller's annotation structure, and
`putann' converts times in sample numbers into times in frame numbers
before writing annotations into annotation files.  This permits
applications that are not "multi-frequency aware" to read
multi-frequency records with the highest possible resolution.

   The operating mode used by `getvec', if not specified by an explicit
call to `setgvmode', is determined by the value of the environment
variable `WFDBGVMODE' if it is set, and otherwise by the value of
`DEFWFDBGVMODE' in `wfdblib.h' at the time the library was compiled..
In either case, a value of 0 selects low-resolution mode, and any other
value selects high-resolution mode.


File: wpg,  Node: Multi-Segment Records,  Next: Multiple Record Access,  Prev: Multi-Frequency Records,  Up: Database Files

Multi-Segment Records
=====================

   A multi-segment record consists of two or more concatenated segments.
Each segment is an ordinary WFDB record, with its own header file and
signal file(s).  In any given multi-segment record, all signals must
appear in the same order within each segment (signals may not be
omitted), and the sampling frequency of any given signal must be the
same in each segment.  Segments of multi-segment records must be
ordinary records (it is not permitted to nest one multi-segment record
within another, for example), and the length of each segment must be
specified (the WFDB library does not impose this requirement on ordinary
records that are not part of a multi-segment record).  There are no
other restrictions on segments; specifically, it is permitted to mix
segments with different storage formats, and for any segment to appear
more than once.  A special header file (created either manually or by
using `setmsheader') specifies the record name for each segment in a
multi-segment record.  Once this special header exists, the
multi-segment record can be read by any WFDB application.  Note that
only the signal files of the segments are "linked" by the multi-segment
record's header; annotation files associated with the individual
segments are _not_ readable as part of the multi-segment record
(although an annotation file associated directly with the multi-segment
record can be created and read just as for an ordinary record).  From
the point of view of a WFDB application, reading a multi-segment record
is exactly like reading an ordinary record; specifically, `isigsettime'
works as expected, permitting jumps forward and backward between as
well as within segments.  Version 9.1 of the WFDB library is the first
to support reading and writing multi-segment records.


File: wpg,  Node: Multiple Record Access,  Next: Special Files,  Prev: Multi-Segment Records,  Up: Database Files

Simultaneous Access to Multiple Records
=======================================

   Selection functions that accept RECORD arguments (`annopen',
`isigopen', `osigopen', and `wfdbinit') normally close any active
database files of the types with which each deals before proceeding.
The argument `+'RECORD is synonymous with RECORD, but has the effect of
causing these functions to leave any active files open.  (For
convenience, the other functions that accept RECORD arguments --
`sampfreq', `newheader', and `setheader' -- also treat RECORD and
`+'RECORD as synonymous, but without any noticeable effect.)  The
restrictions on the total numbers of signals and annotation files still
apply.

   If the sampling frequencies or lengths of the records do not match,
a warning message will be produced (unless `wfdbquiet' was invoked).
The time-conversion functions (*note timstr and strtim::) will continue
to use the sampling frequency and base time defined for the first
record that was opened, unless these attributes are reset by
`sampfreq', `setsampfreq', or `setbasetime'.

   Function `calopen' uses the `+' convention for calibration file
names.  Although it normally creates the calibration list from scratch
each time it is called, it retains the current calibration list if the
calibration file name is prefixed by `+'.


File: wpg,  Node: Special Files,  Next: Piped and Local Records,  Prev: Multiple Record Access,  Up: Database Files

Signals That Are Not Stored in Disk Files
=========================================

   The `fname' component of a `WFDB_Siginfo' object can be any string
acceptable as a file name to your operating system.  Under Unix, for
example, signals can be read from (or written to) `special' files such
as `/dev/rmt0' (the raw tape drive).  If I/O must be performed in
fixed-size blocks (such as for Unix character devices), the `bsize'
component of the `WFDB_Siginfo' object must contain the appropriate
block size in bytes.  In such cases, the WFDB library must obtain
(using `malloc' (see `K&R', page 167) an amount of memory equal to the
size of one block when the signal file is first opened.  For large
programs running on 16-bit machines, this can cause problems if signal
files with large block sizes are read.  (In such cases, `isigopen' or
`osigopen' will not open the signal file if there is not enough memory
to allocate a buffer.)  Under Unix, if this problem occurs, use the
"piped records" (*note Piped and Local Records::) instead.  The usual
method is to read or write the signal file using a utility such as
Unix's `dd' and to pipe the data to or from the application program.
Although this approach is flexible, there are a few drawbacks:

  1. While reading piped input, the standard input cannot be used for
     other purposes by the application program.  Interactive programs
     can avoid problems by opening `/dev/tty' for I/O, however.

  2. Programs that use `isigsettime' or `isgsettime' cannot perform
     backward skips on piped input, and forward skips can be quite slow.

  3. Additional system resources (computation time, process slots, and
     memory) are needed when using pipes, in comparison with the usual
     method of operation.

   Several special-purpose header files allow application programs to
read data directly from 9-track tape.  When the WFDB Software Package
is installed, these files are copied into the `tape' subdirectory of
the system-wide database directory.  The record names associated with
most of these header files (`tape/512', `tape/1024', `tape/4096',
`tape/10240') specify the block size in bytes.  These use 16-bit
format, 250 Hz samples, 12 bit ADC with zero ADC offset, two signals
multiplexed into one, and data to be read from `/dev/rmt0'.  Record
`tape/6144d' uses 8-bit difference format, 6144 bytes/block, and is
otherwise similar to the others.  Records `tape/ahatape' and
`tape/mittape' can be used to read or write an AHA-format signal file
on a 9-track tape that has been positioned to the beginning of the
correct file; the signal file for these is `/dev/nrmt0' (the
non-rewinding raw tape drive).  If the tape density is encoded into the
tape drive name on your system, additional header files may be needed.


File: wpg,  Node: Piped and Local Records,  Next: NETFILES,  Prev: Special Files,  Up: Database Files

Piped and Local Records
=======================

   "Piped record" header files allow application programs to read
signals from the standard input, or write them to the standard output.
Record `8' specifies 8-bit format, a 10-bit ADC, zero ADC offset, and
two signals sampled at 250 Hz, both of which are to be acquired from
the standard input, or written to the standard output.  Record `16'
specifies 16-bit format and a 12-bit ADC, and is otherwise identical to
record `8'.  ADCs from several manufacturers can produce output in the
format specified by record `16'; thus such output can be piped directly
into an application program using record `16'.  Signal files in AHA
format also match these specifications.  Piped records for reading or
writing other numbers of signals are provided in the `pipe'
subdirectory of the system-wide database directory; they are named
`pipe/8xN' and `pipe/16xN', where N is the number of signals (N = 1, 2,
..., 16; piped record header files can be created with larger numbers
of signals (use the existing files as a model).

   Application programs may also read or write signal files in the
current directory using "local record" header files.  Record `16l'
("one-six-ell") specifies up to sixteen format 16 files, and record
`8l' ("eight-ell") specifies up to sixteen format 8 files, named
`data0', `data1', `data2', ..., `dataN' in the current directory.  When
opened using `isigopen' or `wfdbinit', these signal files will be
readable by `getvec' as signals 0, 1, 2, ... 16 respectively.  These
files should be created by the user, with the use of `putvec'.  It is
necessary to create only as many signal files as will be used; if, for
example, only one signal is needed, only `data0' need be created.


File: wpg,  Node: NETFILES,  Next: Annotation Order,  Prev: Piped and Local Records,  Up: Database Files

NETFILES
========

   If the symbol `WFDB_NETFILES' is defined at the time the WFDB
library is compiled, then input files located on remote web (HTTP) and
FTP servers can be read directly.  This capability is implemented using
the World Wide Web Consortium's `libwww' library (which is available on
many of the platforms supported by the WFDB library).  NETFILES
support, if available, is transparent to WFDB applications.  To make
use of this feature, simply link to the NETFILES-enabled WFDB library
(the necessary `libwww' functions will be loaded automatically), and
incorporate one or more URL prefixes in the WFDB path.

   In current versions of the WFDB library, the default WFDB path
(defined in the WFDB library source file `wfdblib.h', and used as the
WFDB path if the WFDB environment variable is undefined) is `.
/usr/database http://www.physionet.org/physiobank/database'.  (The
second component, after the `.' that specifies the current directory,
may vary, depending on your platform and the choices made during
installation.)  The third component is a URL prefix pointing to
PhysioBank, an on-line archive for a wide variety of standard databases
of physiologic signals.  For example, the MIT-BIH Polysomnographic
Database is kept in
`http://www.physionet.org/physiobank/database/slpdb', so it is possible
to read record `slp37' of that database directly from PhysioBank by
passing `slpdb/slp37' as the RECORD argument to `wfdbinit' (or
`isigopen', `annopen', etc.).

   Current implementations of `libwww' permit input from `http://' URLs
in much the same way that local files are read, provided that the
remote web server supports HTTP 1.1 range requests (most, including
PhysioNet's, do).  This means that it is not necessary to download an
entire file in order to examine part of it, and you may notice little
or no speed difference between local file and network file input for
many applications.  If the remote server does not support range
requests, however, or if input is from an `ftp://' URL, the current
implementation downloads the entire file to memory, so you may notice a
significant startup delay if the file is long and your network
connection is slow, or if the file does not fit into physical memory.

   Currently, NETFILES support is limited to input files; as always,
any output files created by the WFDB library are written into the
current directory, unless the record name contains local path
information.

   NETFILES support was introduced in WFDB library version 10.0.1.


File: wpg,  Node: Annotation Order,  Prev: NETFILES,  Up: Database Files

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.  Early versions of the WFDB library (before version 6.2)
defined canonical order as time order.  More recent versions of the
WFDB library define canonical order as `time' and `chan' order (thus
annotations are arranged first in `time' order, and any simultaneous
annotations are arranged according to the value of their `chan' fields,
from smallest to largest).

   The combination of the `time' 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', `num',
or `aux' fields of a previously-written annotation simply by writing
another annotation to the same location (i.e, with the same `time' 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' 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'.


File: wpg,  Node: Examples,  Next: Exercises,  Prev: Database Files,  Up: Top

Programming Examples
********************

   The programs in this chapter are useful as models for a variety of
applications that use the WFDB library.  The line numbers are for
reference only; they are not part of the programs.  Any of these
examples can be compiled (under Unix) using a command of the form
     cc FILE.C -lwfdb

or, if the WFDB library or its `*.h' files are not in the standard
locations:
     cc `wfdb-config --cflags` FILE.C `wfdb-config --libs`

where FILE.C is the name of the file containing the source; *note Using
the WFDB Library: Usage., for further information.  The sources for
these examples are included in the WFDB Software Package, within the
`examples' directory.

* Menu:

* Example 1::			An annotation filter.
* Example 2::			An MIT-to-AHA format annotation translator.
* Example 3::			An annotation printer.
* Example 4::			Generating an R-R interval histogram.
* Example 5::			A program that prints signal specifications.
* Example 6::			A differentiator.
* Example 7::			A general-purpose FIR filter.
* Example 8::			Creating a new WFDB record.
* Example 9::			A signal averager.
* Example 10::			A QRS detector.

