API documentation¶
Hrvanalysis consists of a single module which contains all relevant functions and algorithms.
Internally these functions are subdivided into 3 different modules :
 preprocessing
 extract_features
 plot
You should not need to import those modules directly unless you want access to some internal helper functions.
Preprocessing methods¶
This script provides several methods to clean abnormal and ectopic RRintervals.

hrvanalysis.preprocessing.
remove_outliers
(rr_intervals: List[float], verbose: bool = True, low_rri: int = 300, high_rri: int = 2000) → list¶ Function that replace RRinterval outlier by nan.
Parameters:  rr_intervals (list) – raw signal extracted.
 low_rri (int) – lowest RrInterval to be considered plausible.
 high_rri (int) – highest RrInterval to be considered plausible.
 verbose (bool) – Print information about deleted outliers.
Returns: rr_intervals_cleaned – list of RRintervals without outliers
Return type: list
References
[1]  Inbar, A. Oten, M. Scheinowitz, A. Rotstein, R. Dlin, R.Casaburi. Normal cardiopulmonary responses during incremental exercise in 2070yrold men.
[2]  Miller, J. P. Wallace, K. E. Eggert. Predicting max HR and the HRVO2 relationship for exercise prescription in obesity.
[3]  Tanaka, K. D. Monahan, D. R. Seals. Agepredictedmaximal heart rate revisited.
[4]  Gulati, L. J. Shaw, R. A. Thisted, H. R. Black, C. N. B.Merz, M. F. Arnsdorf. Heart rate response to exercise stress testing in asymptomatic women.

hrvanalysis.preprocessing.
remove_ectopic_beats
(rr_intervals: List[float], method: str = 'malik', custom_removing_rule: float = 0.2) → list¶ RRintervals differing by more than the removing_rule from the one proceeding it are removed.
Parameters:  rr_intervals (list) – list of RRintervals
 method (str) – method to use to clean outlier. malik, kamath, karlsson, acar or custom.
 custom_removing_rule (int) – Percentage criteria of difference with previous RRinterval at which we consider that it is abnormal. If method is set to Karlsson, it is the percentage of difference between the absolute mean of previous and next RRinterval at which to consider the beat as abnormal.
Returns:  nn_intervals (list) – list of NN Interval
 outlier_count (int) – Count of outlier detected in RRinterval list
References
[5] Kamath M.V., Fallen E.L.: Correction of the Heart Rate Variability Signal for Ectopics and Miss ing Beats, In: Malik M., Camm A.J. [6] Geometric Methods for Heart Rate Variability Assessment  Malik M et al

hrvanalysis.preprocessing.
interpolate_nan_values
(rr_intervals: list, interpolation_method: str = 'linear', limit=1) → list¶ Function that interpolate Nan values with linear interpolation
Parameters:  rr_intervals (list) – RrIntervals list.
 interpolation_method (str) – Method used to interpolate Nan values of series.
 limit (int) – TODO
Returns: interpolated_rr_intervals – new list with outliers replaced by interpolated values.
Return type: list

hrvanalysis.preprocessing.
get_nn_intervals
(rr_intervals: List[float], low_rri: int = 300, high_rri: int = 2000, interpolation_method: str = 'linear', ectopic_beats_removal_method: str = 'kamath', verbose: bool = True) → List[float]¶ Function that computes NN Intervals from RRintervals.
Parameters:  rr_intervals (list) – RrIntervals list.
 interpolation_method (str) – Method used to interpolate Nan values of series.
 ectopic_beats_removal_method (str) – method to use to clean outlier. malik, kamath, karlsson, acar or custom.
 low_rri (int) – lowest RrInterval to be considered plausible.
 high_rri (int) – highest RrInterval to be considered plausible.
 verbose (bool) – Print information about deleted outliers.
Returns: interpolated_nn_intervals – list of NN Interval interpolated
Return type: list
Features extraction methods¶
This script provides several methods to extract features from Normal to Normal Intervals for heart rate variability analysis.

hrvanalysis.extract_features.
get_time_domain_features
(nn_intervals: List[float]) → dict¶ Returns a dictionary containing time domain features for HRV analysis. Mostly used on long term recordings (24h) but some studies use some of those features on short term recordings, from 1 to 5 minutes window.
Parameters: nn_intervals (list) – list of Normal to Normal Interval Returns: time_domain_features – dictionary containing time domain features for HRV analyses. There are details about each features below. Return type: dict Notes
Here are some details about feature engineering…
 mean_nni: The mean of RRintervals.
 sdnn : The standard deviation of the time interval between successive normal heart beats (i.e. the RRintervals).
 sdsd: The standard deviation of differences between adjacent RRintervals
 rmssd: The square root of the mean of the sum of the squares of differences between adjacent NNintervals. Reflects high frequency (fast or parasympathetic) influences on hrV (i.e., those influencing larger changes from one beat to the next).
 median_nni: Median Absolute values of the successive differences between the RRintervals.
 nni_50: Number of interval differences of successive RRintervals greater than 50 ms.
 pnni_50: The proportion derived by dividing nni_50 (The number of interval differences of successive RRintervals greater than 50 ms) by the total number of RRintervals.
 nni_20: Number of interval differences of successive RRintervals greater than 20 ms.
 pnni_20: The proportion derived by dividing nni_20 (The number of interval differences of successive RRintervals greater than 20 ms) by the total number of RRintervals.
 range_nni: difference between the maximum and minimum nn_interval.
 cvsd: Coefficient of variation of successive differences equal to the rmssd divided by mean_nni.
 cvnni: Coefficient of variation equal to the ratio of sdnn divided by mean_nni.
 mean_hr: The mean Heart Rate.
 max_hr: Max heart rate.
 min_hr: Min heart rate.
 std_hr: Standard deviation of heart rate.
