Heart Rate Variability

time_domain()

Compute time-domain HRV metrics from RR intervals

frequency_domain()

Compute frequency-domain HRV metrics from RR intervals

poincare()

Compute Poincaré plot descriptors (SD1, SD2)

Definitions follow the Task Force of the ESC and NASPE (1996), Heart rate variability: standards of measurement, physiological interpretation and clinical use, Circulation 93:1043–1065.

  • Input is a 1-D array of RR intervals in milliseconds. NaN, infinite or non-positive values raise ValueError.

  • The intervals are used as given. Ectopic beats and detection errors are not removed, so pass cleaned NN intervals when the result must follow the standard.

  • A metric that is undefined for the number of intervals is returned as nan: SDNN and RMSSD need 2 intervals, SDSD needs 3, frequency-domain metrics need 4, SD1/SD2 need 3.

Metric

Unit

Definition

sdnn

ms

Sample standard deviation of the intervals (ddof = 1)

rmssd

ms

Root mean square of successive differences

sdsd

ms

Sample standard deviation of successive differences

nn50_count, pnn50

count, %

Successive differences strictly greater than 50 ms, as a percentage of all differences

nn20_count, pnn20

count, %

Same with 20 ms

hr_mean, hr_std

bpm

Mean and sample standard deviation of 60000 / RR

vlf_power, lf_power, hf_power, total_power

ms²

Welch PSD of the RR series, cubic-interpolated at interp_fs (default 4 Hz, must be finite and above 0.8 Hz), integrated over 0–0.04, 0.04–0.15, 0.15–0.40 and 0–0.40 Hz

lf_hf_ratio

none

lf_power / hf_power (nan when HF is 0)

sd1, sd2

ms

std(RR[n+1] − RR[n]) / √2 and std(RR[n+1] + RR[n]) / √2

Warning

Frequency-domain metrics need enough data: the Task Force recommends at least 1 min for HF, 2 min for LF and 5 min for short-term analysis. frequency_domain() issues a UserWarning below 2 min (LF unreliable) and below 1 min (LF and HF unreliable). The RR intervals of a standard 10-second ECG are not enough for spectral HRV. Do not interpret VLF from recordings shorter than 5 min.

ecgdatakit.processing.time_domain(rr_ms)[source]

Compute time-domain HRV metrics from RR intervals.

Parameters:

rr_ms (NDArray[double]) – RR intervals in milliseconds (1-D, positive, finite).

Returns:

  • mean_rr (ms): mean interval; nan if empty.

  • sdnn (ms): sample standard deviation (ddof=1); needs 2 intervals.

  • rmssd (ms): root mean square of successive differences; needs 2.

  • sdsd (ms): standard deviation (ddof=1) of successive differences; needs 3.

  • nn50_count, nn20_count: successive differences strictly greater than 50 ms / 20 ms.

  • pnn50, pnn20 (%): counts divided by the number of successive differences; needs 2 intervals.

  • hr_mean (bpm): mean of 60000 / rr; nan if empty.

  • hr_std (bpm): sample standard deviation of 60000 / rr; needs 2.

Return type:

dict

Raises:

ValueError – If rr_ms is not 1-D or contains NaN, infinite or non-positive values.

ecgdatakit.processing.frequency_domain(rr_ms, method='welch', interp_fs=4.0)[source]

Compute frequency-domain HRV metrics from RR intervals.

RR intervals are placed at their beat times, interpolated (cubic) to a uniform series at interp_fs Hz, mean-removed, and the power spectral density is estimated with Welch’s method (segments of up to 256 samples, 64 s at 4 Hz). Band powers integrate the PSD over the Task Force bands: VLF 0–0.04 Hz, LF 0.04–0.15 Hz, HF 0.15–0.40 Hz, total 0–0.40 Hz.

The Task Force recommends at least 1 min of data for HF and 2 min for LF (5 min for short-term analysis). A UserWarning is issued when the recording is shorter than 2 min (LF unreliable) or 1 min (LF and HF unreliable). VLF from recordings shorter than 5 min should not be interpreted.

Parameters:

  • rr_ms (NDArray[double]) – RR intervals in milliseconds (1-D, positive, finite).

  • method (str) – PSD method. Only "welch" is supported.

  • interp_fs (float) – Interpolation sampling rate in Hz (default 4.0); must be above 0.8 Hz so the HF band lies below the Nyquist frequency.

Returns:

vlf_power, lf_power, hf_power, total_power in ms², and lf_hf_ratio (dimensionless). All values are nan when fewer than 4 intervals are given; lf_hf_ratio is nan when HF power is zero.

Return type:

dict

Raises:

ValueError – Unknown method, interp_fs not above 0.8 Hz or not finite, or invalid rr_ms.

ecgdatakit.processing.poincare(rr_ms)[source]

Compute Poincaré plot descriptors (SD1, SD2).

SD1 = std(RR[n+1] - RR[n]) / sqrt(2) and SD2 = std(RR[n+1] + RR[n]) / sqrt(2) (sample standard deviations).

Parameters:

rr_ms (NDArray[double]) – RR intervals in milliseconds (1-D, positive, finite).

Returns:

sd1 and sd2 in ms, sd1_sd2_ratio. All nan when fewer than 3 intervals are given; the ratio is nan when SD2 is 0.

Return type:

dict

Raises:

ValueError – If rr_ms is not 1-D or contains NaN, infinite or non-positive values.

Edit this page Report an issue