add a new demo and function help messages

Author: cx1111

demo.ipynb

@@ -11,7 +11,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 3,
    "metadata": {
     "collapsed": false
    },
@@ -201,30 +201,58 @@
    "outputs": [],
    "source": [
     "# Demo 9 - Write a WFDB record without using a Record object via the gateway wrsamp function.\n",
-    "# This is the easiest way to write physical signals to a WFDB file. \n",
+    "# This is the basic way to write physical signals to a WFDB file. \n",
     "\n",
     "# Read part of a record from Physiobank\n",
     "sig, fields = wfdb.srdsamp('a103l', sampfrom = 50000, channels = [0,1], pbdir = 'challenge/2015/training')\n",
     "\n",
     "# Call the gateway wrsamp function, manually inserting fields as function input parameters\n",
-    "wfdb.wrsamp('ecgrecord', fs = 250, units = ['mV', 'mV'], signames = ['I', 'II'], p_signals = sig, fmt = ['16', '16'])"
+    "wfdb.wrsamp('ecgrecord', fs = 250, units = ['mV', 'mV'], signames = ['I', 'II'], p_signals = sig, fmt = ['16', '16'])\n",
+    "\n",
+    "# The new file can be read\n",
+    "recordecg = wfdb.rdsamp('ecgrecord')"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 7,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
-    "# Demo 10 - Read a WFDB annotation file and create a copy under a new extension.\n",
+    "# Demo 10 - Read a WFDB annotation file and create a copy via the wrann() instance method\n",
+    "# of the Annotation object\n",
+    "\n",
+    "# Read an annotation from Physiobank\n",
     "annotation = wfdb.rdann('sampledata/100', 'atr')\n",
-    "annotation.annotator = 'copy'\n",
+    "annotation.annotator = 'cpy'\n",
+    "\n",
+    "# Call the instance method of the object\n",
     "annotation.wrann()\n",
     "\n",
     "# The new file can be read\n",
-    "annotationcopy = wfdb.rdann('100', 'copy')"
+    "ann100copy = wfdb.rdann('100', 'cpy')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "# Demo 11 - Write a WFDB annotation file without using an Annotator object via the gateway wrann function.\n",
+    "\n",
+    "# Read an annotation as an Annotation object\n",
+    "annotation = wfdb.rdann('b001', 'atr', pbdir='cebsdb')\n",
+    "\n",
+    "# Call the gateway wrann function, manually inserting fields as function input parameters\n",
+    "wfdb.wrann('b001', 'cpy', annotation.annsamp, annotation.anntype)\n",
+    "\n",
+    "# The new file can be read\n",
+    "annbcopy = wfdb.rdann('b001', 'cpy')"
    ]
   },
   {
@@ -235,7 +263,7 @@
    },
    "outputs": [],
    "source": [
-    "# Demo 11 - View what the 'anntype' symbols mean in the standard WFDB library\n",
+    "# Demo 12 - View what the 'anntype' symbols mean in the standard WFDB library\n",
     "wfdb.showanncodes()"
    ]
   },
