biosppy.signals¶
This subpackage provides methods to process common physiological signals (biosignals).
Modules¶
biosppy.signals.bvp¶
This module provides methods to process Blood Volume Pulse (BVP) signals.
copyright: 


license:  BSD 3clause, see LICENSE for more details. 

biosppy.signals.bvp.
bvp
(signal=None, sampling_rate=1000.0, show=True)¶ Process a raw BVP signal and extract relevant signal features using default parameters.
Parameters:  signal (array) – Raw BVP signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 show (bool, optional) – If True, show a summary plot.
Returns:  ts (array) – Signal time axis reference (seconds).
 filtered (array) – Filtered BVP signal.
 onsets (array) – Indices of BVP pulse onsets.
 heart_rate_ts (array) – Heart rate time axis reference (seconds).
 heart_rate (array) – Instantaneous heart rate (bpm).

biosppy.signals.bvp.
find_onsets
(signal=None, sampling_rate=1000.0, sm_size=None, size=None, alpha=2.0, wrange=None, d1_th=0, d2_th=None)¶ Determine onsets of BVP pulses.
Skips corrupted signal parts. Based on the approach by Zong et al. [Zong03].
Parameters:  signal (array) – Input filtered BVP signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 sm_size (int, optional) – Size of smoother kernel (seconds). Defaults to 0.25
 size (int, optional) – Window to search for maxima (seconds). Defaults to 5
 alpha (float, optional) – Normalization parameter. Defaults to 2.0
 wrange (int, optional) – The window in which to search for a peak (seconds). Defaults to 0.1
 d1_th (int, optional) – Smallest allowed difference between maxima and minima. Defaults to 0
 d2_th (int, optional) – Smallest allowed time between maxima and minima (seconds), Defaults to 0.15
Returns: onsets (array) – Indices of BVP pulse onsets.
References
[Zong03] W Zong, T Heldt, GB Moody and RG Mark, “An Opensource Algorithm to Detect Onset of Arterial Blood Pressure Pulses”, IEEE Comp. in Cardiology, vol. 30, pp. 259262, 2003
biosppy.signals.ecg¶
This module provides methods to process Electrocardiographic (ECG) signals. Implemented code assumes a singlechannel Lead I like ECG signal.
copyright: 


license:  BSD 3clause, see LICENSE for more details. 

biosppy.signals.ecg.
christov_segmenter
(signal=None, sampling_rate=1000.0)¶ ECG Rpeak segmentation algorithm.
Follows the approach by Christov [Chri04].
Parameters:  signal (array) – Input filtered ECG signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
Returns: rpeaks (array) – Rpeak location indices.
References
[Chri04] Ivaylo I. Christov, “Real time electrocardiogram QRS detection using combined adaptive threshold”, BioMedical Engineering OnLine 2004, vol. 3:28, 2004

biosppy.signals.ecg.
compare_segmentation
(reference=None, test=None, sampling_rate=1000.0, offset=0, minRR=None, tol=0.05)¶ Compare the segmentation performance of a list of Rpeak positions against a reference list.
Parameters:  reference (array) – Reference Rpeak location indices.
 test (array) – Test Rpeak location indices.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 offset (int, optional) – Constant a priori offset (number of samples) between reference and test Rpeak locations.
 minRR (float, optional) – Minimum admissible RR interval (seconds).
 tol (float, optional) – Tolerance between corresponding reference and test Rpeak locations (seconds).
Returns:  TP (int) – Number of true positive Rpeaks.
 FP (int) – Number of false positive Rpeaks.
 performance (float) – Test performance; TP / len(reference).
 acc (float) – Accuracy rate; TP / (TP + FP).
 err (float) – Error rate; FP / (TP + FP).
 match (list) – Indices of the elements of ‘test’ that match to an Rpeak from ‘reference’.
 deviation (array) – Absolute errors of the matched Rpeaks (seconds).
 mean_deviation (float) – Mean error (seconds).
 std_deviation (float) – Standard deviation of error (seconds).
 mean_ref_ibi (float) – Mean of the reference interbeat intervals (seconds).
 std_ref_ibi (float) – Standard deviation of the reference interbeat intervals (seconds).
 mean_test_ibi (float) – Mean of the test interbeat intervals (seconds).
 std_test_ibi (float) – Standard deviation of the test interbeat intervals (seconds).

biosppy.signals.ecg.
correct_rpeaks
(signal=None, rpeaks=None, sampling_rate=1000.0, tol=0.05)¶ Correct Rpeak locations to the maximum within a tolerance.
Parameters:  signal (array) – ECG signal.
 rpeaks (array) – Rpeak location indices.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 tol (int, float, optional) – Correction tolerance (seconds).
Returns: rpeaks (array) – Cerrected Rpeak location indices.
Notes
 The tolerance is defined as the time interval .

biosppy.signals.ecg.
ecg
(signal=None, sampling_rate=1000.0, show=True)¶ Process a raw ECG signal and extract relevant signal features using default parameters.
Parameters:  signal (array) – Raw ECG signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 show (bool, optional) – If True, show a summary plot.
Returns:  ts (array) – Signal time axis reference (seconds).
 filtered (array) – Filtered ECG signal.
 rpeaks (array) – Rpeak location indices.
 templates_ts (array) – Templates time axis reference (seconds).
 templates (array) – Extracted heartbeat templates.
 heart_rate_ts (array) – Heart rate time axis reference (seconds).
 heart_rate (array) – Instantaneous heart rate (bpm).