References
[1] Heart rate variability  Standards of measurement, physiological interpretation, and clinical use, Task Force of The European Society of Cardiology and The North American Society of Pacing and Electrophysiology, 1996

hrvanalysis.extract_features.
get_frequency_domain_features
(nn_intervals: List[float], method: str = 'welch', sampling_frequency: int = 4, interpolation_method: str = 'linear', vlf_band: collections.namedtuple = Vlf_band(low=0.003, high=0.04), lf_band: collections.namedtuple = Lf_band(low=0.04, high=0.15), hf_band: collections.namedtuple = Hf_band(low=0.15, high=0.4)) → dict¶ Returns a dictionary containing frequency domain features for HRV analyses. To our knowledge, you might use this function on short term recordings, from 2 to 5 minutes window.
Parameters:  nn_intervals (list) – list of Normal to Normal Interval
 method (str) – Method used to calculate the psd. Choice are Welch’s FFT or Lomb method.
 sampling_frequency (int) – Frequency at which the signal is sampled. Common value range from 1 Hz to 10 Hz, by default set to 4 Hz. No need to specify if Lomb method is used.
 interpolation_method (str) – kind of interpolation as a string, by default “linear”. No need to specify if Lomb method is used.
 vlf_band (tuple) – Very low frequency bands for features extraction from power spectral density.
 lf_band (tuple) – Low frequency bands for features extraction from power spectral density.
 hf_band (tuple) – High frequency bands for features extraction from power spectral density.
Returns: frequency_domain_features – Dictionary containing frequency domain features for HRV analyses. There are details about each features below.
Return type: dict
Notes
Details about feature engineering…
 total_power : Total power density spectral
 vlf : variance ( = power ) in HRV in the Very low Frequency (.003 to .04 Hz by default). Reflect an intrinsic rhythm produced by the heart which is modulated primarily by sympathetic activity.
 lf : variance ( = power ) in HRV in the low Frequency (.04 to .15 Hz). Reflects a mixture of sympathetic and parasympathetic activity, but in longterm recordings, it reflects sympathetic activity and can be reduced by the betaadrenergic antagonist propanolol.
 hf: variance ( = power ) in HRV in the High Frequency (.15 to .40 Hz by default). Reflects fast changes in beattobeat variability due to parasympathetic (vagal) activity. Sometimes called the respiratory band because it corresponds to HRV changes related to the respiratory cycle and can be increased by slow, deep breathing (about 6 or 7 breaths per minute) and decreased by anticholinergic drugs or vagal blockade.
 lf_hf_ratio : lf/hf ratio is sometimes used by some investigators as a quantitative mirror of the sympatho/vagal balance.
 lfnu : normalized lf power.
 hfnu : normalized hf power.
References
[1] Heart rate variability  Standards of measurement, physiological interpretation, and clinical use, Task Force of The European Society of Cardiology and The North American Society of Pacing and Electrophysiology, 1996 [2] Signal Processing Methods for Heart Rate Variability  Gari D. Clifford, 2002

hrvanalysis.extract_features.
get_geometrical_features
(nn_intervals: List[float]) → dict¶ Returns a dictionary containing geometrical time domain features for HRV analyses. Known practise is to use this function on recordings from 20 minutes to 24 Hours window.
Parameters: nn_intervals (list) – list of Normal to Normal Interval. Returns: geometrical_features – Dictionary containing geometrical time domain features for HRV analyses. There are details about each features below. Return type: dict Notes
Details about feature engineering…
 triangular_index: The HRV triangular index measurement is the integral of the density distribution (= the number of all NNintervals) divided by the maximum of the density distribution.
 tinn: The triangular interpolation of NNinterval histogram (TINN) is the baseline width of the distribution measured as a base of a triangle, approximating the NNinterval distribution
References
[1] Heart rate variability  Standards of measurement, physiological interpretation, and clinical use, Task Force of The European Society of Cardiology and The North American Society of Pacing and Electrophysiology, 1996

