Skip to content

Commit 12f4bf5

Browse files
cx1111cx1111
committed
readme
1 parent c5f839b commit 12f4bf5

File tree

3 files changed

+153
-30
lines changed

3 files changed

+153
-30
lines changed

‎README.rst

Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,57 @@ functions.
2525
Reading Signals
2626
~~~~~~~~~~~~~~~
2727

28-
**rdsamp** - Read a WFDB file and return the signal as a numpy array and
28+
**rdsamp** - Read a WFDB record and return the signal and record descriptors as attributes in a wfdb.Record object.
29+
30+
::
31+
record = rdsamp(recordname, sampfrom=0, sampto=None, channels=None, physical=True, m2s=True)
32+
33+
Example Usage:
34+
35+
::
36+
37+
import wfdb
38+
record = wfdb.rdsamp('100', sampto=2000)
39+
40+
Input Arguments:
41+
42+
- ``recordname`` (mandatory) - The name of the WFDB record to be read
43+
(without any file extensions).
44+
- ``sampfrom`` (default=0) - The starting sample number to read for
45+
each channel.
46+
- ``sampto`` (default=length of entire signal)- The final sample number
47+
to read for each channel.
48+
- ``channels`` (default=all channels) - Indices specifying the channels
49+
to be returned.
50+
- ``physical`` (default=True) - Flag that specifies whether to return
51+
signals in physical (True) or digital (False) units.
52+
- ``m2s`` (default=True) - Flag used only for multi-segment
53+
records. Specifies whether to convert the returned wfdb.MultiRecord object
54+
into a wfdb.Record object (True) or not (False).
55+
56+
Output Arguments:
57+
58+
- ``record`` -
59+
60+
- ``fields`` - A dictionary of metadata about the record extracted or
61+
deduced from the header/signal file. If the input record is a
62+
multi-segment record, the output argument will be a list of
63+
dictionaries:
64+
65+
- The first list element will be a dictionary of metadata about the
66+
master header.
67+
- If the record is in variable layout format, the next list element
68+
will be a dictionary of metadata about the layout specification
69+
header.
70+
- The last list element will be a list of dictionaries of metadata
71+
for each segment. For empty segments, the dictionary will be
72+
replaced by a single string: ‘Empty Segment’
73+
74+
75+
Writing Signals
76+
~~~~~~~~~~~~~~~
77+
78+
**wrsamp** - Read a WFDB file and return the signal as a numpy array and
2979
the metadata as a dictionary.
3080

3181
::

‎wfdb/annotations.py

Lines changed: 46 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,26 @@
77