@@ -258,7 +286,7 @@
    },
    "outputs": [],
    "source": [
-    "# Demo 12 - List the Physiobank Databases\n",
+    "# Demo 13 - List the Physiobank Databases\n",
     "\n",
     "dbs = wfdb.getdblist()\n",
     "display(dbs)"
@@ -272,7 +300,7 @@
    },
    "outputs": [],
    "source": [
-    "# Demo 13 - Download all the WFDB records and annotations from a small Physiobank Database\n",
+    "# Demo 14 - Download all the WFDB records and annotations from a small Physiobank Database\n",
     "\n",
     "# Make a temporary download directory in your current working directory\n",
     "cwd = os.getcwd()\n",
@@ -296,7 +324,7 @@
    },
    "outputs": [],
    "source": [
-    "# Demo 14 - Download specified files from a Physiobank database\n",
+    "# Demo 15 - Download specified files from a Physiobank database\n",
     "\n",
     "# The files to download\n",
     "filelist = ['STAFF-Studies-bibliography-2016.pdf', 'data/001a.hea', 'data/001a.dat', 'data/001b.hea', 'data/001b.dat']\n",

wfdb/annotations.py

@@ -12,22 +12,22 @@ class Annotation():
     """
     The class representing WFDB annotations. 
 
-    Annotation objects can be created as with any other class, or by reading a WFDB annotation
+    Annotation objects can be created using the constructor, or by reading a WFDB annotation
     file with 'rdann'. 
 
     The attributes of the Annotation object give information about the annotation as specified
-    by https://www.physionet.org/physiotools/wag/ <INSERT>:
+    by https://www.physionet.org/physiotools/wag/annot-5.htm:
     - annsamp: The annotation location in samples relative to the beginning of the record.
     - anntype: The annotation type according the the standard WFDB codes.
     - subtype: The marked class/category of the annotation.
     - chan: The signal channel associated with the annotations.
     - num: The labelled annotation number. 
     - aux: The auxiliary information string for the annotation.
-    - fs: The sampling frequency of the record.
+    - fs: The sampling frequency of the record if contained in the annotation file.
 
     Call 'showanncodes()' to see the list of standard annotation codes. Any text used to label 
-    annotations that are not one of the codes go in the 'aux' field rather than the 'anntype'
-    field.
+    annotations that are not one of these codes should go in the 'aux' field rather than the 
+    'anntype' field.
     """
     def __init__(self, recordname, annotator, annsamp, anntype, subtype = None, chan = None, num = None, aux = None, fs = None):
         self.recordname = recordname
@@ -350,28 +350,59 @@ def field2bytes(field, value):
 
 
 # Function for writing annotations
-def wrann(recordname, annotator, annsamp, anntype, num = None, subtype = None, chan = None, aux = None, fs = None):
-        # Create Annotation object
-        annotation = Annotation(recordname, annotator, annsamp, anntype, num, subtype, chan, aux, fs)
-        # Perform field checks and write the annotation file
-        annotation.wrann()
+def wrann(recordname, annotator, annsamp, anntype, subtype = None, chan = None, num = None, aux = None, fs = None):
+    """Write a WFDB annotation file.
+
+    Usage:
+    wrann(recordname, annotator, annsamp, anntype, num = None, subtype = None, chan = None, aux = None, fs = None)
+
+    Input arguments:
+    - recordname (required): The string name of the WFDB record to be written (without any file extensions). 
+    - annsamp (required): The annotation location in samples relative to the beginning of the record.
+    - anntype (required): The annotation type according the the standard WFDB codes.
+    - subtype (default=None): The marked class/category of the annotation.
+    - chan (default=None): The signal channel associated with the annotations.
+    - num (default=None): The labelled annotation number. 
+    - aux (default=None): The auxiliary information string for the annotation.
+    - fs (default=None): The numerical sampling frequency of the record to be written to the file.
+
+    Note: This gateway function was written to enable a simple way to write WFDB annotation files without
+          needing to explicity create an Annotation object beforehand. 
+          
+          You may also create an Annotation object, manually set its attributes, and call its wrann() instance method. 
+
+    Example Usage: 
+    import wfdb
+    # Read an annotation as an Annotation object
+    annotation = wfdb.rdann('b001', 'atr', pbdir='cebsdb')
+    # Call the gateway wrann function, manually inserting fields as function input parameters
+    wfdb.wrann('b001', 'cpy', annotation.annsamp, annotation.anntype)
+    """    
+
+    # Create Annotation object
+    annotation = Annotation(recordname, annotator, annsamp, anntype, num, subtype, chan, aux, fs)
+    # Perform field checks and write the annotation file
+    annotation.wrann()
 
 # Display the annotation symbols and the codes they represent
 def showanncodes():
     """
-    Display the annotation symbols and the codes they represent
+    Display the annotation symbols and the codes they represent according to the 
+    standard WFDB library 10.5.24
     
-    Usage: showanncodes()
+    Usage: 
+    showanncodes()
     """
     display(symcodes)
 
 ## ------------- Reading Annotations ------------- ##
 
 def rdann(recordname, annotator, sampfrom=0, sampto=None, pbdir=None):
-    """ Read a WFDB annotation file recordname.annotator and return the fields as lists or arrays
+    """ Read a WFDB annotation file recordname.annotator and return an
+    Annotation object.
 
     Usage: 
-    annotation = rdann(recordname, annot, sampfrom=0, sampto=None)
+    annotation = rdann(recordname, annotator, sampfrom=0, sampto=None, pbdir=None)
 
     Input arguments:
     - recordname (required): The record name of the WFDB annotation file. ie. for 
@@ -380,9 +411,12 @@ def rdann(recordname, annotator, sampfrom=0, sampto=None, pbdir=None):
       file '100.atr', annotator='atr'
     - sampfrom (default=0): The minimum sample number for annotations to be returned.
     - sampto (default=None): The maximum sample number for annotations to be returned.
+    - pbdir (default=None): Option used to stream data from Physiobank. The Physiobank database 
+       directory from which to find the required annotation file.
+      eg. For record '100' in 'http://physionet.org/physiobank/database/mitdb', pbdir = 'mitdb'.
 
     Output argument:
-    - annotation: The annotation object. Call help(wfdb.Annotation) for the attribute
+    - annotation: The Annotation object. Call help(wfdb.Annotation) for the attribute
       descriptions.
 
     Note: For every annotation sample, the annotation file explictly stores the 'annsamp' 

wfdb/downloads.py

@@ -126,7 +126,10 @@ def getannotators(dburl, annotators):
         # Check for an ANNOTATORS file
         r = requests.get(os.path.join(dburl, 'ANNOTATORS'))
         if r.status_code == 404:
-            sys.exit('The database '+dburl+' has no annotation files to download')
+            if annotators == 'all':
+                return
+            else:
+                sys.exit('The database '+dburl+' has no annotation files to download')
         # Make sure the input annotators are present in the database
         annlist = r.content.decode('ascii').splitlines()
         annlist = [a.split('\t')[0] for a in annlist]

wfdb/plots.py

@@ -8,7 +8,24 @@
 # Plot a WFDB Record's signals
 # Optionally, overlay annotation locations
 def plotrec(record=None, title = None, annotation = None, annch = [0], timeunits='samples', returnfig = False): 
+    """ Subplot and label each channel of a WFDB Record.
+    Optionally, subplot annotation locations over selected channels.
     
+    Usage: plotrec(record=None, title = None, annotation = None, annch = [0], timeunits='samples', returnfig=False)
+    
+    Input arguments:
+    - record (required): A wfdb Record object. The p_signals attribute will be plotted.
+    - title (optional): A string containing the title of the graph.
+    - annotation (optional): An Annotation object. The annsamp attribute locations will be overlaid on the signal.
+    - annch (default=[0]): A list of channels on which to plot the annotation samples.
+    - timeunits (default='samples'): String specifying the x axis unit. 
+      Allowed options are: 'samples', 'seconds', 'minutes', and 'hours'.
+    - returnfig (default=False): Specifies whether the figure is to be returned as an output argument
+    
+    Output argument:
+    - figure: The matplotlib figure generated. Only returned if the 'returnfig' option is set to True.
+    """
+
     # Check the validity of items used to make the plot
     # Return the x axis time values to plot for the record (and annotation if any)
     t, tann = checkplotitems(record, title, annotation, annch, timeunits)
@@ -131,7 +148,23 @@ def checkplotitems(record, title, annotation, annch, timeunits):
 
 # Plot the sample locations of a WFDB annotation on a new figure
 def plotann(annotation, title = None, timeunits = 'samples', returnfig = False): 
+    """ Plot sample locations of an Annotation object.
+    
+    Usage: plotann(annotation, title = None, timeunits = 'samples', returnfig = False)
     
+    Input arguments:
+    - annotation (required): An Annotation object. The annsamp attribute locations will be overlaid on the signal.
+    - title (optional): A string containing the title of the graph.
+    - timeunits (default='samples'): String specifying the x axis unit. 
+      Allowed options are: 'samples', 'seconds', 'minutes', and 'hours'.
+    - returnfig (default=False): Specifies whether the figure is to be returned as an output argument
+    
+    Output argument:
+    - figure: The matplotlib figure generated. Only returned if the 'returnfig' option is set to True.
+
+    Note: The plotrec function is useful for plotting annotations on top of signal waveforms.
+    """
+
     # Check the validity of items used to make the plot
     # Get the x axis annotation values to plot
     plotvals = checkannplotitems(annotation, title, timeunits)