file: README		G. Moody	2 July 2010

This directory contains the first beta version of a package for
interchange between WFDB native formats and XML formats.  It includes:

wfdb.dtd	a DTD for WFDB-XML, an XML schema for
		expressing the contents of WFDB
		header and annotation files

wfdb.xsl	an XSLT style sheet that a web browser
		(or other XSLT engine) can use to transform
		a WFDB-XML header or annotation file into
		a human-readable representation of its
 		contents

heaxml.c	a C program that converts a native
		WFDB .hea file into a WFDB-XML file

annxml.c	a C program that converts a native
		WFDB annotation file into a WFDB-XML file

xmlhea.c	a C program that converts a WFDB-XML header
		file into a native WFDB .hea file

xmlann.c	a C program that converts a WFDB-XML annotation
		file into a native WFDB annotation file

Makefile	a 'make' description file for automating the
		process of compiling and installing this software

test/inputs/	miscellaneous sample WFDB-XML files, useful for
		testing this software; these include mitdb-200.atr.xml
		and mitdb-208.hea.xml, sample outputs of annxml and
		heaxml respectively

A copy of the most recent version of wfdb.dtd is posted on PhysioNet at
   http://physionet.org/physiobank/database/XML/wfdb.dtd
This on-line copy is referenced in WFDB-XML files generated by heaxml
and annxml.

Note that these programs require the WFDB library version 10.5.4 or
later, and that those that read WFDB-XML files also require libexpat
(http://expat.sourceforge.net/).  To compile them, install gcc, make,
the WFDB software package, and libexpat if you have not already done so,
then run 'make' from within this directory.  If you don't have 'make',
you can compile these programs manually;  see 'Makefile' for the commands
needed to do so.

It is not necessary to download the native WFDB files in order to use
heaxml and annxml, since they can obtain their inputs directly from
the PhysioNet web server via HTTP.

For example, these commands:
    heaxml mitdb/200
    annxml mitdb/200 atr
produce the WFDB-XML files
    mitdb-200.hea.xml
    mitdb-200.atr.xml
in the current directory.

If you put a copy of wfdb.xsl in the same directory with these output
files, you should be able to view the HTML generated from them via
wfdb.xsl by opening them with Firefox or another web browser that
incorporates an XSLT engine.

Try running heaxml on a mimicdb or mimic2db record, for
example like this:
    heaxml mimic2db/a40006/a40006
This command produces
    mimic2db-a40006-a40006.hea.xml
which includes information about each segment in the
multi-segment record as well as a summary of the entire
record.  The inverse operation, which can be performed by reading
the .xml file using xmlhea, generates a complete set of segment
headers together with the master header in this case.

Warning: the XML outputs generated by these commands are huge.  There is a
good reason that I don't keep these data in XML format on PhysioBank!

A 'datxml' converter for signal files would be a trivial followup to
heaxml and annxml, but unchecked network transfers of XML-format
signals might consume a large fraction of PhysioNet's bandwidth, so
I'm holding off on that for a while.

One of the principal goals of this project is to provide a web-based
importer for researchers wishing to use PhysioToolkit software to
analyze their data on PhysioNet Works.  In the near future, I'd like
to produce a schema using the XML Schema language, as the basis for
a less portable but more effective input validator than the DTD-based
XML schema I've written and included here.  Once these pieces are
complete and it's possible to take a set of data on a round trip from
native WFDB format to XML and back again reliably, the tools will be
promoted from beta status to that of fully supported tools and added
to the PhysioBank ATM toolbox.

This package is the result of my first foray into the indigestibly
jargon-saturated alphabet soup that is XML.  I'm sure that everything
it does can be done better, given more than 4 days of experience.
(Update, August 2010:  now 8 days!  XML is best (in)digested in small
doses.) Your suggestions are welcome;  please limit your use of
acronyms. :-)

Cheers,
George
