Skip to content

Commit 83139ab

Browse files
cx1111cx1111
committed
updating doc
1 parent 5cb3632 commit 83139ab

File tree

8 files changed

+175
-388
lines changed

8 files changed

+175
-388
lines changed

‎README.rst

+17-329
Original file line numberDiff line numberDiff line change
@@ -9,355 +9,43 @@ wfdb-python
99
Introduction
1010
------------
1111

12-
Native python scripts for reading and writing WFDB signals and annotations. Package to be expanded with other useful functionalities.
12+
The native Python waveform-database (WFDB) package. A library of tools for reading and writing WFDB signals and annotations, and general physiological signal processing.
1313

14+
Core components of this package are based on the original WFDB specifications:
15+
16+
| `WFDB Software Package`_
17+
| `WFDB Applications Guide`_
18+
| `WFDB Header Specifications`_
19+
| `WFDB Signal Specifications`_
20+
| `WFDB Annotation Specifications`_
1421
1522
Installation
1623
------------
1724

18-
The distribution is hosted on pypi and directly installable via pip without needing clone or download this repository. Note that the pypi package does not contain the demo scripts or the example data. To install the package from pypi, run from your terminal:
25+
The distribution is hosted on pypi at: https://pypi.python.org/pypi/wfdb/ and directly installable via pip without needing clone or download this repository. Note that the pypi package does not contain the demo scripts or the example data. To install the package from pypi, run from your terminal:
1926
``pip install wfdb``
2027

21-
Download or clone this repository https://github.com/MIT-LCP/wfdb-python for the latest development version, the demo scripts, and the example data. To install the downloaded package, change directory into the base directory of the repository and run:
28+
Download or clone this repository: https://github.com/MIT-LCP/wfdb-python for the latest development version, the demo scripts, and the example data. To install the downloaded package, navigate to the base directory of the repository and run:
2229
``pip install .``
2330

2431