biosppy.signals.ecg.
engzee_segmenter
(signal=None, sampling_rate=1000.0, threshold=0.48)¶ ECG Rpeak segmentation algorithm.
Follows the approach by Engelse and Zeelenberg [EnZe79] with the modifications by Lourenco et al. [LSLL12].
Parameters:  signal (array) – Input filtered ECG signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 threshold (float, optional) – Detection threshold.
Returns: rpeaks (array) – Rpeak location indices.
References
[EnZe79] W. Engelse and C. Zeelenberg, “A single scan algorithm for QRS detection and feature extraction”, IEEE Comp. in Cardiology, vol. 6, pp. 3742, 1979 [LSLL12] A. Lourenco, H. Silva, P. Leite, R. Lourenco and A. Fred, “Real Time Electrocardiogram Segmentation for Finger Based ECG Biometrics”, BIOSIGNALS 2012, pp. 4954, 2012

biosppy.signals.ecg.
extract_heartbeats
(signal=None, rpeaks=None, sampling_rate=1000.0, before=0.2, after=0.4)¶ Extract heartbeat templates from an ECG signal, given a list of Rpeak locations.
Parameters:  signal (array) – Input ECG signal.
 rpeaks (array) – Rpeak location indices.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 before (float, optional) – Window size to include before the R peak (seconds).
 after (int, optional) – Window size to include after the R peak (seconds).
Returns:  templates (array) – Extracted heartbeat templates.
 rpeaks (array) – Corresponding Rpeak location indices of the extracted heartbeat templates.

biosppy.signals.ecg.
gamboa_segmenter
(signal=None, sampling_rate=1000.0, tol=0.002)¶ ECG Rpeak segmentation algorithm.
Follows the approach by Gamboa.
Parameters:  signal (array) – Input filtered ECG signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 tol (float, optional) – Tolerance parameter.
Returns: rpeaks (array) – Rpeak location indices.

biosppy.signals.ecg.
hamilton_segmenter
(signal=None, sampling_rate=1000.0)¶ ECG Rpeak segmentation algorithm.
Follows the approach by Hamilton [Hami02].
Parameters:  signal (array) – Input filtered ECG signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
Returns: rpeaks (array) – Rpeak location indices.
References
[Hami02] P.S. Hamilton, “Open Source ECG Analysis Software Documentation”, E.P.Limited, 2002

biosppy.signals.ecg.
ssf_segmenter
(signal=None, sampling_rate=1000.0, threshold=20, before=0.03, after=0.01)¶ ECG Rpeak segmentation based on the Slope Sum Function (SSF).
Parameters:  signal (array) – Input filtered ECG signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 threshold (float, optional) – SSF threshold.
 before (float, optional) – Search window size before Rpeak candidate (seconds).
 after (float, optional) – Search window size after Rpeak candidate (seconds).
Returns: rpeaks (array) – Rpeak location indices.
biosppy.signals.eda¶
This module provides methods to process Electrodermal Activity (EDA) signals, also known as Galvanic Skin Response (GSR).
copyright: 


license:  BSD 3clause, see LICENSE for more details. 

biosppy.signals.eda.
basic_scr
(signal=None, sampling_rate=1000.0)¶ Basic method to extract Skin Conductivity Responses (SCR) from an EDA signal.
Follows the approach in [Gamb08].
Parameters:  signal (array) – Input filterd EDA signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
Returns:  onsets (array) – Indices of the SCR onsets.
 peaks (array) – Indices of the SRC peaks.
 amplitudes (array) – SCR pulse amplitudes.
References
[Gamb08] Hugo Gamboa, “Multimodal Behavioral Biometrics Based on HCI and Electrophysiology”, PhD thesis, Instituto Superior T{‘e}cnico, 2008

biosppy.signals.eda.
eda
(signal=None, sampling_rate=1000.0, show=True, min_amplitude=0.1)¶ Process a raw EDA signal and extract relevant signal features using default parameters.
Parameters:  signal (array) – Raw EDA signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 show (bool, optional) – If True, show a summary plot.
 min_amplitude (float, optional) – Minimum treshold by which to exclude SCRs.
Returns:  ts (array) – Signal time axis reference (seconds).
 filtered (array) – Filtered EDA signal.
 onsets (array) – Indices of SCR pulse onsets.
 peaks (array) – Indices of the SCR peaks.
 amplitudes (array) – SCR pulse amplitudes.

biosppy.signals.eda.
kbk_scr
(signal=None, sampling_rate=1000.0, min_amplitude=0.1)¶ KBK method to extract Skin Conductivity Responses (SCR) from an EDA signal.
Follows the approach by Kim et al. [KiBK04].
Parameters:  signal (array) – Input filterd EDA signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 min_amplitude (float, optional) – Minimum treshold by which to exclude SCRs.
Returns:  onsets (array) – Indices of the SCR onsets.
 peaks (array) – Indices of the SRC peaks.
 amplitudes (array) – SCR pulse amplitudes.
