documentation

Author: cx1111

README.rst

@@ -11,7 +11,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "metadata": {
     "collapsed": false
    },
@@ -94,8 +94,8 @@
    "source": [
     "# Demo 4 - Read part of a WFDB annotation file into a wfdb.Annotation object, and plot the samples\n",
     "annotation = wfdb.rdann('sampledata/100', 'atr', sampfrom = 100000, sampto = 110000)\n",
-    "#annotation.fs = 360\n",
-    "#wfdb.plotann(annotation, timeunits = 'minutes')\n",
+    "annotation.fs = 360\n",
+    "wfdb.plotann(annotation, timeunits = 'minutes')\n",
     "\n",
     "# Can also read the same file hosted on PhysioBank \n",
     "annotation2 = wfdb.rdann('100', 'atr', sampfrom = 100000, sampto = 110000, pbdir = 'mitdb')"
@@ -215,7 +215,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": null,
    "metadata": {
     "collapsed": false
    },
@@ -237,7 +237,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": null,
    "metadata": {
     "collapsed": true
    },

demo.ipynb

@@ -4,7 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "<h2>This script is for internal developer testing.</h2>"
+    "<h2>This script is for internal developer testing.</h2>\n",
+    "\n",
+    "This is different from the unit tests located in the `tests` directory."
    ]
   },
   {

devtests.ipynb

@@ -20,7 +20,7 @@
     # Versions should comply with PEP440. For a discussion on single-sourcing
     # the version across setup.py and the project code, see
     # https://packaging.python.org/en/latest/single_source_version.html
-    version='0.2.0',
+    version='1.0.0',
 
     description='The WFDB Python Toolbox',
     long_description=long_description,

setup.py

@@ -25,11 +25,21 @@ class Annotation():
     - aux: The auxiliary information string for the annotation.
     - fs: The sampling frequency of the record if contained in the annotation file.
 
+    Constructor function:
+    def __init__(self, recordname, annotator, annsamp, anntype, subtype = None, 
+                 chan = None, num = None, aux = None, fs = None)
+
     Call 'showanncodes()' to see the list of standard annotation codes. Any text used to label 
     annotations that are not one of these codes should go in the 'aux' field rather than the 
     'anntype' field.
+
+    Example usage:
+    import wfdb
+    ann1 = wfdb.Annotation(recordname='ann1', annotator='atr', annsamp=[10,20,400],
+                           anntype = ['N','N','['], aux=[None, None, 'Serious Vfib'])
     """
-    def __init__(self, recordname, annotator, annsamp, anntype, subtype = None, chan = None, num = None, aux = None, fs = None):
+    def __init__(self, recordname, annotator, annsamp, anntype, subtype = None, 
+                 chan = None, num = None, aux = None, fs = None):
         self.recordname = recordname
         self.annotator = annotator
 
@@ -358,18 +368,24 @@ def wrann(recordname, annotator, annsamp, anntype, subtype = None, chan = 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.
+    - annotator (required): The string annotation file extension.
+    - annsamp (required): The annotation location in samples relative to the beginning of the record. List or numpy array.
+    - anntype (required): The annotation type according the the standard WFDB codes. List or numpy array.
+    - subtype (default=None): The marked class/category of the annotation. List or numpy array.
+    - chan (default=None): The signal channel associated with the annotations. List or numpy array.
+    - num (default=None): The labelled annotation number. List or numpy array.
+    - aux (default=None): The auxiliary information string for the annotation. List or numpy array.
     - 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. 
+          
+    Note: Each annotation stored in a WFDB annotation file contains an annsamp and an anntype field. All other fields
+          may or may not be present. Therefore in order to save space, when writing additional features such
+          as 'aux' that are not present for every annotation, it is recommended to make the field a list, with empty 
+          indices set to None so that they are not written to the file.
 
     Example Usage: 
     import wfdb
@@ -426,7 +442,7 @@ def rdann(recordname, annotator, sampfrom=0, sampto=None, pbdir=None):
 
     Example usage:
     import wfdb
-    ann = wfdb.rdann('100', 'atr', sampto = 300000)
+    ann = wfdb.rdann('sampledata/100', 'atr', sampto = 300000)
     """
 
     if sampto and sampto <= sampfrom:

wfdb/annotations.py

@@ -87,9 +87,10 @@ def streamannotation(filename, pbdir):
     return annbytes
 
 
-# Return a list of all the physiobank databases available
+
 def getdblist():
-    """
+    """Return a list of all the physiobank databases available.
+    
     Usage:
     dblist = getdblist()
     """

wfdb/downloads.py

@@ -11,19 +11,27 @@ def plotrec(record=None, title = None, annotation = None, annch = [0], timeunits
     """ 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)
