biosppy.signals.hrv

biosppy.signals.hrv

This module provides computation and visualization of Heart-Rate Variability metrics.

copyright:

  1. 2015-2026 by Instituto de Telecomunicacoes

license:

BSD 3-clause, see LICENSE for more details.

Functions

approximate_entropy(rri[, m, r])

Computes the approximate entropy of an RRI sequence.

compute_fbands(frequencies, powers[, ...])

Computes frequency domain features for the specified frequency bands.

compute_geometrical(rri[, binsize, show])

Computes the geometrical features from a sequence of RR intervals.

compute_poincare(rri[, show])

Compute the Poincaré features from a sequence of RR intervals.

compute_rri(rpeaks[, sampling_rate, ...])

Computes RR intervals in milliseconds from a list of R-peak indexes.

detrend_window(rri[, win_len])

Facilitates RRI detrending method using a signal window.

hrv([rpeaks, sampling_rate, rri, rri_min, ...])

Extracts the RR-interval sequence from a list of R-peak indexes and extracts HRV features.

hrv_frequencydomain([rri, duration, ...])

Computes the frequency domain HRV features from a sequence of RR intervals.

hrv_nonlinear([rri, duration, detrend_rri, show])

Computes the non-linear HRV features from a sequence of RR intervals.

hrv_timedomain(rri[, duration, detrend_rri, ...])

Computes the time domain HRV features from a sequence of RR intervals in milliseconds.

rri_correction([rri, threshold])

Corrects artifacts in an RRI sequence based on a local average threshold.

rri_filter([rri, threshold])

Filters an RRI sequence based on a maximum threshold in milliseconds.

sample_entropy(rri[, m, r])

Computes the sample entropy of an RRI sequence.
biosppy.signals.hrv.approximate_entropy(rri, m=2, r=0.2)[source]

Computes the approximate entropy of an RRI sequence.

Parameters:

  • rri (array) – RR-intervals (ms).

  • m (int, optional) – Embedding dimension. Default: 2.

  • r (int, float, optional) – Tolerance. It is then multiplied by the sequence standard deviation. Default: 0.2.

Returns:

appen (float) – Approximate entropy of the RRI sequence.

References

https://en.wikipedia.org/wiki/Approximate_entropy

biosppy.signals.hrv.compute_fbands(frequencies, powers, fbands=None, method_name=None, show=False)[source]

Computes frequency domain features for the specified frequency bands.

Parameters:

  • frequencies (array) – Frequency axis.

  • powers (array) – Power spectrum values for the frequency axis.

  • fbands (dict, optional) – Dictionary containing the limits of the frequency bands.

  • method_name (str, optional) – Method that was used to compute the power spectrum. Default: None.

  • show (bool, optional) – Whether to show the power spectrum plot. Default: False.

Returns:

  • {fbands}_peak (float) – Peak frequency of the frequency band (Hz).

  • {fbands}_pwr (float) – Absolute power of the frequency band (ms^2).

  • {fbands}_rpwr (float) – Relative power of the frequency band (nu).

biosppy.signals.hrv.compute_geometrical(rri, binsize=0.0078125, show=False)[source]

Computes the geometrical features from a sequence of RR intervals.

Parameters:

  • rri (array) – RR-intervals (ms).

  • binsize (float, optional) – Binsize for RRI histogram (s). Default: 1/128 s.

  • show (bool, optional) – If True, show the RRI histogram. Default: False.

Returns:

  • hti (float) – HTI - HRV triangular index - Integral of the density of the RR interval histogram divided by its height.

  • tinn (float) – TINN - Baseline width of RR interval histogram (ms).

biosppy.signals.hrv.compute_poincare(rri, show=False)[source]

Compute the Poincaré features from a sequence of RR intervals.

Parameters:

  • rri (array) – RR-intervals (ms).

  • show (bool, optional) – If True, show the Poincaré plot.

Returns:

  • s (float) – S - Area of the ellipse of the Poincaré plot (ms^2).

  • sd1 (float) – SD1 - Poincaré plot standard deviation perpendicular to the identity line (ms).

  • sd2 (float) – SD2 - Poincaré plot standard deviation along the identity line (ms).

  • sd12 (float) – SD1/SD2 - SD1 to SD2 ratio.

  • sd21 (float) – SD2/SD1 - SD2 to SD1 ratio.