References
[KiBK04] K.H. Kim, S.W. Bang, and S.R. Kim, “Emotion recognition system using shortterm monitoring of physiological signals”, Med. Biol. Eng. Comput., vol. 42, pp. 419427, 2004
biosppy.signals.eeg¶
This module provides methods to process Electroencephalographic (EEG) signals.
copyright: 


license:  BSD 3clause, see LICENSE for more details. 

biosppy.signals.eeg.
car_reference
(signal=None)¶ Change signal reference to the Common Average Reference (CAR).
Parameters: signal (array) – Input EEG signal matrix; each column is one EEG channel. Returns: signal (array) – Rereferenced EEG signal matrix; each column is one EEG channel.

biosppy.signals.eeg.
eeg
(signal=None, sampling_rate=1000.0, labels=None, show=True)¶ Process raw EEG signals and extract relevant signal features using default parameters.
Parameters:  signal (array) – Raw EEG signal matrix; each column is one EEG channel.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 labels (list, optional) – Channel labels.
 show (bool, optional) – If True, show a summary plot.
Returns:  ts (array) – Signal time axis reference (seconds).
 filtered (array) – Filtered BVP signal.
 features_ts (array) – Features time axis reference (seconds).
 theta (array) – Average power in the 4 to 8 Hz frequency band; each column is one EEG channel.
 alpha_low (array) – Average power in the 8 to 10 Hz frequency band; each column is one EEG channel.
 alpha_high (array) – Average power in the 10 to 13 Hz frequency band; each column is one EEG channel.
 beta (array) – Average power in the 13 to 25 Hz frequency band; each column is one EEG channel.
 gamma (array) – Average power in the 25 to 40 Hz frequency band; each column is one EEG channel.
 plf_pairs (list) – PLF pair indices.
 plf (array) – PLF matrix; each column is a channel pair.

biosppy.signals.eeg.
get_plf_features
(signal=None, sampling_rate=1000.0, size=0.25, overlap=0.5)¶ Extract PhaseLocking Factor (PLF) features from EEG signals between all channel pairs.
Parameters:  signal (array) – Filtered EEG signal matrix; each column is one EEG channel.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 size (float, optional) – Window size (seconds).
 overlap (float, optional) – Window overlap (0 to 1).
Returns:  ts (array) – Features time axis reference (seconds).
 plf_pairs (list) – PLF pair indices.
 plf (array) – PLF matrix; each column is a channel pair.

biosppy.signals.eeg.
get_power_features
(signal=None, sampling_rate=1000.0, size=0.25, overlap=0.5)¶ Extract band power features from EEG signals.
Computes the average signal power, with overlapping windows, in typical EEG frequency bands: * Theta: from 4 to 8 Hz, * Lower Alpha: from 8 to 10 Hz, * Higher Alpha: from 10 to 13 Hz, * Beta: from 13 to 25 Hz, * Gamma: from 25 to 40 Hz.
Parameters:  array (signal) – Filtered EEG signal matrix; each column is one EEG channel.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 size (float, optional) – Window size (seconds).
 overlap (float, optional) – Window overlap (0 to 1).
Returns:  ts (array) – Features time axis reference (seconds).
 theta (array) – Average power in the 4 to 8 Hz frequency band; each column is one EEG channel.
 alpha_low (array) – Average power in the 8 to 10 Hz frequency band; each column is one EEG channel.
 alpha_high (array) – Average power in the 10 to 13 Hz frequency band; each column is one EEG channel.
 beta (array) – Average power in the 13 to 25 Hz frequency band; each column is one EEG channel.
 gamma (array) – Average power in the 25 to 40 Hz frequency band; each column is one EEG channel.
biosppy.signals.emg¶
This module provides methods to process Electromyographic (EMG) signals.
copyright: 


license:  BSD 3clause, see LICENSE for more details. 

biosppy.signals.emg.
abbink_onset_detector
(signal=None, rest=None, sampling_rate=1000.0, size=None, alarm_size=None, threshold=None, transition_threshold=None)¶ Determine onsets of EMG pulses.
Follows the approach by Abbink et al.. [Abb98].
Parameters:  signal (array) – Input filtered EMG signal.
 rest (array, list, dict) – One of the following 3 options: * Ndimensional array with filtered samples corresponding to a rest period; * 2D array or list with the beginning and end indices of a segment of the signal corresponding to a rest period; * Dictionary with {‘mean’: mean value, ‘std_dev’: standard variation}.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 size (int) – Detection window size (seconds).
 alarm_size (int) – Number of amplitudes searched in the calculation of the transition index.
 threshold (int, float) – Detection threshold.
 transition_threshold (int, float) – Threshold used in the calculation of the transition index.
Returns:  onsets (array) – Indices of EMG pulse onsets.
 processed (array) – Processed EMG signal.
References
[Abb98] Abbink JH, van der Bilt A, van der Glas HW, “Detection of onset and termination of muscle activity in surface electromyograms”, Journal of Oral Rehabilitation, vol. 25, pp. 365–369, 1998

