2.5 Conversion Functions

Functions in this section perform various useful conversions: between annotation codes and printable strings, between times in sample intervals and printable strings, between Julian dates and printable strings, and between ADC units and physical units.

annstr, anndesc, and ecgstr

char *annstr(int code)
char *anndesc(int code)
char *ecgstr(int code)

Return:

(char *)

pointer to a printable string that describes the code, or NULL

These functions translate the annotation code specified by their argument into a string (see section Annotation Codes). Illegal or undefined codes are translated by annstr and ecgstr into decimal numerals surrounded by brackets (e.g., ‘[55]’); anndesc returns NULL in such cases. The strings returned by annstr are mnemonics (usually only one character), which may be modified either by setannstr or by the presence of modification labels in an input annotation file (see section setannstr). The strings returned by anndesc are brief descriptive strings, usually those given in the table of annotation codes (see section Annotation Codes). The strings returned by ecgstr are usually the same as those returned by annstr, but they can be modified only by setecgstr, and not by the presence of modification labels as for annstr. The intent is that ecgstr should be used rather than annstr only when it is necessary that a fixed set of mnemonics be used, independent of any modification labels.

Here is a little program that prints a table of the codes, mnemonic strings, and descriptions:

#include <stdio.h>
#include <wfdb/wfdb.h>
#include <wfdb/ecgcodes.h>

main()
{
    int i;

    printf("Code\tMnemonic\tDescription\n");
    for (i = 1; i <= ACMAX; i++) {
        printf("%3d\t%s", i, annstr(i));
        if (anndesc(i) != NULL)
            printf("\t\t%s", anndesc(i));
        printf("\n");
    }
}