biosppy.signals.hrv.compute_rri(rpeaks, sampling_rate=1000.0, filter_rri=True, rri_min=300, rri_max=1500, show=False)[source]

Computes RR intervals in milliseconds from a list of R-peak indexes.

Parameters:

  • rpeaks (list, array) – R-peak index locations.

  • sampling_rate (int, float, optional) – Sampling frequency (Hz).

  • filter_rri (bool, optional) – Whether to filter the RR-interval sequence. Default: True.

  • show (bool, optional) – Plots the RR-interval sequence. Default: False.

Returns:

rri (array) – RR-intervals (ms).

biosppy.signals.hrv.detrend_window(rri, win_len=2000, **kwargs)[source]

Facilitates RRI detrending method using a signal window.

Parameters:

  • rri (array) – RR-intervals (ms).

  • win_len (int, optional) – Length of the window to detrend the RRI signal. Default: 2000.

  • kwargs (dict, optional) – Parameters of the detrending method.

Returns:

  • rri_det (array) – Detrended RRI signal.

  • rri_trend (array) – Trend of the RRI signal.

biosppy.signals.hrv.hrv(rpeaks=None, sampling_rate=1000.0, rri=None, rri_min=300, rri_max=1500, parameters='auto', outliers='interpolate', detrend_rri=True, features_only=True, show=True, show_individual=False, **kwargs)[source]

Extracts the RR-interval sequence from a list of R-peak indexes and extracts HRV features.

Parameters:

  • rpeaks (array) – R-peak index locations.

  • sampling_rate (int, float, optional) – Sampling frequency (Hz). Default: 1000.0 Hz.

  • rri (array, optional) – RR-intervals (ms). Providing this parameter overrides the computation of RR-intervals from rpeaks.

  • rri_min (int, optional) – Minimum RR-interval (ms). Default: 300 ms.

  • rri_max (int, optional) – Maximum RR-interval (ms). Default: 1500 ms.

  • parameters (str, optional) – If ‘auto’ computes the recommended HRV features. If ‘time’ computes only time-domain features. If ‘frequency’ computes only frequency-domain features. If ‘non-linear’ computes only non-linear features. If ‘all’ computes all available HRV features. Default: ‘auto’.

  • outliers (str, optional) – Determines the method to handle outliers. If ‘interpolate’, replaces the outlier RR-intervals with cubic spline interpolation based on a local threshold. If ‘filter’, the RR-interval sequence is cut at the outliers. If None, no correction is performed. Default: ‘interpolate’.

  • detrend_rri (bool, optional) – Whether to detrend the RRI sequence with the default method smoothness priors. Default: True.

  • features_only (bool, optional) – Whether to return only the hrv features. Default: True.

  • show (bool, optional) – Whether to show the HRV summary plot. Default: True.

  • show_individual (bool, optional) – Whether to show the individual HRV plots. Default: False.

  • kwargs (dict, optional) – fbands : dictionary of frequency bands (Hz) to use.

Returns:

  • rri (array) – RR-intervals (ms).

  • rri_det (array) – Detrended RR-interval sequence (ms), if detrending was applied.

  • hrv_features (dict) – The set of HRV features extracted from the RRI data. The number of features depends on the chosen parameters.

biosppy.signals.hrv.hrv_frequencydomain(rri=None, duration=None, freq_method='FFT', fbands=None, detrend_rri=True, show=False, **kwargs)[source]

Computes the frequency domain HRV features from a sequence of RR intervals.

Parameters:

  • rri (array) – RR-intervals (ms).

  • duration (int, optional) – Duration of the signal (s).

  • freq_method (str, optional) – Method for spectral estimation. If ‘FFT’ uses Welch’s method.

  • fbands (dict, optional) – Dictionary specifying the desired HRV frequency bands.

  • detrend_rri (bool, optional) – Whether to detrend the input signal. Default: True.

  • show (bool, optional) – Whether to show the power spectrum plot. Default: False.

  • kwargs (dict, optional) – frs : resampling frequency for the RRI sequence (Hz). nperseg : Length of each segment in Welch periodogram. nfft : Length of the FFT used in Welch function.