biosppy.signals.emg.
bonato_onset_detector
(signal=None, rest=None, sampling_rate=1000.0, threshold=None, active_state_duration=None, samples_above_fail=None, fail_size=None)¶ Determine onsets of EMG pulses.
Follows the approach by Bonato et al. [Bo98].
Parameters:  signal (array) – Input filtered EMG signal.
 rest (array, list, dict) – One of the following 3 options: * Ndimensional array with filtered samples corresponding to a rest period; * 2D array or list with the beginning and end indices of a segment of the signal corresponding to a rest period; * Dictionary with {‘mean’: mean value, ‘std_dev’: standard variation}.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 threshold (int, float) – Detection threshold.
 active_state_duration (int) – Minimum duration of the active state.
 samples_above_fail (int) – Number of samples above the threshold level in a group of successive samples.
 fail_size (int) – Number of successive samples.
Returns:  onsets (array) – Indices of EMG pulse onsets.
 processed (array) – Processed EMG signal.
References
[Bo98] Bonato P, D’Alessio T, Knaflitz M, “A statistical method for the measurement of muscle activation intervals from surface myoelectric signal during gait”, IEEE Transactions on Biomedical Engineering, vol. 45:3, pp. 287–299, 1998

biosppy.signals.emg.
emg
(signal=None, sampling_rate=1000.0, show=True)¶ Process a raw EMG signal and extract relevant signal features using default parameters.
Parameters:  signal (array) – Raw EMG signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 show (bool, optional) – If True, show a summary plot.
Returns:  ts (array) – Signal time axis reference (seconds).
 filtered (array) – Filtered EMG signal.
 onsets (array) – Indices of EMG pulse onsets.

biosppy.signals.emg.
find_onsets
(signal=None, sampling_rate=1000.0, size=0.05, threshold=None)¶ Determine onsets of EMG pulses.
Skips corrupted signal parts.
Parameters:  signal (array) – Input filtered EMG signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 size (float, optional) – Detection window size (seconds).
 threshold (float, optional) – Detection threshold.
Returns: onsets (array) – Indices of EMG pulse onsets.

biosppy.signals.emg.
hodges_bui_onset_detector
(signal=None, rest=None, sampling_rate=1000.0, size=None, threshold=None)¶ Determine onsets of EMG pulses.
Follows the approach by Hodges and Bui [HoBu96].
Parameters:  signal (array) – Input filtered EMG signal.
 rest (array, list, dict) – One of the following 3 options: * Ndimensional array with filtered samples corresponding to a rest period; * 2D array or list with the beginning and end indices of a segment of the signal corresponding to a rest period; * Dictionary with {‘mean’: mean value, ‘std_dev’: standard variation}.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 size (int) – Detection window size (seconds).
 threshold (int, float) – Detection threshold.
Returns:  onsets (array) – Indices of EMG pulse onsets.
 processed (array) – Processed EMG signal.
References
[HoBu96] Hodges PW, Bui BH, “A comparison of computerbased methods for the determination of onset of muscle contraction using electromyography”, Electroencephalography and Clinical Neurophysiology  Electromyography and Motor Control, vol. 101:6, pp. 511519, 1996

biosppy.signals.emg.
lidierth_onset_detector
(signal=None, rest=None, sampling_rate=1000.0, size=None, threshold=None, active_state_duration=None, fail_size=None)¶ Determine onsets of EMG pulses.
Follows the approach by Lidierth. [Li86].
Parameters:  signal (array) – Input filtered EMG signal.
 rest (array, list, dict) – One of the following 3 options: * Ndimensional array with filtered samples corresponding to a rest period; * 2D array or list with the beginning and end indices of a segment of the signal corresponding to a rest period; * Dictionary with {‘mean’: mean value, ‘std_dev’: standard variation}.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 size (int) – Detection window size (seconds).
 threshold (int, float) – Detection threshold.
 active_state_duration (int) – Minimum duration of the active state.
 fail_size (int) – Number of successive samples.
Returns:  onsets (array) – Indices of EMG pulse onsets.
 processed (array) – Processed EMG signal.
References
[Li86] Lidierth M, “A computer based method for automated measurement of the periods of muscular activity from an EMG and its application to locomotor EMGs”, ElectroencephClin Neurophysiol, vol. 64:4, pp. 378–380, 1986

biosppy.signals.emg.
londral_onset_detector
(signal=None, rest=None, sampling_rate=1000.0, size=None, threshold=None, active_state_duration=None)¶ Determine onsets of EMG pulses.
Follows the approach by Londral et al. [Lon13].
Parameters:  signal (array) – Input filtered EMG signal.
 rest (array, list, dict) – One of the following 3 options: * Ndimensional array with filtered samples corresponding to a rest period; * 2D array or list with the beginning and end indices of a segment of the signal corresponding to a rest period; * Dictionary with {‘mean’: mean value, ‘std_dev’: standard variation}.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 size (int) – Detection window size (seconds).
 threshold (int, float) – Scale factor for calculating the detection threshold.
 active_state_duration (int) – Minimum duration of the active state.
Returns:  onsets (array) – Indices of EMG pulse onsets.
 processed (array) – Processed EMG signal.
References
[Lon13] Londral A, Silva H, Nunes N, Carvalho M, Azevedo L, “A wireless usercomputer interface to explore various sources of biosignals and visual biofeedback for severe motor impairment”, Journal of Accessibility and Design for All, vol. 3:2, pp. 118–134, 2013