88
# Class for WFDB annotations
99
class Annotation():
10-
10+
"""
11+
The class representing WFDB annotations.
12+
13+
Annotation objects can be created as with any other class, or by reading a WFDB annotation
14+
file with 'rdann'.
15+
16+
The attributes of the Annotation object give information about the annotation as specified
17+
by https://www.physionet.org/physiotools/wag/ <INSERT>:
18+
- annsamp: The annotation location in samples relative to the beginning of the record.
19+
- anntype: The annotation type according the the standard WFDB codes.
20+
- subtype: The marked class/category of the annotation.
21+
- chan: The signal channel associated with the annotations.
22+
- num: The labelled annotation number.
23+
- aux: The auxiliary information string for the annotation.
24+
- fs: The sampling frequency of the record.
25+
26+
Call 'showanncodes()' to see the list of standard annotation codes. Any text used to label
27+
annotations that are not one of the codes go in the 'aux' field rather than the 'anntype'
28+
field.
29+
"""
1130
def __init__(self, recordname, annotator, annsamp, anntype, num = None, subtype = None, chan = None, aux = None, fs = None):
1231
self.recordname = recordname
1332
self.annotator = annotator
@@ -22,6 +41,11 @@ def __init__(self, recordname, annotator, annsamp, anntype, num = None, subtype
2241

2342
# Write an annotation file
2443
def wrann(self):
44+
"""
45+
Instance method to write a WFDB annotation file from an Annotation object.
46+
47+
Example usage:
48+
"""
2549
# Check the validity of individual fields used to write the annotation file
2650
self.checkfields()
2751

@@ -307,36 +331,41 @@ def wrann(recordname, annotator, annsamp, anntype, num = None, subtype = None, c
307331

308332
# Display the annotation symbols and the codes they represent
309333
def showanncodes():
334+
"""
335+
Display the annotation symbols and the codes they represent
336+
337+
Usage: showanncodes()
338+
"""
310339
display(symcodes)
311340

312341
## ------------- Reading Annotations ------------- ##
313342

314343
def rdann(recordname, annotator, sampfrom=0, sampto=None):
315-
""" Read a WFDB annotation file recordname.annot and return the fields as lists or arrays
344+
""" Read a WFDB annotation file recordname.annotator and return the fields as lists or arrays
316345
317-
Usage: annotation = rdann(recordname, annot, sampfrom=0, sampto=[], anndisp=1)
346+
Usage:
347+
annotation = rdann(recordname, annot, sampfrom=0, sampto=None)
318348
319349
Input arguments:
320350
- recordname (required): The record name of the WFDB annotation file. ie. for
321351
file '100.atr', recordname='100'
322352
- annotator (required): The annotator extension of the annotation file. ie. for
323-
file '100.atr', annot='atr'
353+
file '100.atr', annotator='atr'
324354
- sampfrom (default=0): The minimum sample number for annotations to be returned.
325-
- sampto (default=None): The maximum sample number for
326-
annotations to be returned.
355+
- sampto (default=None): The maximum sample number for annotations to be returned.
327356
328357
Output argument:
329-
- annotation: The annotation object with the following fields:
330-
- annsamp: The annotation location in samples relative to the beginning of the record.
331-
- anntype: The annotation type according the the standard WFDB keys.
332-
- subtype: The marked class/category of the annotation.
333-
- chan: The signal channel associated with the annotations.
334-
- num: The labelled annotation number.
335-
- aux: The auxiliary information string for the annotation.
336-
- fs: The sampling frequency written into the annotation file if present.
337-
338-
*NOTE: Every annotation sample contains the 'annsamp' and 'anntype' fields. All
339-
other fields default to 0 or empty if not present.
358+
- annotation: The annotation object. Call help(wfdb.Annotation) for the attribute
359+
descriptions.
360+
361+
Note: For every annotation sample, the annotation file explictly stores the 'annsamp'
362+
and 'anntype' fields but not necessarily the others. When reading annotation files
363+
using this function, fields which are not stored in the file will either take their
364+
default values of 0 or None, or will be carried over from their previous values if any.
365+
366+
Example usage:
367+
import wfdb
368+
ann = wfdb.rdann('100', 'atr', sampto = 300000)
340369
"""
341370

342371
if sampto and sampto <= sampfrom:

‎wfdb/records.py

Lines changed: 56 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,6 @@
1919
# The base WFDB class to extend to create Record and MultiRecord. Contains shared helper functions and fields.
2020
class BaseRecord():
2121
# Constructor
22-
2322
def __init__(self, recordname=None, nsig=None,
2423
fs=None, counterfreq=None, basecounter = None,
2524
siglen = None, basetime = None, basedate = None,
@@ -219,8 +218,8 @@ class Record(BaseRecord, _headers.HeadersMixin, _signals.SignalsMixin):
219218
The attributes of the Record object give information about the record as specified
220219
by https://www.physionet.org/physiotools/wag/header-5.htm
221220
222-
In addition, the d_signals and p_signals attributes represent the digital and physical
223-
signals of WFDB records with at least one channel.
221+
In addition, the d_signals and p_signals attributes store the digital and physical
222+
signals of WFDB records with at least one channel.
224223
"""
225224
# Constructor
226225
def __init__(self, p_signals=None, d_signals=None,
@@ -341,16 +340,18 @@ class MultiRecord(BaseRecord, _headers.MultiHeadersMixin):
341340
MultiRecord objects can be created as with any other class, or by reading a multi-segment
342341
WFDB record using 'rdsamp' with the 'm2s' (multi to single) input parameter set to False.
343342
344-
The attributes of the MultiRecord object give information about the record as specified
343+
The attributes of the MultiRecord object give information about the entire record as specified
345344
by https://www.physionet.org/physiotools/wag/header-5.htm
346345
347346
In addition, the 'segments' parameter is a list of Record objects representing each
348-
individual segment of the entire multi-segment record.
349-
350-
Noteably, the 'multi_to_single' instance method can be called on MultiRecord objects
351-
to return a single segment representation of the record as a Record object. The resulting
352-
Record object will have its 'p_signals' field set.
347+
individual segment, or 'None' representing empty segments, of the entire multi-segment record.
353348
349+
Noteably, this class has no attribute representing the signals as a whole. The 'multi_to_single'
350+
instance method can be called on MultiRecord objects to return a single segment representation
351+
of the record as a Record object. The resulting Record object will have its 'p_signals' field set.
352+
353+
eg. record1 = wfdb.rdsamp('s00001-2896-10-10-00-31', m2s = False)
354+
record1 = record1.multi_to_single()
354355
"""
355356
# Constructor
356357
def __init__(self, segments = None, layout = None,
@@ -669,7 +670,9 @@ def rdsamp(recordname, sampfrom=0, sampto=None, channels = None, physical = True
669670
'srdsamp' returns two arguments: the physical signals array, and a dictionary of a
670671
few select fields, a subset of the original wfdb Record attributes.
671672
672-
Example Usage: record1 = wfdb.rdsamp('macecgdb/test01_00s', sampfrom=800, channels = [1,3])
673+
Example Usage:
674+
import wfdb
675+
record1 = wfdb.rdsamp('macecgdb/test01_00s', sampfrom=800, channels = [1,3])
673676
"""
674677

675678
dirname, baserecordname = os.path.split(recordname)
@@ -822,7 +825,42 @@ def wanted_siginds(wanted_signames, record_signames):
822825
# A simple version of rdsamp for ease of use
823826
# Return the physical signals and a few essential fields
824827
def srdsamp(recordname, sampfrom=0, sampto=None, channels = None):
828+
"""Read a WFDB record and return the signal and record descriptors as attributes in a wfdb.Record object
829+
830+
Usage:
831+
record = rdsamp(recordname, sampfrom=0, sampto=None, channels=None, physical=True, m2s=True)
832+
833+
Input arguments:
834+
- recordname (required): The name of the WFDB record to be read (without any file extensions).
835+
If the argument contains any path delimiter characters, the argument will be interpreted as
836+
PATH/baserecord and the data files will be searched for in the local path.
837+
- sampfrom (default=0): The starting sample number to read for each channel.
838+
- sampto (default=None): The sample number at which to stop reading for each channel.
839+
- channels (default=all): Indices specifying the channel to be returned.
825840
841+
Output arguments:
842+
- signals: A 2d numpy array storing the physical signals from the record.
843+
- fields: A dictionary specifying several key attributes of the read record:
844+
- fs: The sampling frequency of the record
845+
- units: The units for each channel
846+
- signame: The signal name for each channel
847+
- comments: Any comments written in the header
848+
849+
Note: If a signal range or channel selection is specified when calling this function, the
850+
the resulting attributes of the returned object will be set to reflect the section
851+
of the record that is actually read, rather than necessarily what is in the header file.
852+
For example, if channels = [0, 1, 2] is specified when reading a 12 channel record, the
853+
'nsig' attribute will be 3, not 12.
854+
855+
Note: The 'rdsamp' function exists as a simple alternative to 'rdsamp' for the most common
856+
purpose of extracting the physical signals and a few important descriptor fields.
857+
'srdsamp' returns two arguments: the physical signals array, and a dictionary of a
858+
few select fields, a subset of the original wfdb Record attributes.
859+
860+
Example Usage:
861+
import wfdb
862+
sig, fields = wfdb.srdsamp('macecgdb/test01_00s', sampfrom=800, channels = [1,3])
863+
"""
826864
record = rdsamp(recordname, sampfrom, sampto, channels, True, True)
827865

828866
signals = record.p_signals
@@ -835,12 +873,18 @@ def srdsamp(recordname, sampfrom=0, sampto=None, channels = None):
835873
#------------------- /Reading Records -------------------#
836874

837875

838-
# Simple function for single segment wrsamp
839-
def wrsamp(recordname, fs, units, signames, p_signals = None, d_signals = None, fmt = None, comments= None):
876+
# Function for writing single segment records
877+
def wrsamp(recordname, fs, units, signames, p_signals = None, d_signals = None,
878+
fmt = None, gain = None, baseline = None, comments= None):
879+
"""
840880
881+
"""
841882
# Check input field combinations
842883
if p_signals is not None and d_signals is not None:
843884
sys.exit('Must only give one of the inputs: p_signals or d_signals')
885+
if d_signals is not none:
886+
if fmt is None or gain is None or baseline is None:
887+
sys.exit("When using d_signals, must also specify 'fmt', 'gain', and 'baseline' fields.")
844888

845889
# Create the Record object
846890
record = Record(recordname = recordname, p_signals = p_signals, fs = fs, fmt = fmt, units = units, signame = signames, comments = comments)

0 commit comments

Comments
 (0)