.TH A2M 1 "2 August 2012" "WFDB 10.5.14" "WFDB Applications Guide"
.SH NAME
a2m, ad2m, ahaconvert, ahaecg2mit, m2a, md2a \- converting between AHA DB and WFDB formats
.SH SYNOPSIS
To read from an AHA DB DVD:
.br
\fBahaecg2mit\fR [ \fB-s\fR ] \fIahafile\fB.*\fR ...
.br
To read from an AHA DB CD:
.br
\fBahaconvert\fR \fIahafile\fB.cmp\fR ...
.br
To read from an AHA DB floppy disk or 9-track tape:
.br
\fBa2m -i\fR \fIahafile\fR \fB-r\fR \fIrecord\fR \fB-a\fR \fIannotator\fR [ \fIoptions\fR ... ]
.br
\fBad2m -i\fR \fIahafile\fR \fB-r\fR \fIrecord\fR [ \fIoptions\fR ... ]
.br
To convert a WFDB record to AHA tape format:
.br
\fBm2a -r\fR \fIrecord\fR \fB-a\fR \fIWFDB-annotator AHA-annotator\fR [ \fIoptions\fR ... ]
.br
\fBmd2a -o\fR \fIahafile\fR \fB-r\fR \fIrecord\fR [ \fIoptions\fR ... ]
.SH DESCRIPTION
.PP
The AHA Database for Evaluation of Ventricular Arrhythmia Detectors (AHA DB)
has been distributed since 1983 by ECRI (http://www.ecri.org), in
at least four formats:
.TP
\fBsingle-file (.txt) format\fR
Developed by ECRI for distributions of the AHA DB on DVDs (ca. 2012) as a
successor to the earlier .ecg format (below); this format can be read by
\fBahaecg2mit\fR.
.TP
\fBsingle-file (.ecg) format\fR
Developed by ECRI for distributions of the AHA DB on DVDs (ca. 2008); this
format can be read by \fBahaecg2mit\fR.
.TP
\fBcompressed (.cmp and .ano) format\fR
Previously developed by ECRI for distributions of the AHA DB on floppy
disks (ca. 1990) and CDs (ca. 1995); this format can be read by \fBahaconvert\fR
(using \fBa2m\fR and \fBad2m\fR).
.TP
\fBtape format\fR
Originally specified by the creators of the AHA DB at the Biomedical
Computing Laboratory (BCL) at Washington University in St. Louis.
This format was also used for tape distributions of the MIT-BIH
Arrhythmia Database from 1980-1989; it can be read by \fBa2m\fR and
\fBad2m\fR, and written by \fBm2a\fR and \fBmd2a\fR.
.PP
The AHA DB consists of a \fBdevelopment\fR set of 80 records (which
were created by the BCL between 1976 and 1983 and have been
distributed by ECRI since then) and a \fBtest\fR set of 75 records
(also created by the BCL between 1976 and 1983, but not distributed
until about 20 years later). Each record contains two simultaneous
ECG signals that have been digitized for three hours continuously, and
beat annotations for the final 30 minutes of the signals in each
record. The records have been distributed in two versions: a \fBlong
version\fR (records named n0nn and n1nn) containing the full three
hours of signals, and a \fBshort version\fR (records named n2nn and
n3nn) containing only the final 35 minutes of signals (including all
of the annotated beats).
.PP
ECRI currently supplies the AHA DB only on DVDs, so the tape and
compressed formats are primarily of historical interest. The programs
described below convert these formats into WFDB (also known as
PhysioBank or MIT) format. Long version input files can be converted
in their entirety, or these programs can create short version records
from either long or short version inputs. The last two programs below
convert WFDB records to AHA tape format (conversion to AHA DB DVD and
CD/floppy disk distribution formats is not supported). All of these
programs print a brief usage summary if invoked with no command-line
arguments, or with a \fB-h\fR option.
.PP
Note that records in WFDB format can be excerpted and reformatted in
more generally useful ways using \fBsnip\fR(1) or \fBxform\fR(1).
.SH DVD FORMAT
.SS ahaecg2mit
.PP
Use \fBahaecg2mit\fR to convert .txt or .ecg files from an AHA DB DVD into
WFDB-compatible records. One or more input filenames may be supplied as
command-line arguments; each specified input file is converted into
a WFDB record, including a .hea (header) file, a .dat (signal) file,
and a .atr (reference annotation) file. If the first command-line
argument is \fB-s\fR, then \fBahaecg2mit\fR produces short-form records
with the correct (n2nn or n3nn) record names.
If the .txt or .ecg files are not in the current directory, give their
full pathnames. The output files are always written to the current
directory, so be sure that the current directory is writeable (it
should not be the DVD) and that has sufficient free space (roughly
8 Mb per long version record, or 1.6 MB per short version record).
.SH OLDER FORMATS
.SS ahaconvert
.PP
Use \fBahaconvert\fR to convert one or more records from an AHA DB CD-ROM
into WFDB format. Run \fBahaconvert\fR without any command-line arguments
for instructions, or see the examples below. Note: \fBahaconvert\fR is
a shell script; to use it successfully, you will need to have a shell
(standard with all versions of Unix, and included in the free Cygwin package
for MS-Windows) as well as \fBad2m\fR and \fBa2m\fR, which perform the
actual work of the conversion.
.SS a2m
.PP
Use \fBa2m\fR to convert AHA-format annotation files from tapes, floppy disks,
or CDs into WFDB format. Options for \fBa2m\fR include:
.TP
\fB-s\fR \fItime\fR
Shift annotations forward by the specified \fItime\fR (default: no shift for
type 0 input files, 5 minutes for type 1, 2 hours and 30 minutes for
type 2; for type 3, the default is 5 minutes if \fIrecord\fR is of the form
\fIn\fR2\fInn\fR or \fIn\fR3\fInn\fR, or 2 hours and 30 minutes if \fIrecord\fR
is of the form \fIn\fR0\fInn\fR or \fIn\fR1\fInn\fR).
.TP
\fB-t\fR \fItype\fR
Convert an input file of the specified \fItype\fR (0:
a file produced by a WFDB application using \fBputann\fR and
\fBWFDB_AHA_WRITE\fR mode; 1: an AHA DB `short format' tape file; 2: an
AHA DB `long format' tape file; 3: an AHA DB compressed (\fB.ano\fR)
CD-ROM or floppy disk file). Input files of types 1, 2, and 3 are assumed to
contain annotation times in milliseconds, which are converted to
sampling intervals based on an assumed sampling frequency of 250 Hz. Default:
type 3 is assumed if \fIahafile\fR ends with \fB.ANO\fR or \fB.ano\fR; type
0 is assumed otherwise.
.SS ad2m
.PP
Use \fBad2m\fR to convert AHA-format signal files from tapes, floppy disks,
or CDs into WFDB format. Options for \fBad2m\fR include:
.TP
\fB-c\fR
Convert an AHA DB compressed (\fB.cmp\fR) floppy disk file (this is
the default if \fIahafile\fR ends with \fB.CMP\fR or \fB.cmp\fR,
otherwise \fBad2m\fR assumes that the input is a file in AHA DB tape
format).
.TP
\fB-f\fR \fItime\fR
Begin converting at the specified \fItime\fR relative to the beginning of the
input file (default: 0, i.e., at the beginning of the input file)
.TP
\fB-t\fR \fItime\fR
Stop converting at the specified \fItime\fR relative to the beginning
of the input file (default: 35 minutes after the starting time if
\fIrecord\fR is of the form \fIn\fR2\fInn\fR or \fIn\fR3\fInn\fR, 3 hours
if \fIrecord\fR is of the form \fIn\fR0\fInn\fR or \fIn\fR1\fInn\fR,
or the end of the input file, whichever comes first).
.SS m2a
.PP
Use \fBm2a\fR to convert WFDB-format annotation files into AHA tape format.
Options for \fBm2a\fR include:
.TP
\fB-s\fR \fItime\fR
Shift annotation times backward by the specified \fItime\fR, and convert them
from sample intervals to milliseconds.
.SS md2a
.PP
Use \fBmd2a\fR to convert WFDB-format signal files into AHA tape format.
Options for \fBmd2a\fR include:
.TP
\fB-n\fR \fInew-record\fR
Create a new header file for the AHA-format output signal file, so that it
may be read as record \fInew-record\fR.
.SH ENVIRONMENT
.PP
It may be necessary to set and export the shell variable \fBWFDB\fR (see
\fBsetwfdb\fR(1)).
.SH EXAMPLES
.SS "AHA Database DVD"
If the DVD is accessible as \fB/media/dvd/\fR, either
.br
\fBahaecg2mit -s /media/dvd/*.txt\fR
.br
or (for DVDs written in the older format):
.br
\fBahaecg2mit -s /media/dvd/*.ecg\fR
.br
makes a complete set of short-version records in the current directory.
(Omit the \fB-s\fR to make a set of long-version records instead.)
Under Windows, within a Cygwin window, the DVD is accessible as
\fB/cygdrive/d/\fR (or \fB/cygdrive/e/\fR, etc., depending on the
drive letter that Windows has assigned), so the same task can be done
under Windows by
.br
\fBahaecg2mit -s /cygdrive/d/*.txt\fR
.SS "AHA Database CD"
AHA DB CDs contain both long and short versions of each record. In
most cases, you will want to convert only one version of each record.
To convert the short-version records only, if the contents of the
CD-ROM are available at \fB/mnt/cdrom\fR, type:
.br
\fBahaconvert /mnt/cdrom/?[23]??.cmp\fR
.br
(The pattern '\fB?[23]??\fR' matches the record names of the short-version
records.)
.PP
To convert the long-version records only, type:
.br
\fBahaconvert /mnt/cdrom/?[01]??.cmp\fR
.SS "AHA DB floppy disk"
To make a version of AHA DB record 1201 in WFDB format, given the distribution
floppy disk, copy the files \fB1201.ano\fR and \fB1201.cmp\fR to the current
directory, then type:
.br
\fBad2m -i 1201.cmp -r 1201 -c\fR
.br
\fBa2m -i 1201.ano -r 1201 -a atr -t 3\fR
.br
These commands produce files \fB1201.dat\fR (the signal file),
\fB1201.hea\fR (the header file), and \fB1201.atr\fR (the reference
annotation file), all in the current directory. Run \fBad2m\fR first,
so that the new header file is available for the use of \fBa2m\fR.
(In this example, note that the options '-r 1201', '-c', and '-t 3' are
redundant unless you have renamed the input files, since \fBad2m\fR and
\fBa2m\fR recognize the record name and file types from the suffixes
otherwise.)
.SS "AHA DB short version tape"
.PP
To obtain the same files given a `short version' 9-track distribution tape,
copy the second and third files from the tape into files \fB1201.tap\fR and
\fB1201.ann\fR in the current directory, then type:
.br
\fBad2m -i 1201.tap -r 1201\fR
.br
\fBa2m -i 1201.ann -r 1201 -a atr -t 1\fR
.br
The names for the files copied from the tape are arbitrary, but do not
use names of files to be generated by \fBad2m\fR or \fBa2m\fR (see the
previous example). Note that the first and fourth files on the
distribution tape contain an `id' block, which can be read by
\fBreadid\fR (a program included in the \fBconvert\fR directory of the
WFDB Software Package) to verify the record name. Distribution tapes
that contain more than one record contain additional sets of four
files, always in the same order within each set.
.SS "AHA DB long version tape"
.PP
To make a version of the three-hour AHA DB record 1001 in WFDB format,
given the `long version' distribution tape, copy the second and third files
from the tape into files \fB1001.tap\fR and \fB1001.ann\fR in the current
directory, then type:
.br
\fBad2m -i 1001.tap -r 1001 -t 3:0:0\fR
.br
\fBa2m -i 1001.ann -r 1001 -a atr -t 2\fR
.br
The \fB-t 3:0:0\fR option is necessary to prevent \fBad2m\fR from truncating
the signal file after the first 35 minutes.
.SS "Converting AHA DB long version tapes to short version records"
.PP
To make a version of AHA DB record 1201 in WFDB format, given a `long version'
9-track distribution tape containing the corresponding three-hour record 1001,
copy the second and third files from the tape into files \fB1001.tap\fR and
\fB1001.ann\fR in the current directory, then type:
.br
\fBad2m -i 1001.tap -r 1201 -f 2:25:0\fR
.br
\fBa2m -i 1001.ann -r 1201 -a atr -t 1\fR
.br
In this case, the \fB-f\fR option instructs \fBad2m\fR to skip the first
two hours and 25 minutes of the `long-version' AHA signal file, and to reformat
the remainder (equivalent to the 35-minute `short-version' record). The
\fB-t 1\fR option is used with \fBa2m\fR even though its input file comes from
a `long-version' tape, because the annotation times must be shifted only by
the amount necessary for a `short-version' tape in this case.
.SS "Sharing signal files for long version and short version AHA DB records"
.PP
To keep both versions (1001 and 1201) on-line, make the long version
first (see above), then type:
.br
\fBa2m -i 1001.ann -r 1201 -a atr -t 1\fR
.br
to make a short version reference annotation file. Continue (under UNIX) by:
.br
\fBcp 1001.hea 1201.hea\fR
.br
or (under MS-DOS) by:
.br
\fBcopy 1001.hea 1201.hea\fR
.br
and edit \fB1201.hea\fR, replacing `1001' in the first line (only!)
with `1201', and replacing `212' in the second and third lines by
`212+6525000' (see the description of the `byte offset' field in
\fBheader\fR(5)). Although each version needs its own header and
reference annotation files, the long-version signal file can be shared
with the short version, allowing a substantial savings in storage
requirements. Note that WFDB application programs that read the
`short version' record 1201 signal file may report signal checksum
errors at the end of the record, unless you also recalculate the
signal checksums (easily done using \fBsnip\fR(1) to copy the record;
delete the copy once the checksums have been obtained).
.SH AVAILABILITY
These programs are provided in the \fBconvert\fR directory of the WFDB Software
Package. Run \fBmake\fR in that directory to compile and install them if they
have not been installed already.
.SH SEE ALSO
\fBsnip\fR(1), \fBxform\fR(1), \fBwfdb\fR(3), \fBheader\fR(5)
.SH AUTHOR
George B. Moody (george@mit.edu)
.SH SOURCES
http://www.physionet.org/physiotools/wfdb/convert/a2m.c
.br
http://www.physionet.org/physiotools/wfdb/convert/ad2m.c
.br
http://www.physionet.org/physiotools/wfdb/convert/ahaconvert
.br
http://www.physionet.org/physiotools/wfdb/convert/ahaecg2mit.c
.br
http://www.physionet.org/physiotools/wfdb/convert/m2a.c
.br
http://www.physionet.org/physiotools/wfdb/convert/md2a.c