biosppy.signals.emg.
silva_onset_detector
(signal=None, sampling_rate=1000.0, size=None, threshold_size=None, threshold=None)¶ Determine onsets of EMG pulses.
Follows the approach by Silva et al. [Sil12].
Parameters:  signal (array) – Input filtered EMG signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 size (int) – Detection window size (seconds).
 threshold_size (int) – Window size for calculation of the adaptive threshold; must be bigger than the detection window size.
 threshold (int, float) – Fixed threshold for the double criteria.
Returns:  onsets (array) – Indices of EMG pulse onsets.
 processed (array) – Processed EMG signal.
References
[Sil12] Silva H, Scherer R, Sousa J, Londral A , “Towards improving the usability of electromyographic interfacess”, Journal of Oral Rehabilitation, pp. 1–2, 2012

biosppy.signals.emg.
solnik_onset_detector
(signal=None, rest=None, sampling_rate=1000.0, threshold=None, active_state_duration=None)¶ Determine onsets of EMG pulses.
Follows the approach by Solnik et al. [Sol10].
Parameters:  signal (array) – Input filtered EMG signal.
 rest (array, list, dict) – One of the following 3 options: * Ndimensional array with filtered samples corresponding to a rest period; * 2D array or list with the beginning and end indices of a segment of the signal corresponding to a rest period; * Dictionary with {‘mean’: mean value, ‘std_dev’: standard variation}.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 threshold (int, float) – Scale factor for calculating the detection threshold.
 active_state_duration (int) – Minimum duration of the active state.
Returns:  onsets (array) – Indices of EMG pulse onsets.
 processed (array) – Processed EMG signal.
References
[Sol10] Solnik S, Rider P, Steinweg K, DeVita P, Hortobágyi T, “TeagerKaiser energy operator signal conditioning improves EMG onset detection”, European Journal of Applied Physiology, vol 110:3, pp. 489498, 2010
biosppy.signals.resp¶
This module provides methods to process Respiration (Resp) signals.
copyright: 


license:  BSD 3clause, see LICENSE for more details. 

biosppy.signals.resp.
resp
(signal=None, sampling_rate=1000.0, show=True)¶ Process a raw Respiration signal and extract relevant signal features using default parameters.
Parameters:  signal (array) – Raw Respiration signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 show (bool, optional) – If True, show a summary plot.
Returns:  ts (array) – Signal time axis reference (seconds).
 filtered (array) – Filtered Respiration signal.
 zeros (array) – Indices of Respiration zero crossings.
 resp_rate_ts (array) – Respiration rate time axis reference (seconds).
 resp_rate (array) – Instantaneous respiration rate (Hz).
biosppy.signals.tools¶
This module provides various signal analysis methods in the time and frequency domains.
copyright: 


license:  BSD 3clause, see LICENSE for more details. 

class
biosppy.signals.tools.
OnlineFilter
(b=None, a=None)¶ Bases:
object
Online filtering.
Parameters:  b (array) – Numerator coefficients.
 a (array) – Denominator coefficients.

filter
(signal=None)¶ Filter a signal segment.
Parameters: signal (array) – Signal segment to filter. Returns: filtered (array) – Filtered signal segment.

reset
()¶ Reset the filter state.

biosppy.signals.tools.
analytic_signal
(signal=None, N=None)¶ Compute analytic signal, using the Hilbert Transform.
Parameters:  signal (array) – Input signal.
 N (int, optional) – Number of Fourier components; default is len(signal).
Returns:  amplitude (array) – Amplitude envelope of the analytic signal.
 phase (array) – Instantaneous phase component of the analystic signal.

biosppy.signals.tools.
band_power
(freqs=None, power=None, frequency=None, decibel=True)¶ Compute the avearge power in a frequency band.
Parameters:  freqs (array) – Array of frequencies (Hz) at which the power was computed.
 power (array) – Input power spectrum.
 frequency (list, array) – Pair of frequencies defining the band.
 decibel (bool, optional) – If True, input power is in decibels.
Returns: avg_power (float) – The average power in the band.

biosppy.signals.tools.
distance_profile
(query=None, signal=None, metric='euclidean')¶ Compute the distance profile of a query sequence against a signal.
Implements the algorithm described in [Mueen2014].
Parameters:  query (array) – Input query signal sequence.
 signal (array) – Input target time series signal.
 metric (str, optional) – The distance metric to use; one of ‘euclidean’ or ‘pearson’; default is ‘euclidean’.
Returns: dist (array) – Distance of the query sequence to every subsequnce in the signal.
Notes
 Computes distances on znormalized data.
References
[Mueen2014] Abdullah Mueen, Hossein Hamooni, “Trilce Estrada: Time Series Join on Subsequence Correlation”, ICDM 2014: 450459