25-
Usage
26-
-----
27-
28-
See the **demo.ipynb** file for example cases.
29-
30-
31-
32-
Converting between Analog and Digital Values
33-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
34-
35-
When reading signal sample values into ``record`` objects using ``rdsamp``, the samples are stored in either the ``p_signals`` or the ``d_signal`` field depending on the specified return type (``physical`` = ``True`` or ``False`` respectively).
36-
37-
One can also use existing objects to obtain physical values from digital values and vice versa, without having to re-read the wfdb file with a different set of options. The two following instance methods perform the conversions.
38-
39-
40-
**adc** - Performs analogue to digital conversion of the physical signal stored in p_signals if expanded is False, or e_p_signals if expanded is True. The p_signals/e_p_signals, fmt, gain, and baseline fields must all be valid. If inplace is True, the adc will be performed inplace on the variable, the d_signal/e_d_signal attribute will be set, and the p_signals/e_p_signals field will be set to None.
41-
42-
::
43-
44-
record.adc(self, expanded=False, inplace=False)
45-
46-
Input arguments:
47-
48-
- ``expanded`` (default=False): Boolean specifying whether to transform the e_p_signals attribute (True) or the p_signals attribute (False).
49-
- ``inplace`` (default=False): Boolean specifying whether to automatically set the object's corresponding digital signal attribute and set the physical signal attribute to None (True), or to return the converted signal as a separate variable without changing the original physical signal attribute (False).
50-
51-
Possible output argument:
52-
53-
- ``d_signal``: The digital conversion of the signal. Either a 2d numpy array or a list of 1d numpy arrays.
54-
55-
Example Usage:
56-
57-
::
58-
59-
import wfdb
60-
record = wfdb.rdsamp('sampledata/100')
61-
d_signal = record.adc()
62-
record.adc(inplace=True)
63-
record.dac(inplace=True)
64-
65-
66-
**dac** - Performs digital to analogue conversion of the digital signal stored in d_signal if expanded is False, or e_d_signal if expanded is True. The d_signal/e_d_signal, fmt, gain, and baseline fields must all be valid. If inplace is True, the dac will be performed inplace on the variable, the p_signals/e_p_signals attribute will be set, and the d_signal/e_d_signal field will be set to None.
67-
68-
::
69-
70-
record.dac(self, expanded=False, inplace=False)
71-
72-
Input arguments:
73-
74-
- ``expanded`` (default=False): Boolean specifying whether to transform the e_d_signal attribute (True) or the d_signal attribute (False).
75-
- ``inplace`` (default=False): Boolean specifying whether to automatically set the object's corresponding physical signal attribute and set the digital signal attribute to None (True), or to return the converted signal as a separate variable without changing the original digital signal attribute (False).
76-
77-
Possible output argument:
78-
79-
- ``p_signals``: The physical conversion of the signal. Either a 2d numpy array or a list of 1d numpy arrays.
80-
81-
Example Usage:
82-
83-
::
84-
85-
import wfdb
86-
record = wfdb.rdsamp('sampledata/100', physical=False)
87-
p_signal = record.dac()
88-
record.dac(inplace=True)
89-
record.adc(inplace=True)
90-
91-
92-
93-
94-
95-
96-
97-
98-
99-
100-
101-
102-
103-
104-
105-
106-
Signal Processing
107-
-----------------
108-
109-
Basic Functionalities
110-
~~~~~~~~~~~~~~~~~~~~~
111-
112-
**resample_sig** - Resample a single-channel signal
113-
114-
::
115-
116-
resample_sig(x, fs, fs_target)
117-
118-
Example Usage:
119-
120-
::
121-
122-
import wfdb
123-
sig, fields = wfdb.srdsamp('sampledata/100', sampto=10000)
124-
x, _ = wfdb.processing.resample_sig(x=sig[:,0], fs=fields['fs'], fs_target=128)
125-
126-
Input arguments:
127-
128-
- ``x`` (required): The signal.
129-
- ``fs`` (required): The signal frequency.
130-
- ``fs_target`` (required): The target signal frequency.
131-
132-
133-
**resample_singlechan** - Resample a single-channel signal and its annotation.
134-
135-
::
136-
137-
resample_singlechan(x, ann, fs, fs_target)
138-
139-
Example Usage:
140-
141-
::
142-
143-
import wfdb
144-
sig, fields = wfdb.srdsamp('sampledata/100')
145-
ann = wfdb.rdann('sampledata/100', 'atr')
146-
new_sig, new_ann = wfdb.processing.resample_singlechan(x=sig[:, 0], ann=ann, fs=fields['fs'], fs_target=50)
147-
148-
Input arguments:
149-
150-
- ``x`` (required): The signal.
151-
- ``ann`` (required): The signal Annotation.
152-
- ``fs`` (required): The signal frequency.
153-
- ``fs_target`` (required): The target signal frequency.
154-
155-
156-
157-
**resample_multichan** - Resample a multi-channel signal and its annotation.
158-
159-
::
32+
Documentation and Usage
33+
-----------------------
16034

161-
resample_multichan(sig, ann, fs, fs_target)
35+
See the documentation site for public classes and functions.
16236

163-
Example Usage:
37+
See the **demo.ipynb** file for example use cases.
16438

165-
::
16639

167-
import wfdb
168-
sig, fields = wfdb.srdsamp('sampledata/100')
169-
ann = wfdb.rdann('sampledata/100', 'atr')
170-
new_sig, new_ann = wfdb.processing.resample_multichan(sig=sig, ann=ann, fs=fields['fs'], fs_target=50)
17140

172-
Input arguments:
17341

174-
- ``x`` (required): The signal.
175-
- ``ann`` (required): The signal Annotation.
176-
- ``fs`` (required): The signal frequency.
177-
- ``fs_target`` (required): The target signal frequency.
17842

17943