hrvanalysis.extract_features.
get_poincare_plot_features
(nn_intervals: List[float]) → dict¶ Function returning a dictionary containing 3 features from non linear domain for HRV analyses. Known practise is to use this function on short term recordings, from 5 minutes window.
Parameters: nn_intervals (list) – Normal to Normal Interval Returns: poincare_plot_features – Dictionary containing non linear domain features for hrV analyses. There are details about each features are given below. Return type: dict Notes
 sd1 : The standard deviation of projection of the Poincaré plot on the line perpendicular to the line of identity.
 sd2 : SD2 is defined as the standard deviation of the projection of the Poincaré plot on the line of identity (y=x).
 ratio_sd2_sd1 : Ratio between SD2 and SD1.
References
[4] Preictal heart rate variability assessment of epileptic seizures by means of linear and non linear analyses, Soroor Behbahani, Nader Jafarnia Dabanloo et al  2013

hrvanalysis.extract_features.
get_csi_cvi_features
(nn_intervals: List[float]) → dict¶ Returns a dictionary containing 3 features from non linear domain for HRV analyses. Known practise is to use this function on short term recordings, on 30 , 50, 100 RRintervals (or seconds) window.
Parameters: nn_intervals (list) – Normal to Normal Intervals. Returns: csi_cvi_features – Dictionary containing non linear domain features for hrV analyses. There are details about each features are given below. Return type: dict Notes
 csi : Cardiac Sympathetic Index.
 cvi : Cadiac Vagal Index.
 Modified_csi : Modified CSI is an alternative measure in research of seizure detection.
References
[3] Using Lorenz plot and Cardiac Sympathetic Index of heart rate variability for detecting seizures for patients with epilepsy, Jesper Jeppesen et al, 2014

hrvanalysis.extract_features.
get_sampen
(nn_intervals: List[float]) → dict¶ Function computing the sample entropy of the given data. Must use this function on short term recordings, from 1 minute window.
Parameters: nn_intervals (list) – Normal to Normal Interval Returns: sampen – The sample entropy of the data Return type: float References
[5] Physiological timeseries analysis using approximate entropy and sample entropy, JOSHUA S. RICHMAN1, J. RANDALL MOORMAN  2000
Plot methods¶
This script provides several methods to plot RR / NNintervals.

hrvanalysis.plot.
HfBand
¶ alias of
hrvanalysis.plot.Hf_band

hrvanalysis.plot.
LfBand
¶ alias of
hrvanalysis.plot.Lf_band

hrvanalysis.plot.
VlfBand
¶ alias of
hrvanalysis.plot.Vlf_band

hrvanalysis.plot.
plot_distrib
(nn_intervals: List[float], bin_length: int = 8)¶ Function plotting histogram distribution of the NN Intervals. Useful for geometrical features.
Parameters:  nn_intervals (list) – list of Normal to Normal Interval.
 bin_length (int) – size of the bin for histogram in ms, by default = 8.

hrvanalysis.plot.
plot_poincare
(nn_intervals: List[float], plot_sd_features: bool = True)¶ Pointcare / Lorentz Plot of the NN Intervals
Parameters:  nn_intervals (list) – list of NN intervals
 plot_sd_features (bool) – Option to show or not SD1 and SD2 features on plot. By default, set to True.
Notes
The transverse axis (T) reflects beattobeat variation the longitudinal axis (L) reflects the overall fluctuation

hrvanalysis.plot.
plot_psd
(nn_intervals: List[float], method: str = 'welch', sampling_frequency: int = 7, interpolation_method: str = 'linear', vlf_band: collections.namedtuple = Vlf_band(low=0.003, high=0.04), lf_band: collections.namedtuple = Lf_band(low=0.04, high=0.15), hf_band: collections.namedtuple = Hf_band(low=0.15, high=0.4))¶ Function plotting the power spectral density of the NN Intervals.
Parameters:  nn_intervals (list) – list of Normal to Normal Interval.
 method (str) – Method used to calculate the psd. Choice are Welch’s FFT (welch) or Lomb method (lomb).
 sampling_frequency (int) – frequence at which the signal is sampled. Common value range from 1 Hz to 10 Hz, by default set to 7 Hz. No need to specify if Lomb method is used.
 interpolation_method (str) – kind of interpolation as a string, by default “linear”. No need to specify if lomb method is used.
 vlf_band (tuple) – Very low frequency bands for features extraction from power spectral density.
 lf_band (tuple) – Low frequency bands for features extraction from power spectral density.
 hf_band (tuple) – High frequency bands for features extraction from power spectral density.

hrvanalysis.plot.
plot_timeseries
(nn_intervals: List[float], normalize: bool = True, autoscale: bool = True, y_min: float = None, y_max: float = None)¶ Function plotting the NNintervals time series.
Parameters:  nn_intervals (list) – list of Normal to Normal Interval.
 normalize (bool) – Set to True to plot X axis as a cumulative sum of Time. Set to False to plot X axis using x as index array 0, 1, …, N1.
 autoscale (bool) – Option to normalize the xaxis as a time series for comparison. Set to True by default.
 y_min (float) – Custom min value might be set for y axis.
 y_max (float) – Custom max value might be set for y axis.
This script allow user to import directly the most useful functions.