Returns:

  • {fbands}_peak (float) – Peak frequency for each frequency band (Hz).

  • {fbands}_pwr (float) – Absolute power for each frequency band (ms^2).

  • {fbands}_rpwr (float) – Relative power for each frequency band (nu).

  • lf_hf (float) – Ratio of LF-to-HF power.

  • lf_nu (float) – Ratio of LF to LF+HF power (nu).

  • hf_nu (float) – Ratio of HF to LF+HF power (nu).

  • total_pwr (float) – Total power.

biosppy.signals.hrv.hrv_nonlinear(rri=None, duration=None, detrend_rri=True, show=False)[source]

Computes the non-linear HRV features from a sequence of RR intervals.

Parameters:

  • rri (array) – RR-intervals (ms).

  • duration (int, optional) – Duration of the signal (s).

  • detrend_rri (bool, optional) – Whether to detrend the input signal. Default: True.

  • show (bool, optional) – Controls the plotting calls. Default: False.

Returns:

  • s (float) – S - Area of the ellipse of the Poincaré plot (ms^2).

  • sd1 (float) – SD1 - Poincaré plot standard deviation perpendicular to the identity line (ms).

  • sd2 (float) – SD2 - Poincaré plot standard deviation along the identity line (ms).

  • sd12 (float) – SD1/SD2 - SD1 to SD2 ratio.

  • sd21 (float) – SD2/SD1 - SD2 to SD1 ratio.

  • sampen (float) – Sample entropy.

  • appen (float) – Approximate entropy.

biosppy.signals.hrv.hrv_timedomain(rri, duration=None, detrend_rri=True, show=False, **kwargs)[source]

Computes the time domain HRV features from a sequence of RR intervals in milliseconds.

Parameters:

  • rri (array) – RR-intervals (ms).

  • duration (int, optional) – Duration of the signal (s).

  • detrend_rri (bool, optional) – Whether to detrend the input signal.

  • show (bool, optional) – Controls the plotting calls. Default: False.

Returns:

  • hr (array) – Instantaneous heart rate (bpm).

  • hr_min (float) – Minimum heart rate (bpm).

  • hr_max (float) – Maximum heart rate (bpm).

  • hr_minmax (float) – Difference between the highest and the lowest heart rates (bpm).

  • hr_mean (float) – Mean heart rate (bpm).

  • hr_median (float) – Median heart rate (bpm).

  • rr_min (float) – Minimum value of RR intervals (ms).

  • rr_max (float) – Maximum value of RR intervals (ms).

  • rr_minmax (float) – Difference between the highest and the lowest values of RR intervals (ms).

  • rr_mean (float) – Mean value of RR intervals (ms).

  • rr_median (float) – Median value of RR intervals (ms).

  • rmssd (float) – RMSSD - Root mean square of successive RR interval differences (ms).

  • nn50 (int) – NN50 - Number of successive RR intervals that differ by more than 50ms.

  • pnn50 (float) – pNN50 - Percentage of successive RR intervals that differ by more than 50ms.

  • sdnn (float) – SDNN - Standard deviation of RR intervals (ms).

  • hti (float) – HTI - HRV triangular index - Integral of the density of the RR interval histogram divided by its height.

  • tinn (float) – TINN - Baseline width of RR interval histogram (ms).

biosppy.signals.hrv.rri_correction(rri=None, threshold=250)[source]

Corrects artifacts in an RRI sequence based on a local average threshold. Artifacts are replaced with cubic spline interpolation.

Parameters:

  • rri (array) – RR-intervals (ms).

  • threshold (int, float, optional) – Local average threshold (ms). Default: 250.

Returns:

rri (array) – Corrected RR-intervals (ms).

biosppy.signals.hrv.rri_filter(rri=None, threshold=1200)[source]

Filters an RRI sequence based on a maximum threshold in milliseconds.

Parameters:

  • rri (array) – RR-intervals (ms).

  • threshold (int, float, optional) – Maximum rri value to accept (ms).

Returns:

rri_filt (array) – Filtered RR-intervals (ms).

biosppy.signals.hrv.sample_entropy(rri, m=2, r=0.2)[source]

Computes the sample entropy of an RRI sequence.

Parameters:

  • rri (array) – RR-intervals (ms).

  • m (int, optional) – Embedding dimension. Default: 2.

  • r (int, float, optional) – Tolerance. It is then multiplied by the sequence standard deviation. Default: 0.2.

Returns:

sampen (float) – Sample entropy of the RRI sequence.

References

https://en.wikipedia.org/wiki/Sample_entropy