API documentation

Hrv-analysis 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 RR-intervals.

hrvanalysis.preprocessing.remove_outliers(rr_intervals: List[float], verbose: bool = True, low_rri: int = 300, high_rri: int = 2000) → list

Function that replace RR-interval 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 RR-intervals without outliers
Return type:

list

References

[1]
  1. Inbar, A. Oten, M. Scheinowitz, A. Rotstein, R. Dlin, R.Casaburi. Normal cardiopulmonary responses during incremental exercise in 20-70-yr-old men.
[2]
    1. Miller, J. P. Wallace, K. E. Eggert. Predicting max HR and the HR-VO2 relationship for exercise prescription in obesity.
[3]
  1. Tanaka, K. D. Monahan, D. R. Seals. Age-predictedmaximal heart rate revisited.
[4]
  1. 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

RR-intervals differing by more than the removing_rule from the one proceeding it are removed.

Parameters:
  • rr_intervals (list) – list of RR-intervals
  • method (str) – method to use to clean outlier. malik, kamath, karlsson, acar or custom.
  • custom_removing_rule (int) – Percentage criteria of difference with previous RR-interval 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 RR-interval at which to consider the beat as abnormal.
Returns:

  • nn_intervals (list) – list of NN Interval
  • outlier_count (int) – Count of outlier detected in RR-interval 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 RR-intervals.

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 RR-intervals.
  • sdnn : The standard deviation of the time interval between successive normal heart beats (i.e. the RR-intervals).
  • sdsd: The standard deviation of differences between adjacent RR-intervals
  • rmssd: The square root of the mean of the sum of the squares of differences between adjacent NN-intervals. 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 RR-intervals.
  • nni_50: Number of interval differences of successive RR-intervals greater than 50 ms.
  • pnni_50: The proportion derived by dividing nni_50 (The number of interval differences of successive RR-intervals greater than 50 ms) by the total number of RR-intervals.
  • nni_20: Number of interval differences of successive RR-intervals greater than 20 ms.
  • pnni_20: The proportion derived by dividing nni_20 (The number of interval differences of successive RR-intervals greater than 20 ms) by the total number of RR-intervals.
  • 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 long-term recordings, it reflects sympathetic activity and can be reduced by the beta-adrenergic antagonist propanolol.
  • hf: variance ( = power ) in HRV in the High Frequency (.15 to .40 Hz by default). Reflects fast changes in beat-to-beat 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 NN-intervals) divided by the maximum of the density distribution.
  • tinn: The triangular interpolation of NN-interval histogram (TINN) is the baseline width of the distribution measured as a base of a triangle, approximating the NN-interval 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]Pre-ictal 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 RR-intervals (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 time-series analysis using approximate entropy and sample entropy, JOSHUA S. RICHMAN1, J. RANDALL MOORMAN - 2000

Plot methods

This script provides several methods to plot RR / NN-intervals.

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 beat-to-beat 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 NN-intervals 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, …, N-1.
  • autoscale (bool) – Option to normalize the x-axis 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.