biosppy.signals.tools.
filter_signal
(signal=None, ftype='FIR', band='lowpass', order=None, frequency=None, sampling_rate=1000.0, **kwargs)¶ Filter a signal according to the given parameters.
Parameters:  signal (array) – Signal to filter.
 ftype (str) –
 Filter type:
 Finite Impulse Response filter (‘FIR’);
 Butterworth filter (‘butter’);
 Chebyshev filters (‘cheby1’, ‘cheby2’);
 Elliptic filter (‘ellip’);
 Bessel filter (‘bessel’).
 band (str) –
 Band type:
 Lowpass filter (‘lowpass’);
 Highpass filter (‘highpass’);
 Bandpass filter (‘bandpass’);
 Bandstop filter (‘bandstop’).
 order (int) – Order of the filter.
 frequency (int, float, list, array) –
 Cutoff frequencies; format depends on type of band:
 ’lowpass’ or ‘bandpass’: single frequency;
 ’bandpass’ or ‘bandstop’: pair of frequencies.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 **kwargs (dict, optional) – Additional keyword arguments are passed to the underlying scipy.signal function.
Returns:  signal (array) – Filtered signal.
 sampling_rate (float) – Sampling frequency (Hz).
 params (dict) – Filter parameters.
Notes
 Uses a forwardbackward filter implementation. Therefore, the combined filter has linear phase.

biosppy.signals.tools.
find_extrema
(signal=None, mode='both')¶ Locate local extrema points in a signal.
Based on Fermat’s Theorem [Ferm].
Parameters:  signal (array) – Input signal.
 mode (str, optional) – Whether to find maxima (‘max’), minima (‘min’), or both (‘both’).
Returns:  extrema (array) – Indices of the extrama points.
 values (array) – Signal values at the extrema points.
References
[Ferm] Wikipedia, “Fermat’s theorem (stationary points)”, https://en.wikipedia.org/wiki/Fermat%27s_theorem_(stationary_points)

biosppy.signals.tools.
find_intersection
(x1=None, y1=None, x2=None, y2=None, alpha=1.5, xtol=1e06, ytol=1e06)¶ Find the intersection points between two lines using piecewise polynomial interpolation.
Parameters:  x1 (array) – Array of xcoordinates of the first line.
 y1 (array) – Array of ycoordinates of the first line.
 x2 (array) – Array of xcoordinates of the second line.
 y2 (array) – Array of ycoordinates of the second line.
 alpha (float, optional) – Resolution factor for the xaxis; fraction of total number of xcoordinates.
 xtol (float, optional) – Tolerance for the xaxis.
 ytol (float, optional) – Tolerance for the yaxis.
Returns:  roots (array) – Array of xcoordinates of found intersection points.
 values (array) – Array of ycoordinates of found intersection points.
Notes
 If no intersection is found, returns the closest point.

biosppy.signals.tools.
finite_difference
(signal=None, weights=None)¶ Apply the Finite Difference method to compute derivatives.
Parameters:  signal (array) – Signal to differentiate.
 weights (list, array) – Finite difference weight coefficients.
Returns:  index (array) – Indices from signal for which the derivative was computed.
 derivative (array) – Computed derivative.
Notes
 The method assumes central differences weights.
 The method accounts for the delay introduced by the algorithm.
Raises: ValueError
– If the number of weights is not odd.

biosppy.signals.tools.
get_filter
(ftype='FIR', band='lowpass', order=None, frequency=None, sampling_rate=1000.0, **kwargs)¶ Compute digital (FIR or IIR) filter coefficients with the given parameters.
Parameters:  ftype (str) –
 Filter type:
 Finite Impulse Response filter (‘FIR’);
 Butterworth filter (‘butter’);
 Chebyshev filters (‘cheby1’, ‘cheby2’);
 Elliptic filter (‘ellip’);
 Bessel filter (‘bessel’).
 band (str) –
 Band type:
 Lowpass filter (‘lowpass’);
 Highpass filter (‘highpass’);
 Bandpass filter (‘bandpass’);
 Bandstop filter (‘bandstop’).
 order (int) – Order of the filter.
 frequency (int, float, list, array) –
 Cutoff frequencies; format depends on type of band:
 ’lowpass’ or ‘bandpass’: single frequency;
 ’bandpass’ or ‘bandstop’: pair of frequencies.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 **kwargs (dict, optional) – Additional keyword arguments are passed to the underlying scipy.signal function.
Returns:  b (array) – Numerator coefficients.
 a (array) – Denominator coefficients.
 See Also – scipy.signal
 ftype (str) –

biosppy.signals.tools.
get_heart_rate
(beats=None, sampling_rate=1000.0, smooth=False, size=3)¶ Compute instantaneous heart rate from an array of beat indices.
Parameters:  beats (array) – Beat location indices.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 smooth (bool, optional) – If True, perform smoothing on the resulting heart rate.
 size (int, optional) – Size of smoothing window; ignored if smooth is False.
Returns:  index (array) – Heart rate location indices.
 heart_rate (array) – Instantaneous heart rate (bpm).
Notes
 Assumes normal human heart rate to be between 40 and 200 bpm.

biosppy.signals.tools.
mean_waves
(data=None, size=None, step=None)¶ Extract mean samples from a data set.
Parameters:  data (array) – An m by n array of m data samples in an ndimensional space.
 size (int) – Number of samples to use for each mean sample.
 step (int, optional) – Number of samples to jump, controlling overlap; default is equal to size (no overlap).
