2.3 Reading and Writing Signals and Annotations

getvec

int getvec(WFDB_Sample *vector)

Return:

>0

Success; the returned value is the number of input signals (the number of valid entries in vector)

-1

End of data (contents of vector not valid)

-3

Failure: unexpected physical end of file

-4

Failure: checksum error (detected only at end of file)

This function reads a sample from each input signal. The caller should allocate storage for an array of WFDB_Samples (integers) and pass a pointer to this array to getvec. (The length of the array must be no less than the number of input signals, as obtained from isigopen or wfdbinit.) On return, vector[i] contains the next sample from signal i. For example, this modified version of the example from chapter 1 reads and prints the first ten samples of each available input signal:

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

main()
{
    int i, j, nsig;
    WFDB_Sample *v;
    WFDB_Siginfo *s;

    nsig = isigopen("100s", NULL, 0);
    if (nsig < 1)
        exit(1);
    s = (WFDB_Siginfo *)malloc(nsig * sizeof(WFDB_Siginfo));
    if (isigopen("100s", s, nsig) != nsig)
        exit(1);
    v = (WFDB_Sample *)malloc(nsig * sizeof(WFDB_Sample));
    for (i = 0; i < 10; i++) {
        if (getvec(v) < 0)
            break;
        for (j = 0; j < nsig; j++)
            printf("%8d", v[j]);
        printf("\n");
    }
    exit(0);
}

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

Notice how the value returned by the first invocation of isigopen is used to determine how many input signals there are. Several of the example programs in chapter 6 illustrate the use of getvec; for example, see section Example 6: A Differentiator.

If setifreq has been used to modify the input sampling rate, getvec resamples the input signals at the desired rate, using linear interpolation between the pair of samples nearest in time to that of the sample to be returned. The results will generally be satisfactory, provided that the original signals do not contain frequencies near or above the Nyquist limit (half of the desired sampling frequency). If this is a concern, you may wish to low-pass filter the input signals using, for example, ‘fir’ (see the WFDB Applications Guide) before resampling them. If you use setifreq to increase the sampling frequency by a large factor, you may wish to filter the resampled signals within your application to remove harmonics of the original sampling frequency introduced by resampling.

getframe

int getframe(WFDB_Sample *vector)

Return:

>0

Success; the returned value is the number of input signals

-1

End of data (contents of vector not valid)

-3

Failure: unexpected physical end of file

-4

Failure: checksum error (detected only at end of file)

This function reads a vector of samples, including at least one sample from each open input signal. If all signals are sampled at the same frequency, only one sample is read from each signal. Otherwise, signals sampled at multiples of the frame frequency are represented by two or more consecutive elements of the returned vector. For example, if the frame frequency is 125 Hz, signal 0 is sampled at 500 Hz, and the remaining 3 signals are sampled at 125 Hz each, then the returned vector has 7 valid components: the first 4 are samples of signal 0, and the remaining 3 are samples of signals 1, 2, and 3. The caller should allocate storage for an array of WFDB_Samples (integers) and pass a pointer to this array to getframe. The length of vector must be determined by summing the values of the spf (samples per frame) fields in the WFDB_Siginfo structures associated with the input signals (see section isigopen).

putvec

int putvec(const WFDB_Sample *vector)

Return:

>0

Success: the returned value is the number of output signals (the number of entries in vector that were written)

0

Slew rate too high for one or more signals (difference format only; the DC level(s) will be corrected as soon as the slew rate permits)

-1

Failure: write error

This function writes a sample to each input signal. The caller should fill an array of WFDB_Samples with the samples and pass a pointer to this array to putvec. (The length of the array must be no less than the number of output signals, as given to osigfopen or osigopen.) On entry, vector[i] contains the next sample from signal i. For example, this modified version of the previous example (see section getvec) copies the first ten samples of each available input signal:

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

main()
{
    int i, j, nsig;
    WFDB_Sample *v;
    WFDB_Siginfo *s;

    nsig = isigopen("100s", NULL, 0);
    if (nsig < 1)
        exit(1);
    s = (WFDB_Siginfo *)malloc(nsig * sizeof(WFDB_Siginfo));
    if (isigopen("100s", s, nsig) != nsig || 
        osigopen("8l", s, nsig) != nsig)
        exit(1);
    v = (WFDB_Sample *)malloc(nsig * sizeof(WFDB_Sample));
    for (i = 0; i < 10; i++)
        if (getvec(v) < 0 || putvec(v) < 0)
            break;
    wfdbquit();
    exit(0);
}

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

All programs that write signals or annotations must invoke wfdbquit to close the output files properly (see section wfdbquit). This example uses record ‘8l’ (see section Piped and Local Records) for the output signal specifications; the output signal files will be named ‘data0’ and ‘data1’ in the current directory. Several of the example programs in chapter 6 illustrate the use of putvec; for example, see section Example 6: A Differentiator.

Note that prior to WFDB library version 10.7.0, putvec would modify the input vector in some cases (the vector argument was not declared as const.)

getann

int getann(WFDB_Annotator an, WFDB_Annotation *annot)

Return:

0

Success

-1

End of file (*annot is not valid)

-2

Failure: incorrect annotator number specified

-3

Failure: unexpected physical end of file

This function reads the next annotation from the input annotator specified by an into the annotation structure (see section Annotation Structures) pointed to by annot. The caller must allocate storage for the annotation structure. Input annotators are numbered 0, 1, 2, etc. This short program uses getann to read the contents of the reference (‘atr’) annotation file for record ‘100s’:

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

main()
{
    WFDB_Anninfo a;
    WFDB_Annotation annot;

    a.name = "atr"; a.stat = WFDB_READ;
    if (annopen("100s", &a, 1) < 0)
        exit(1);
    while (getann(0, &annot) == 0)
        printf("%s %s\n", mstimstr(annot.time), annstr(annot.anntyp));
    exit(0);
}

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

See section Annotator Information Structures, for information on the contents of the WFDB_Anninfo structure, and see section mstimstr, and see section annstr, for details of the functions used to print portions of the annotations read by getann in this example.

ungetann

int ungetann(WFDB_Annotator an, const WFDB_Annotation *annot)

Return:

0

Success

-1

Failure: push-back buffer full (*annot was not pushed back)

-2

Failure: incorrect annotator number specified

This function arranges for the annotation structure pointed to by annot to be the next one read by getann from input annotator an. The pushed-back annotation need not necessarily be one originally read by getann. No more than one annotation may be pushed back at a time for each input annotator. (This function was first introduced in WFDB library version 5.3.)

putann

int putann(WFDB_Annotator an, const WFDB_Annotation *annot)

Return:

0

Success

-1

Failure: write error

-2

Failure: incorrect annotator number specified

This function writes the next annotation for the output annotator specified by an from the annotation structure pointed to by annot. Output annotators are numbered 0, 1, 2, etc. The caller must fill in all fields of the annotation structure. Using version 9.7 and later versions of the WFDB library, annotations may be written in any order (see section Annotation Order). Earlier versions require that annotations be supplied to putann in canonical order, and return an error code of -3 if an out-of-order annotation is supplied. All programs that write signals or annotations must invoke wfdbquit to close the output files properly (see section wfdbquit). Several of the example programs in chapter 6 illustrate the use of putann; for example, see section Example 1: An Annotation Filter.