+    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.
+    - title (default=None): A string containing the title of the graph.
+    - annotation (default=None): 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.
+
+    Example Usage:
+    import wfdb
+    record = wfdb.rdsamp('sampledata/100', sampto = 15000)
+    annotation = wfdb.rdann('sampledata/100', 'atr', sampto = 15000)
+
+    wfdb.plotrec(record, annotation = annotation, title='Record 100 from MIT-BIH Arrhythmia Database', timeunits = 'seconds')
     """
 
     # Check the validity of items used to make the plot
@@ -154,7 +162,7 @@ def 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.
+    - title (default=None): 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
@@ -163,6 +171,12 @@ def plotann(annotation, title = None, timeunits = 'samples', returnfig = False):
     - 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.
+
+    Example Usage:
+    import wfdb
+    annotation = wfdb.rdann('sampledata/100', 'atr', sampfrom = 100000, sampto = 110000)
+    annotation.fs = 360
+    wfdb.plotann(annotation, timeunits = 'minutes')
     """
 
     # Check the validity of items used to make the plot

wfdb/plots.py

@@ -310,6 +310,22 @@ class Record(BaseRecord, _headers.HeadersMixin, _signals.SignalsMixin):
 
     In addition, the d_signals and p_signals attributes store the digital and physical
     signals of WFDB records with at least one channel.
+    
+    Contructor function:
+    def __init__(self, p_signals=None, d_signals=None,
+                 recordname=None, nsig=None, 
+                 fs=None, counterfreq=None, basecounter=None, 
+                 siglen=None, basetime=None, basedate=None, 
+                 filename=None, fmt=None, sampsperframe=None, 
+                 skew=None, byteoffset=None, adcgain=None, 
+                 baseline=None, units=None, adcres=None, 
+                 adczero=None, initvalue=None, checksum=None, 
+                 blocksize=None, signame=None, comments=None)
+
+    Example Usage: 
+    import wfdb
+    record1 = wfdb.Record(recordname='r1', fs=250, nsig=2, siglen=1000, filename=['r1.dat','r1.dat'])
+
     """
     # Constructor
     def __init__(self, p_signals=None, d_signals=None,
@@ -423,8 +439,20 @@ class MultiRecord(BaseRecord, _headers.MultiHeadersMixin):
     instance method can be called on MultiRecord objects to return a single segment representation 
     of the record as a Record object. The resulting Record object will have its 'p_signals' field set.
     
-    eg. record1 = wfdb.rdsamp('s00001-2896-10-10-00-31', m2s = False)
-        record1 = record1.multi_to_single()
+    Contructor function:
+    def __init__(self, segments = None, layout = None,
+                 recordname=None, nsig=None, fs=None, 
+                 counterfreq=None, basecounter=None, 
+                 siglen=None, basetime=None, basedate=None, 
+                 segname = None, seglen = None, comments=None)
+
+    Example Usage: 
+    import wfdb
+    recordM = wfdb.MultiRecord(recordname='rm', fs=50, nsig=8, siglen=9999, 
+                               segname=['rm_1', '~', rm_2'], seglen=[800, 200, 900])
+
+    recordL = wfdb.rdsamp('s00001-2896-10-10-00-31', m2s = False)
+    recordL = recordL.multi_to_single()
     """
 
     # Constructor
@@ -972,7 +1000,7 @@ def wrsamp(recordname, fs, units, signames, p_signals = None, d_signals = None,
     # Write a local WFDB record (manually inserting fields)
     wfdb.wrsamp('ecgrecord', fs = 250, units = ['mV', 'mV'], signames = ['I', 'II'], p_signals = sig, fmt = ['16', '16'])
     """
-    
+
     # Check input field combinations
     if p_signals is not None and d_signals is not None:
         sys.exit('Must only give one of the inputs: p_signals or d_signals')
@@ -1229,9 +1257,6 @@ def dldatabasefiles(pbdb, dlbasedir, files, keepsubdirs = True, overwrite = Fals
     - pbdb (required): The Physiobank database directory to download.
       eg. For database 'http://physionet.org/physiobank/database/mitdb', pbdb = 'mitdb'.
     - dlbasedir (required): The full local directory path in which to download the files.
-    - records (default='all'): Specifier of the WFDB records to download. Is either a list of strings
-      which each specify a record, or 'all' to download all records listed in the database's RECORDS file.
-      eg. records = ['test01_00s', test02_45s] for database https://physionet.org/physiobank/database/macecgdb/
     - files (required): A list of strings specifying the file names to download relative to the database 
       base directory
     - keepsubdirs (default=True): Whether to keep the relative subdirectories of downloaded files