Returns: waves (array) – An k by n array of mean samples.
Notes
 Discards trailing samples if they are not enough to satify the size parameter.
Raises: ValueError
– If step is an invalid value.ValueError
– If there are not enough samples for the given size.

biosppy.signals.tools.
median_waves
(data=None, size=None, step=None)¶ Extract median samples from a data set.
Parameters:  data (array) – An m by n array of m data samples in an ndimensional space.
 size (int) – Number of samples to use for each median sample.
 step (int, optional) – Number of samples to jump, controlling overlap; default is equal to size (no overlap).
Returns: waves (array) – An k by n array of median samples.
Notes
 Discards trailing samples if they are not enough to satify the size parameter.
Raises: ValueError
– If step is an invalid value.ValueError
– If there are not enough samples for the given size.

biosppy.signals.tools.
normalize
(signal=None, ddof=1)¶ Normalize a signal to zero mean and unitary standard deviation.
Parameters:  signal (array) – Input signal.
 ddof (int, optional) – Delta degrees of freedom for standard deviation computation; the divisor is N  ddof, where N is the number of elements; default is one.
Returns: signal (array) – Normalized signal.

biosppy.signals.tools.
pearson_correlation
(x=None, y=None)¶ Compute the Pearson Correlation Coefficient bertween two signals.
The coefficient is given by:
Parameters:  x (array) – First input signal.
 y (array) – Second input signal.
Returns: rxy (float) – Pearson correlation coefficient, ranging between 1 and +1.
Raises: ValueError
– If the input signals do not have the same length.

biosppy.signals.tools.
phase_locking
(signal1=None, signal2=None, N=None)¶ Compute the PhaseLocking Factor (PLF) between two signals.
Parameters:  signal1 (array) – First input signal.
 signal2 (array) – Second input signal.
 N (int, optional) – Number of Fourier components.
Returns: plf (float) – The PLF between the two signals.

biosppy.signals.tools.
power_spectrum
(signal=None, sampling_rate=1000.0, pad=None, pow2=False, decibel=True)¶ Compute the power spectrum of a signal (onesided).
Parameters:  signal (array) – Input signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 pad (int, optional) – Padding for the Fourier Transform (number of zeros added); defaults to no padding..
 pow2 (bool, optional) – If True, rounds the number of points N = len(signal) + pad to the nearest power of 2 greater than N.
 decibel (bool, optional) – If True, returns the power in decibels.
Returns:  freqs (array) – Array of frequencies (Hz) at which the power was computed.
 power (array) – Power spectrum.

biosppy.signals.tools.
rms_error
(x=None, y=None)¶ Compute the RootMeanSquare Error between two signals.
The error is given by:
Parameters:  x (array) – First input signal.
 y (array) – Second input signal.
Returns: rmse (float) – Rootmeansquare error.
Raises: ValueError
– If the input signals do not have the same length.

biosppy.signals.tools.
signal_cross_join
(signal1=None, signal2=None, size=None, index=None, limit=None)¶ Compute the matrix profile for a similarity join of two time series.
Computes the nearest subsequence in signal2 for each subsequence in signal1. Implements the algorithm described in [Yeh2016_c].
Parameters:  signal1 (array) – Fisrt input time series signal.
 signal2 (array) – Second input time series signal.
 size (int) – Size of the query subsequences.
 index (list, array, optional) – Starting indices for query subsequences; the default is to search all subsequences.
 limit (int, optional) – Upper limit for the number of query subsequences; the default is to search all subsequences.
Returns:  matrix_index (array) – Matric profile index.
 matrix_profile (array) – Computed matrix profile (distances).
Notes
 Computes euclidean distances on znormalized data.
References
[Yeh2016_c] ChinChia Michael Yeh, Yan Zhu, Liudmila Ulanova, Nurjahan Begum, Yifei Ding, Hoang Anh Dau, Diego Furtado Silva, Abdullah Mueen, Eamonn Keogh, “Matrix Profile I: All Pairs Similarity Joins for Time Series: A Unifying View that Includes Motifs, Discords and Shapelets”, IEEE ICDM 2016

biosppy.signals.tools.
signal_self_join
(signal=None, size=None, index=None, limit=None)¶ Compute the matrix profile for a selfsimilarity join of a time series.
Implements the algorithm described in [Yeh2016_b].
Parameters:  signal (array) – Input target time series signal.
 size (int) – Size of the query subsequences.
 index (list, array, optional) – Starting indices for query subsequences; the default is to search all subsequences.
 limit (int, optional) – Upper limit for the number of query subsequences; the default is to search all subsequences.
Returns:  matrix_index (array) – Matric profile index.
 matrix_profile (array) – Computed matrix profile (distances).
Notes
 Computes euclidean distances on znormalized data.
References
[Yeh2016_b] ChinChia Michael Yeh, Yan Zhu, Liudmila Ulanova, Nurjahan Begum, Yifei Ding, Hoang Anh Dau, Diego Furtado Silva, Abdullah Mueen, Eamonn Keogh, “Matrix Profile I: All Pairs Similarity Joins for Time Series: A Unifying View that Includes Motifs, Discords and Shapelets”, IEEE ICDM 2016