180-
181-
**normalize** - Resizes a signal between a lower and upper bound
182-
183-
::
184-
185-
normalize(x, lb=0, ub=1)
186-
187-
Example Usage:
188-
189-
::
190-
191-
import wfdb
192-
sig, _ = wfdb.srdsamp('sampledata/100')
193-
x = wfdb.processing.normalize(x=sig[:, 0], lb=-2, ub=15)
194-
195-
Input arguments:
196-
197-
- ``x`` (required): The signal.
198-
- ``lb`` (required): The lower bound.
199-
- ``ub`` (required): The upper bound.
200-
201-
202-
203-
**smooth** - Signal smoothing
204-
205-
::
206-
207-
smooth(x, window_size)
208-
209-
Example Usage:
210-
211-
::
212-
213-
import wfdb
214-
sig, _ = wfdb.srdsamp('sampledata/100')
215-
x = smooth(x=sig[:,0], window_size=150)
216-
217-
Input arguments:
218-
219-
- ``x`` (required): The signal.
220-
- ``window_size`` (required): The smoothing window width.
221-
222-
223-
Peak Detection
224-
~~~~~~~~~~~~~~
225-
226-
**gqrs_detect** - The GQRS detector function
227-
228-
::
229-
230-
gqrs_detect(x, fs, adcgain, adczero, threshold=1.0, hr=75, RRdelta=0.2,
231-
RRmin=0.28, RRmax=2.4, QS=0.07, QT=0.35, RTmin=0.25, RTmax=0.33,
232-
QRSa=750, QRSamin=130):
233-
234-
Example Usage:
235-
236-
::
237-
238-
import wfdb
239-
t0 = 10000
240-
tf = 20000
241-
record = wfdb.rdsamp("sampledata/100", sampfrom=t0, sampto=tf, channels=[0])
242-
d_signal = record.adc()[:,0]
243-
peak_indices = wfdb.processing.gqrs_detect(x=d_signal, fs=record.fs, adcgain=record.adcgain[0], adczero=record.adczero[0], threshold=1.0)
244-
245-
Input arguments:
246-
247-
- ``x`` (required): The digital signal as a numpy array
248-
- ``fs`` (required): The sampling frequency of the signal
249-
- ``adcgain``: The gain of the signal (the number of adus (q.v.) per physical unit)
250-
- ``adczero`` (required): The value produced by the ADC given a 0 volt input.
251-
- ``threshold`` (default=1.0): The threshold for detection
252-
- ``hr`` (default=75): Typical heart rate, in beats per minute
253-
- ``RRdelta`` (default=0.2): Typical difference between successive RR intervals in seconds
254-
- ``RRmin`` (default=0.28): Minimum RR interval ("refractory period"), in seconds
255-
- ``RRmax`` (default=2.4): Maximum RR interval, in seconds; thresholds will be adjusted if no peaks are detected within this interval
256-
- ``QS`` (default=0.07): Typical QRS duration, in seconds
257-
- ``QT`` (default=0.35): Typical QT interval, in seconds
258-
- ``RTmin`` (default=0.25): Minimum interval between R and T peaks, in seconds
259-
- ``RTmax`` (default=0.33): Maximum interval between R and T peaks, in seconds
260-
- ``QRSa`` (default=750): Typical QRS peak-to-peak amplitude, in microvolts
261-
- ``QRSamin`` (default=130): Minimum QRS peak-to-peak amplitude, in microvolts
262-
263-
Output Arguments:
264-
265-
- ``peak_indices``: A python list containing the peak indices.
266-
267-
268-
**correct_peaks** - A post-processing algorithm to correct peaks position.
269-
270-
See code comments for details about the algorithm.
271-
272-
273-
::
274-
275-
correct_peaks(x, peak_indices, min_gap, max_gap, smooth_window)
276-
277-
Input arguments:
278-
279-
- ``x`` (required): The signal.
280-
- ``peak_indices`` (required): The location of the peaks.
281-
- ``min_gap`` (required): The minimum gap in samples between two peaks.
282-
- ``max_gap`` (required): The maximum gap in samples between two peaks.
283-
- ``smooth_window`` (required): The size of the smoothing window.
284-
285-
Output Arguments:
286-
287-
- ``new_indices``: A python list containing the new peaks indices.
288-
289-
290-
Example Usage:
291-
292-
::
293-
294-
import wfdb
295-
t0 = 10000
296-
tf = 20000
297-
record = wfdb.rdsamp('sampledata/100', sampfrom=t0, sampto=tf, channels=[0])
298-
d_signal = record.adc()[:,0]
299-
peak_indices = wfdb.processing.gqrs_detect(d_signal, fs=record.fs,
300-
adcgain=record.adcgain[0],
301-
adczero=record.adczero[0],
302-
threshold=1.0)
303-
min_bpm = 10
304-
max_bpm = 350
305-
min_gap = record.fs*60/min_bpm
306-
max_gap = record.fs*60/max_bpm
307-
new_indices = wfdb.processing.correct_peaks(d_signal, peak_indices=peak_indices,
308-
min_gap=min_gap, max_gap=max_gap,
309-
smooth_window=150)
310-
311-
312-
Heart Rate
313-
~~~~~~~~~~~~~~
314-
315-
**compute_hr** - Compute instantaneous heart rate from peak indices and signal frequency.
316-
317-
::
318-
319-
compute_hr(siglen, peak_indices, fs)
320-
321-
Input arguments:
322-
323-
- ``siglen`` (required): The length of the corresponding signal.
324-
- ``peak_indices`` (required): The peak indices.
325-
- ``fs`` (required): The corresponding signal's sampling frequency.
326-
327-
328-
Output Arguments:
329-
330-
- ``hr``: A numpy array of the instantaneous heart rate, with the length of the corresponding signal. Contains numpy.nan where heart rate could not be computed.
331-
332-
333-
Example Usage:
334-
335-
::
336-
337-
import wfdb
338-
t0 = 10000
339-
tf = 20000
340-
record = wfdb.rdsamp("sampledata/100", sampfrom=t0, sampto=tf, channels=[0])
341-
peak_indices = wfdb.processing.gqrs_detect(record.adc(), fs=record.fs,
342-
adcgain=record.adcgain[0],
343-
adczero=record.adczero[0],
344-
threshold=1.0)
345-
hr = wfdb.processing.compute_hr(siglen=tf-t0, peak_indices=peak_indices, fs=record.fs)
346-
347-
348-
349-
350-
Based on the original WFDB software package specifications
351-
----------------------------------------------------------
352-
353-
| `WFDB Software Package`_
354-
| `WFDB Applications Guide`_
355-
| `WFDB Header File Specifications`_
356-
35744
.. _WFDB Software Package: http://physionet.org/physiotools/wfdb.shtml
35845
.. _WFDB Applications Guide: http://physionet.org/physiotools/wag/
359-
.. _WFDB Header File Specifications: https://physionet.org/physiotools/wag/header-5.htm
360-
46+
.. _WFDB Header Specifications: https://physionet.org/physiotools/wag/header-5.htm
47+
.. _WFDB Signal Specifications: https://physionet.org/physiotools/wag/signal-5.htm
48+
.. _WFDB Annotation Specifications: https://physionet.org/physiotools/wag/annot-5.htm
36149

36250
.. |Build Status| image:: https://travis-ci.org/MIT-LCP/wfdb-python.svg?branch=master
36351
:target: https://travis-ci.org/MIT-LCP/wfdb-python

‎docs/conf.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -55,9 +55,9 @@
5555
# built documents.
5656
#
5757
# The short X.Y version.
58-
version = '1.3.9'
58+
version = '2.0.0'
5959
# The full version, including alpha/beta/rc tags.
60-
release = '1.3.9'
60+
release = '2.0.0'
6161

6262
# The language for content autogenerated by Sphinx. Refer to documentation
6363
# for a list of supported languages.

0 commit comments

Comments
 (0)