readme

Author: cx1111

README.rst

@@ -25,7 +25,57 @@ functions.
 Reading Signals
 ~~~~~~~~~~~~~~~
 
-**rdsamp** - Read a WFDB file and return the signal as a numpy array and
+**rdsamp** - Read a WFDB record and return the signal and record descriptors as attributes in a wfdb.Record object.
+
+::
+    record = rdsamp(recordname, sampfrom=0, sampto=None, channels=None, physical=True, m2s=True)
+
+Example Usage:
+
+::
+
+    import wfdb
+    record = wfdb.rdsamp('100', sampto=2000)
+
+Input Arguments:
+
+-  ``recordname`` (mandatory) - The name of the WFDB record to be read
+   (without any file extensions).
+-  ``sampfrom`` (default=0) - The starting sample number to read for
+   each channel.
+-  ``sampto`` (default=length of entire signal)- The final sample number
+   to read for each channel.
+-  ``channels`` (default=all channels) - Indices specifying the channels
+   to be returned.
+-  ``physical`` (default=True) - Flag that specifies whether to return
+   signals in physical (True) or digital (False) units.
+-  ``m2s`` (default=True) - Flag used only for multi-segment
+   records. Specifies whether to convert the returned wfdb.MultiRecord object
+   into a wfdb.Record object (True) or not (False).
+
+Output Arguments:
+
+-  ``record`` - 
+
+-  ``fields`` - A dictionary of metadata about the record extracted or
+   deduced from the header/signal file. If the input record is a
+   multi-segment record, the output argument will be a list of
+   dictionaries:
+
+   -  The first list element will be a dictionary of metadata about the
+      master header.
+   -  If the record is in variable layout format, the next list element
+      will be a dictionary of metadata about the layout specification
+      header.
+   -  The last list element will be a list of dictionaries of metadata
+      for each segment. For empty segments, the dictionary will be
+      replaced by a single string: ‘Empty Segment’
+
+
+Writing Signals
+~~~~~~~~~~~~~~~
+
+**wrsamp** - Read a WFDB file and return the signal as a numpy array and
 the metadata as a dictionary.
 
 ::

wfdb/annotations.py

@@ -7,7 +7,26 @@
 
 # Class for WFDB annotations
 class Annotation():
-
+    """
+    The class representing WFDB annotations. 
+
+    Annotation objects can be created as with any other class, 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>:
+    - 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.
+
+    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.
+    """
     def __init__(self, recordname, annotator, annsamp, anntype, num = None, subtype = None, chan = None, aux = None, fs = None):
         self.recordname = recordname
         self.annotator = annotator