(See http://physionet.org/physiotools/wfdb/examples/exannstr.c for a copy of this program.)

ACMAX is defined in ‘<wfdb/ecgcodes.h>’. The range from 1 through ACMAX includes all legal annotation codes; if you run this program, you will find some undefined but legal annotation codes in this range. See section Example 3: An Annotation Printer, for another illustration of the use of annstr. (annstr and anndesc were first introduced in WFDB library version 5.3.)

strann and strecg

int strann(const char *string)
int strecg(const char *string)

Return:

(int)

annotation code

These functions translate the null-terminated ASCII character strings to which their arguments point into annotation codes. Illegal strings are translated into NOTQRS. Input strings for strann and strecg should match those returned by annstr and ecgstr respectively. See section Example 9: A Signal Averager, for an illustration of the use of strann. (strann was first introduced in WFDB library version 5.3.)

setannstr, setanndesc, and setecgstr

int setannstr(int code, const char *string)
int setanndesc(int code, const char *string)
int setecgstr(int code, const char *string)

Return:

0

Success

-1

Failure: illegal code

These functions modify translation tables used by functions that convert between annotation codes and strings. setannstr modifies the table shared by annstr and strann; setanndesc modifies the table used by anndesc; and setecgstr modifies the table shared by ecgstr and strecg. They may be used to redefine strings for defined annotation codes as well as to define strings for undefined annotation codes. For example, setannstr(NORMAL, "\\267") redefines the string for normal beats as a PostScript bullet, ‘•’ (NORMAL is defined in ‘<wfdb/ecgcodes.h>’).

An important difference between setannstr (or setanndesc) and setecgstr is that annopen and wfdbinit insert modification labels in any output annotation files that are created after invoking setannstr or setanndesc; setecgstr does not have this side effect. By using setannstr before annopen, a WFDB application may create annotation files with self-contained code tables, which can be read properly by other WFDB applications without the need to inform them explicitly about non-standard codes. For this scheme to work as intended, all custom code mnemonics and descriptions must be defined before the output annotation files are opened.

By passing a negative value as code to setannstr or setanndesc, the translation for -code can be modified without triggering the generation of a modification label. This feature can be useful for programs that use alternate sets of mnemonics or descriptions for speakers of different languages.

Note that it is possible, though not desirable, to define identical strings for two or more codes; the behavior of strann and strecg in such cases is implementation-dependent. (setannstr and setanndesc were first introduced in WFDB library version 5.3.)

The next three functions convert between “standard time format” strings and times in units of sample intervals. Normally they should be invoked after isigopen, wfdbinit, or sampfreq, any of which will determine the duration of a sample interval and the base time from a header file, or after defining these quantities using setsampfreq and setbasetime. If this is not done, or if these time-conversion functions are used after wfdbquit, they will perform conversions in units of seconds (i.e., the sample interval is taken to be one second in such cases).

[ms]timstr

char *timstr(WFDB_Time t)
char *mstimstr(WFDB_Time t)

Return:

(char *)

pointer to a string that represents the time

These functions convert times or time intervals into null-terminated ASCII strings. If the argument, t, is greater than zero, it is treated as a time interval, and converted directly into HH:MM:SS format by timstr, or to HH:MM:SS.SSS format by mstimstr, with leading zero digits and colons suppressed. If t is zero or negative, it is taken to represent negated elapsed time from the beginning of the record, and it is converted to a time of day using the base time for the record as indicated by the ‘hea’ file or the caller (see section setbasetime); in this case, if the base time is defined, the string will contain all digits even if there are leading zeroes, it will include the date if a base date is defined, and it will be marked as a time of day by being bracketed (e.g., ‘[08:45:00 23/04/1989]’). The result of the conversion is truncated to a multiple of a second by timstr, or to a multiple of a millisecond by mstimstr. Note in each case that the returned pointer addresses static data (shared by timstr and mstimstr), the contents of which are overwritten by subsequent calls. See section Example 3: An Annotation Printer, for an illustration of the use of mstimstr; also see section Example 5: Reading Signal Specifications, for an example of the use of timstr.

strtim

WFDB_Time strtim(const char *string)

Return:

(WFDB_Time) >0

number of sample intervals corresponding to the argument interpreted as a time interval

(WFDB_Time) <0

(negated) elapsed time in sample intervals from the beginning of the record, corresponding to the argument interpreted as a time of day

(WFDB_Time) 0

a legal return if the argument matches the base time; otherwise an error return indicating an incorrectly formatted argument

This function converts an ASCII string in standard time format to a time in units of sample intervals. Examples of standard time format:

2:14.875

2 minutes + 14.875 seconds

[13:6:0]

13:06 (1:06 PM)

[8:0:0 1]

8 AM on the day following the base date

[12:0:0 1/3/1992]

noon on 1 March 1992

143

143 seconds (2 minutes + 23 seconds)

4:02:01

4 hours + 2 minutes + 1 second

s12345

12345 sample intervals

c350.5

counter value 350.5

e

time of the end of the record (if defined)

i

time of the next sample in input signal 0

o

(the letter ‘o’) time of the next sample in output signal 0

If the argument is bracketed (as in the second, third, and fourth examples), it is taken as a time of day, and strtim uses the base time defined by the header file or by the caller (see section setbasetime); in this case, the value returned is zero or negative (and can be converted into elapsed time from the beginning of the record by simply negating it). If the argument is not bracketed, it is taken as a time interval, and converted directly into a positive number of sample intervals. These notations match those used by timstr and mstimstr, which are (approximately) inverse functions of strtim; in fact, for MIT DB and AHA DB records (and any others with sampling frequencies below 1 KHz), strtim(mstimstr(t)) = t, for any t. The ‘s’-format (as in the seventh example above) is provided to allow “conversion” of time intervals already expressed in sample intervals. The similar ‘c’-format converts counter values (see section getcfreq) into sample intervals. The length of the record in sample intervals can be obtained using strtim("e"), which evaluates to zero if this quantity is undefined. The sample number of the next sample to be read or written can be determined using strtim("i") or strtim("o"). If the argument string is incorrectly formatted, strtim returns zero (indistinguishable from a correct input that evokes a zero output); this may be considered a feature. Several of the programs in chapter 6 illustrate the use of strtim (for example, see section Example 7: A General-Purpose FIR Filter).

The next two functions convert between Julian dates and ASCII strings. Julian dates as defined by astronomers begin at noon GMT; these begin at midnight local time.

datstr

char *datstr(WFDB_Date date)

Return:

(char *)

pointer to a string that represents the date

This function converts the Julian date represented by date into an ASCII string in the form DD/MM/YYYY.

strdat

WFDB_Date strdat(const char *string)

Return:

(WFDB_Date)

Julian date corresponding to the argument

This function converts string into a Julian date. The argument should be in the format used by datstr; if string is improperly formatted, strdat returns zero. Note that dates such as ‘15/3/89’ refer to the first century A.D., not the twentieth. For example, the interval in days between the events commemorated by the French and American national holidays is strdat("14/7/1789") – strdat("4/7/1776").

The next four functions convert between analog-to-digital converter (ADC) units and physical units, using as a conversion factor the gain for the specified input signal. The first two (aduphys and physadu) are general-purpose functions that convert absolute levels (i.e., they account for non-zero baseline values); the last two (adumuv and muvadu) are for use with millivolt-dimensioned signals only, and convert potential differences (i.e., adumuv(s, 0) = muvadu(s, 0) = 0 for all s, irrespective of the baseline values specified in the header file). Normally, these functions should be invoked after isigopen or wfdbinit, either of which will determine the gain from the ‘hea’ file. If this is not done, or if the header file indicates that the gain is uncalibrated, or if the specified input signal is not currently open, a gain of WFDB_DEFGAIN (defined in ‘<wfdb/wfdb.h>’) ADC units per millivolt, and a baseline of zero, are assumed. If the physical units (see section Signal Information Structures) are not millivolts, adumuv and muvadu convert to and from thousandths of the defined physical units. Note that adumuv and muvadu deal exclusively with integers, but aduphys returns and physadu accepts double-precision floating point physical values.

aduphys

double aduphys(WFDB_Signal s, WFDB_Sample a)

Return:

(double)

physical value corresponding to a sample value of a ADC units

This function converts the sample value a from ADC units to physical units, based on the gain and baseline for input signal s. (aduphys was first introduced in WFDB library version 6.0.)

physadu

WFDB_Sample physadu(WFDB_Signal s, double v)

Return:

(WFDB_Sample)

sample value, in ADC units, corresponding to v, in physical units

This function converts the value v from physical units to ADC units, based on the gain and baseline for input signal s. (physadu was first introduced in WFDB library version 6.0.)

adumuv

int adumuv(WFDB_Signal s, WFDB_Sample a)

Return:

(int)

number of microvolts corresponding to a ADC units

This function converts the potential difference a from ADC units to microvolts, based on the gain for input signal s.

muvadu

WFDB_Sample muvadu(WFDB_Signal s, int v)

Return:

(int)

number of ADC units corresponding to v microvolts

This function converts the potential difference v from microvolts to ADC units, based on the gain for input signal s.