file: README		I. Henry and G. Moody	 August 2005
			Last revised:		10 March 2006

Name: wfdb-python -- WFDB wrappers for Python

Purpose:

The WFDB library (http://physionet.org/physiotools/wfdb.shtml) provides uniform
access to digitized signals and annotations in a wide variety of formats,
including those in PhysioBank (http://physionet.org/physiobank/).  The WFDB
library is written in C and includes bindings for C++ and wrappers for Fortran.

This package provides an interface that allows use of the WFDB library
functions from Python programs.

Authors:

Isaac Henry (ihenry@physionet.org), George Moody (george@physionet.org)

Background literature:

The SWIG web site (http://www.swig.org/)
The WFDB Programmer's Guide (http://www.physionet.org/physiotools/wpg/)

Platforms:

GNU/Linux (development) Mac OS X, MS Windows.  Other platforms supported by
SWIG should also work but have not been tested.

Code organization:

This is a subpackage of wfdb-swig (see ../README).  The file named Makefile
invokes 'python setup.py' to manage the build and installation processes
(see INSTALL).  The wrappers themselves are generated by SWIG from ../wfdb.i.

URLs:
   code:
	http://physionet.org/wfdb-swig/wfdb-python
	http://physionet.org/wfdb-swig/wfdb.i
   test scripts and data:
	http://physionet.org/wfdb-swig/examples/*.py
   docs:
	The WFDB Programmer's Guide (http://physionet.org/physiotools/wpg/);
	also see the notes below

Installation and Testing:

See INSTALL, in this directory.

_______________________________________________________________________

A Trivial Example Program in Python

This program is a translation to Python of Example 2 from the WFDB Programmer's
Guide (http://physionet.org/physiotools/wpg/).  It translates the `atr'
annotations for the record named in its argument into an AHA-format annotation
file with the annotator name `aha'.

  import wfdb, sys

  def main(argv):
      an = wfdb.WFDB_AnninfoArray(2)
      annot = wfdb.WFDB_Annotation()
      if len(argv) < 2:
          print "usage:", argv[0], "record"
          sys.exit(1)
      a = an[0]
      a.name = "atr"
      a.stat = wfdb.WFDB_READ
      an[0] = a
      a = an[1]
      a.name = "aha"
      a.stat = wfdb.WFDB_AHA_WRITE
      an[1] = a
      if wfdb.annopen(argv[1], an.cast(), 2) < 0: sys.exit(2)
      while 1:
          if not (wfdb.getann(0, annot) == 0 and wfdb.putann(0,annot) == 0): break
      wfdb.wfdbquit()
    
  if __name__ == "__main__":
      main(sys.argv)

First, note that all programs that use the WFDB wrappers for Python must
include the statement:

  import wfdb

The functions used in this example are described in detail in the WFDB
Programmer's Guide.  All functions are methods of the "wfdb" class. For now,
note that wfdb.annopen prepares a record to read by wfdb.getann, which reads an
annotation each time it is called. Also notice that WFDB constants are also
members of the "wfdb" class.

The WFDB data types are described in the WFDB Programmer's Guide. In Python,
each WFDB structure is paired with an accessor class that allows you to work
with pointers to the native C structures in memory.  These classes are often
refereed to as "shadow classes".

In addition, there are several 'Array' special classes, which are used in place
of pointer arrays in C.  Note that the 'cast' method must be used when passing
an 'Array' object to a method, as in

  wfdb.annopen(argv[1], an.cast(), 2)

Special care must be taken when manipulating the members of an array. As shown
in the example, you must first obtain a shadow class object for an item,
  
  a = an[0]

which can then be used to get or set structure members. 

  a.name = "atr"
  a.stat = wfdb.WFDB_READ

Take special note that you must copy your changes back to the array.
 
  an[0] = a

This may seem unintuitive, but remember that the Array classes only manipulate
underlying C structures.

A ready-to-run copy of this program is available as ../examples/example2.py.
To run it, type
	python ../examples/example2.py
or (if python is installed as /usr/bin/python):
	../examples/example2.pl
The ../examples directory also contains translations into Perl 5 of the other
examples from the WFDB Programmer's Guide.