@@ -22,6 +41,11 @@ def __init__(self, recordname, annotator, annsamp, anntype, num = None, subtype
 
     # Write an annotation file
     def wrann(self):
+        """
+        Instance method to write a WFDB annotation file from an Annotation object.
+
+        Example usage: 
+        """
         # Check the validity of individual fields used to write the annotation file
         self.checkfields() 
 
@@ -307,36 +331,41 @@ def wrann(recordname, annotator, annsamp, anntype, num = None, subtype = None, c
 
 # Display the annotation symbols and the codes they represent
 def showanncodes():
+    """
+    Display the annotation symbols and the codes they represent
+    
+    Usage: showanncodes()
+    """
     display(symcodes)
 
 ## ------------- Reading Annotations ------------- ##
 
 def rdann(recordname, annotator, sampfrom=0, sampto=None):
-    """ Read a WFDB annotation file recordname.annot and return the fields as lists or arrays
+    """ Read a WFDB annotation file recordname.annotator and return the fields as lists or arrays
 
-    Usage: annotation = rdann(recordname, annot, sampfrom=0, sampto=[], anndisp=1)
+    Usage: 
+    annotation = rdann(recordname, annot, sampfrom=0, sampto=None)
 
     Input arguments:
     - recordname (required): The record name of the WFDB annotation file. ie. for 
       file '100.atr', recordname='100'
     - annotator (required): The annotator extension of the annotation file. ie. for 
-      file '100.atr', annot='atr'
+      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.
+    - sampto (default=None): The maximum sample number for annotations to be returned.
 
     Output argument:
-    - annotation: The annotation object with the following fields:
-        - annsamp: The annotation location in samples relative to the beginning of the record.
-        - anntype: The annotation type according the the standard WFDB keys.
-        - 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 written into the annotation file if present.
-
-    *NOTE: Every annotation sample contains the 'annsamp' and 'anntype' fields. All 
-           other fields default to 0 or empty if not present.
+    - annotation: The annotation object. Call help(wfdb.Annotation) for the attribute
+      descriptions.
+
+    Note: For every annotation sample, the annotation file explictly stores the 'annsamp' 
+    and 'anntype' fields but not necessarily the others. When reading annotation files
+    using this function, fields which are not stored in the file will either take their
+    default values of 0 or None, or will be carried over from their previous values if any.
+
+    Example usage:
+    import wfdb
+    ann = wfdb.rdann('100', 'atr', sampto = 300000)
     """
 
     if sampto and sampto <= sampfrom:

wfdb/records.py

@@ -19,7 +19,6 @@
 # The base WFDB class to extend to create Record and MultiRecord. Contains shared helper functions and fields.             
 class BaseRecord():
     # Constructor
-    
     def __init__(self, recordname=None, nsig=None, 
                  fs=None, counterfreq=None, basecounter = None, 
                  siglen = None, basetime = None, basedate = None, 
@@ -219,8 +218,8 @@ class Record(BaseRecord, _headers.HeadersMixin, _signals.SignalsMixin):
     The attributes of the Record object give information about the record as specified
     by https://www.physionet.org/physiotools/wag/header-5.htm
 
-    In addition, the d_signals and p_signals attributes represent the digital and physical
-    signals of WFDB records with at least one channel. 
+    In addition, the d_signals and p_signals attributes store the digital and physical
+    signals of WFDB records with at least one channel.
     """
     # Constructor
     def __init__(self, p_signals=None, d_signals=None,
@@ -341,16 +340,18 @@ class MultiRecord(BaseRecord, _headers.MultiHeadersMixin):
     MultiRecord objects can be created as with any other class, or by reading a multi-segment
     WFDB record using 'rdsamp' with the 'm2s' (multi to single) input parameter set to False.
 
-    The attributes of the MultiRecord object give information about the record as specified
+    The attributes of the MultiRecord object give information about the entire record as specified
     by https://www.physionet.org/physiotools/wag/header-5.htm
 
     In addition, the 'segments' parameter is a list of Record objects representing each
-    individual segment of the entire multi-segment record.
-
-    Noteably, the 'multi_to_single' 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.
+    individual segment, or 'None' representing empty segments, of the entire multi-segment record.
 
+    Noteably, this class has no attribute representing the signals as a whole. The 'multi_to_single' 
+    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()
     """
     # Constructor
     def __init__(self, segments = None, layout = None,
@@ -669,7 +670,9 @@ def rdsamp(recordname, sampfrom=0, sampto=None, channels = None, physical = True
           'srdsamp' returns two arguments: the physical signals array, and a dictionary of a 
           few select fields, a subset of the original wfdb Record attributes. 
 
-    Example Usage: record1 = wfdb.rdsamp('macecgdb/test01_00s', sampfrom=800, channels = [1,3])
+    Example Usage: 
+    import wfdb
+    record1 = wfdb.rdsamp('macecgdb/test01_00s', sampfrom=800, channels = [1,3])
     """
 
     dirname, baserecordname = os.path.split(recordname)
@@ -822,7 +825,42 @@ def wanted_siginds(wanted_signames, record_signames):
 # A simple version of rdsamp for ease of use
 # Return the physical signals and a few essential fields
 def srdsamp(recordname, sampfrom=0, sampto=None, channels = None):
+    """Read a WFDB record and return the signal and record descriptors as attributes in a wfdb.Record object
+
+    Usage:
+    record = rdsamp(recordname, sampfrom=0, sampto=None, channels=None, physical=True, m2s=True)
+
+    Input arguments:
+    - recordname (required): The name of the WFDB record to be read (without any file extensions). 
+      If the argument contains any path delimiter characters, the argument will be interpreted as 
+      PATH/baserecord and the data files will be searched for in the local path.
+    - sampfrom (default=0): The starting sample number to read for each channel.
+    - sampto (default=None): The sample number at which to stop reading for each channel.
+    - channels (default=all): Indices specifying the channel to be returned.
 
+    Output arguments:
+    - signals: A 2d numpy array storing the physical signals from the record. 
+    - fields: A dictionary specifying several key attributes of the read record:
+        - fs: The sampling frequency of the record
+        - units: The units for each channel
+        - signame: The signal name for each channel
+        - comments: Any comments written in the header
+
+    Note: If a signal range or channel selection is specified when calling this function, the
+          the resulting attributes of the returned object will be set to reflect the section
+          of the record that is actually read, rather than necessarily what is in the header file.
+          For example, if channels = [0, 1, 2] is specified when reading a 12 channel record, the 
+          'nsig' attribute will be 3, not 12. 
+
+    Note: The 'rdsamp' function exists as a simple alternative to 'rdsamp' for the most common
+          purpose of extracting the physical signals and a few important descriptor fields. 
+          'srdsamp' returns two arguments: the physical signals array, and a dictionary of a 
+          few select fields, a subset of the original wfdb Record attributes. 
+
+    Example Usage: 
+    import wfdb
+    sig, fields = wfdb.srdsamp('macecgdb/test01_00s', sampfrom=800, channels = [1,3])
+    """
     record = rdsamp(recordname, sampfrom, sampto, channels, True, True)
 
     signals = record.p_signals
@@ -835,12 +873,18 @@ def srdsamp(recordname, sampfrom=0, sampto=None, channels = None):
 #------------------- /Reading Records -------------------#
 
 
-# Simple function for single segment wrsamp
-def wrsamp(recordname, fs, units, signames, p_signals = None, d_signals = None,  fmt = None, comments= None):
+# Function for writing single segment records
+def wrsamp(recordname, fs, units, signames, p_signals = None, d_signals = None,  
+    fmt = None, gain = None, baseline = None, comments= None):
+    """
     
+    """
     # 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')
+    if d_signals is not none:
+        if fmt is None or gain is None or baseline is None:
+            sys.exit("When using d_signals, must also specify 'fmt', 'gain', and 'baseline' fields.")
 
     # Create the Record object
     record = Record(recordname = recordname, p_signals = p_signals, fs = fs, fmt = fmt, units = units, signame = signames, comments = comments)