.TH MXM 1 "22 November 2002" "WFDB 10.3.0" "WFDB Applications Guide"
.SH NAME
mxm \- ANSI/AAMI-standard measurement-by-measurement annotation comparator
.SH SYNOPSIS
\fBmxm -r\fR \fIrecord\fR \fB-a\fR \fIreference-annotator test-annotator\fR [ \fIoptions ... \fR ]
.SH DESCRIPTION
.PP
This program implements the measurement-by-measurement comparison
algorithm specified in ANSI/AAMI EC38:1998, the American National
Standard for ambulatory ECGs, for evaluating heart rate measurements.
Its use is not restricted to comparisons of these particular types of
measurements, however; if other types of measurements (e.g., HRV
measurements) are available, they may be compared in the same way by
\fRmxm\fR.
.PP
Input to this program consists of two annotation files associated with the same
\fIrecord\fR.  One of these is designated the \fIreference\fR annotation file,
the other the \fItest\fR annotation file.
.PP
\fIOptions\fR include:
.TP
\fB-f\fR \fItime\fR
Begin the comparison at the specified \fItime\fR (default: 5 minutes after the
beginning of the record).
.TP
\fB-h\fR
Print a usage summary.
.TP
\fB-l\fR \fIfile\fR
Append a line-format report to \fIfile\fR (see below).
.TP
\fB-L\fR \fIfile\fR
Same as \fB-l\fR \fIfile\fR.
.TP
\fB-m\fR \fIn\fR
Compare measurement type \fIn\fR (default: \fIn\fR = 0).
.TP
\fB-s\fR \fIfile\fR
Append a standard-format report to \fIfile\fR (see below).
.TP
\fB-t\fR \fItime\fR
Stop the comparison at the specified \fItime\fR (default: the end of the record
if it is defined, the end of the reference annotation file otherwise;  if
\fItime\fR is 0, the comparison ends when the end of either annotation file is
reached).
.TP
\fB-u\fR
Calculate unnormalized RMS measurement error (see below).
.PP
\fBmxm\fR reads the annotation files, ignoring all annotations except for those
with \fIanntyp\fR = \fBMEASURE\fR and \fIsubtyp\fR = \fIn\fR (where \fIn\fR is
the measurement type selected using the \fB-m\fR option).  The measurements to
be compared are extracted from the \fIaux\fR fields of these annotations, which
should contain strings with the measurements in \fBscanf\fR(3) \fB%lf\fR format
(e.g., ``85'', ``-12.4'', ``1.2e3'').  A measurement error is calculated for
each test measurement by comparing it with the reference measurement that is
nearest in time.  By default, \fBmxm\fR reports the normalized RMS measurement
error (i.e., the square root of the sum of the squares of the differences
between the test and reference measurements, divided by the sum of the
reference measurements).  If the \fB-u\fR option is given, \fBmxm\fR reports
the unnormalized RMS measurement error (the square root of the sum of the
squares of the differences between the test and reference measurements, divided
by the number of test measurements); this may be useful if the measurement has
a zero mean (or a mean value that is significantly smaller than the mean
absolute value).  The mean reference measurement that \fBmxm\fR reports is the
mean of the reference measurements that are actually used in the comparison;
since there is not necessarily a one-to-one correspondence between test and
reference measurements, some reference measurements may not be included in the
mean, and others may be included more than once.
.PP
If `\fB-\fR' is given as a \fIfile\fR argument, reports are written on the
standard output.  If no options are specified, \fBmxm\fR writes standard
reports on the standard output (equivalent to using the option \fB-s -\fR).
The output generated by selecting \fB-l\fR or \fB-L\fR includes column headings
only if a \fIfile\fR other than `\fB-\fR' is specified, and only if the
specified \fIfile\fR does not already exist.  In this way, \fBmxm\fR can be
used repeatedly to build up a line-format table for multiple records, for
further processing by \fBsumstats\fR(1).
.SH DIAGNOSTICS
.TP
\fInon-standard comparison selected\fR
The \fB-f\fR, \fB-t\fR, and \fB-u\fR options modify the comparison in ways
not permitted by the draft standard.
.TP
\fIreference measurements have zero mean\fR
Normalized RMS measurement error cannot be determined.  Try using the \fB-u\fR
option.
.SH ENVIRONMENT
.PP
It may be necessary to set and export the shell variable \fBWFDB\fR (see
\fBsetwfdb\fR(1)).
.SH SEE ALSO
\fBbxb\fR(1), \fBecgeval\fR(1), \fBepicmp\fR(1), \fBrxr\fR(1),
\fBsetwfdb\fR(1), \fBsumstats\fR(1)
.br
\fIEvaluating ECG Analyzers\fR (in the \fIWFDB Applications Guide\fR)
.br
\fIAmerican National Standard ANSI/AAMI EC38:1998, Ambulatory
Electrocardiographs\fR;  available from AAMI, 1110 N Glebe Road,
Suite 220, Arlington, VA 22201 USA (http://www.aami.org/).
.SH AUTHOR
George B. Moody (george@mit.edu)
.SH SOURCE
http://www.physionet.org/physiotools/wfdb/app/mxm.c