biosppy.signals.tools.
signal_stats
(signal=None)¶ Compute various metrics describing the signal.
Parameters: signal (array) – Input signal. Returns:  mean (float) – Mean of the signal.
 median (float) – Median of the signal.
 max (float) – Maximum signal amplitude.
 var (float) – Signal variance (unbiased).
 std_dev (float) – Standard signal deviation (unbiased).
 abs_dev (float) – Absolute signal deviation.
 kurtosis (float) – Signal kurtosis (unbiased).
 skew (float) – Signal skewness (unbiased).

biosppy.signals.tools.
smoother
(signal=None, kernel='boxzen', size=10, mirror=True, **kwargs)¶ Smooth a signal using an Npoint moving average [MAvg] filter.
This implementation uses the convolution of a filter kernel with the input signal to compute the smoothed signal [Smit97].
Availabel kernels: median, boxzen, boxcar, triang, blackman, hamming, hann, bartlett, flattop, parzen, bohman, blackmanharris, nuttall, barthann, kaiser (needs beta), gaussian (needs std), general_gaussian (needs power, width), slepian (needs width), chebwin (needs attenuation).
Parameters:  signal (array) – Signal to smooth.
 kernel (str, array, optional) – Type of kernel to use; if array, use directly as the kernel.
 size (int, optional) – Size of the kernel; ignored if kernel is an array.
 mirror (bool, optional) – If True, signal edges are extended to avoid boundary effects.
 **kwargs (dict, optional) – Additional keyword arguments are passed to the underlying scipy.signal.windows function.
Returns:  signal (array) – Smoothed signal.
 params (dict) – Smoother parameters.
Notes
 When the kernel is ‘median’, mirror is ignored.
References
[MAvg] Wikipedia, “Moving Average”, http://en.wikipedia.org/wiki/Moving_average [Smit97] S. W. Smith, “Moving Average Filters  Implementation by Convolution”, http://www.dspguide.com/ch15/1.htm, 1997

biosppy.signals.tools.
synchronize
(x=None, y=None, detrend=True)¶ Align two signals based on crosscorrelation.
Parameters:  x (array) – First input signal.
 y (array) – Second input signal.
 detrend (bool, optional) – If True, remove signal means before computation.
Returns:  delay (int) – Delay (number of samples) of ‘x’ in relation to ‘y’; if ‘delay’ < 0 , ‘x’ is ahead in relation to ‘y’; if ‘delay’ > 0 , ‘x’ is delayed in relation to ‘y’.
 corr (float) – Value of maximum correlation.
 synch_x (array) – Biggest possible portion of ‘x’ in synchronization.
 synch_y (array) – Biggest possible portion of ‘y’ in synchronization.

biosppy.signals.tools.
welch_spectrum
(signal=None, sampling_rate=1000.0, size=None, overlap=None, window='hanning', window_kwargs=None, pad=None, decibel=True)¶ Compute the power spectrum of a signal using Welch’s method (onesided).
Parameters:  signal (array) – Input signal.
 sampling_rate (int, float, optional) – Sampling frequency (Hz).
 size (int, optional) – Number of points in each Welch segment; defaults to the equivalent of 1 second; ignored when ‘window’ is an array.
 overlap (int, optional) – Number of points to overlap between segments; defaults to size / 2.
 window (str, array, optional) – Type of window to use.
 window_kwargs (dict, optional) – Additional keyword arguments to pass on window creation; ignored if ‘window’ is an array.
 pad (int, optional) – Padding for the Fourier Transform (number of zeros added); defaults to no padding.
 decibel (bool, optional) – If True, returns the power in decibels.
Returns:  freqs (array) – Array of frequencies (Hz) at which the power was computed.
 power (array) – Power spectrum.
Notes
 Detrends each Welch segment by removing the mean.

biosppy.signals.tools.
windower
(signal=None, size=None, step=None, fcn=None, fcn_kwargs=None, kernel='boxcar', kernel_kwargs=None)¶ Apply a function to a signal in sequential windows, with optional overlap.
Availabel window kernels: boxcar, triang, blackman, hamming, hann, bartlett, flattop, parzen, bohman, blackmanharris, nuttall, barthann, kaiser (needs beta), gaussian (needs std), general_gaussian (needs power, width), slepian (needs width), chebwin (needs attenuation).
Parameters:  signal (array) – Input signal.
 size (int) – Size of the signal window.
 step (int, optional) – Size of window shift; if None, there is no overlap.
 fcn (callable) – Function to apply to each window.
 fcn_kwargs (dict, optional) – Additional keyword arguments to pass to ‘fcn’.
 kernel (str, array, optional) – Type of kernel to use; if array, use directly as the kernel.
 kernel_kwargs (dict, optional) – Additional keyword arguments to pass on window creation; ignored if ‘kernel’ is an array.
Returns:  index (array) – Indices characterizing window locations (start of the window).
 values (array) – Concatenated output of calling ‘fcn’ on each window.

biosppy.signals.tools.
zero_cross
(signal=None, detrend=False)¶ Locate the indices where the signal crosses zero.
Parameters:  signal (array) – Input signal.
 detrend (bool, optional) – If True, remove signal mean before computation.
Returns: zeros (array) – Indices of zero crossings.
Notes
 When the signal crosses zero between samples, the first index is returned.