Heart Rate variability biomarkers

This module computes HRV biomarkers based on the mhrv MATLAB package.

pyPSG.biomarkers.hrv_bms

pyPSG.biomarkers.hrv_bms.buffer(X, n, p=0, opt=None)

Mimic MATLAB routine to generate buffer array

MATLAB docs here: https://se.mathworks.com/help/signal/ref/buffer.html

Parameters:

  • x (ndarray) – signal array

  • n (int) – number of data segments

  • p (int) – number of values to overlap

  • opt – Initial condition options. default sets the first p values to zero, while ‘nodelay’ begins filling the buffer immediately.

Returns:

buffer array created from x ((n,n)ndarray)

pyPSG.biomarkers.hrv_bms.comp_AVNN(segment)

This function returns the mean RR interval (AVNN) over a segment of RR time series.

Parameters:

segment (1d-array) – The input RR intervals time-series in seconds.

Returns:

AVNN: The mean RR interval over the segment.

pyPSG.biomarkers.hrv_bms.comp_DFA(segment, n_min=4, n_max=64, n_incr=2, alpha1_range=(4, 15), alpha2_range=(16, 64))

Calculates the DFA (detrended fluctuation analysis) of a signal and it’s scaling exponents.

Parameters:

  • segment (1d-array) – The input RR intervals time-series.

  • n_min (int, optional) – Minimal DFA block-size (default 4)

  • n_max – Maximal DFA block-size (default 64)

  • n_incr (int, optional) – increment value for n (default 2). Can also be less than 1, in which case we interpret it as the ratio of a geometric series on box sizes (n). This should produce box size values identical to the PhysioNet DFA implmentation.

  • alpha1_range (tuple, optional) – Range of block size values to use for calculating the alpha_1 scaling exponent. Default: [4, 15].

  • alpha2_range (tuple, optional) – Range of block size values to use for calculating the alpha_2 scaling exponent. Default: [16, 64].

Return: alpha1: Log-log slope of DFA in the low-scale region, alpha2: Log-log slope of DFA in the high-scale region

pyPSG.biomarkers.hrv_bms.comp_IALS(segment)

Compute the Inverse Average Length of Segments (IALS) in an NN interval segment.

The segments are defined between inflection points.

Parameters:

segment (ndarray) – 1D array of NN intervals.

Returns:

IALS – Inverse of the mean segment length.

Return type:

float

pyPSG.biomarkers.hrv_bms.comp_MSE(segment, normalize_std=True, mse_max_scale=15, sampen_m=2, sampen_r=0.2, mse_metrics=False)

Calculates the Multiscale Entropy (MSE) of a signal.

Multiscale Entropy is a measure of a signal’s complexity. This function computes the Sample Entropy of the signal at various scales from 1 to mse_max_scale. At each scale, the signal is downsampled by averaging scale samples, and Sample Entropy is calculated for the resulting coarse-grained signal.

Parameters:

  • sig (array_like) – Signal to calculate MSE for.

  • mse_max_scale (int, optional) – Maximal scale to calculate up to. Default is 15.

  • sampen_r (float, optional) – The ‘r’ parameter for Sample Entropy (maximum distance between matching points). Default is 0.2.

  • sampen_m (int, optional) – The ‘m’ parameter for Sample Entropy (template length). Default is 2.

  • normalize_std (bool, optional) – Whether to normalize the signal to std=1 before entropy calculation. This affects the meaning of r.

  • plot (bool, optional) – Whether to generate a plot of the results. Defaults to True if no output is returned.

Returns:

  • mse_result (ndarray): The Sample Entropy value at each scale.

  • scale_axis (ndarray): The scale values corresponding to each MSE value.

pyPSG.biomarkers.hrv_bms.comp_PAS(segment)

Compute the Percentage of Alternating Segments (PAS) in an NN interval segment.

Alternating segments are those where the segment length is > 3. This metric calculates the percentage of RR intervals that fall into such alternating segments.

Parameters:

segment (ndarray) – 1D array of RR intervals.

Returns:

PAS – Percentage of NN intervals in alternating segments of length > 3.

Return type:

float

pyPSG.biomarkers.hrv_bms.comp_PIP(segment)

Compute the Percentage of Inflection Points (PIP) in an NN interval segment.

An inflection point is defined where the delta NN interval changes sign. Fake points are added at the beginning and end to enclose edge segments.

Parameters:

segment (ndarray) – 1D array of NN intervals.

Returns:

PIP – Percentage of inflection points in the segment.

Return type:

float

pyPSG.biomarkers.hrv_bms.comp_PNN20(segment)

This function returns the percentage of the RR interval differences above .02 over a segment of RR time series.

Parameters:

segment (1d-array) – The input RR intervals time-series.

Return PNN20:

The percentage of the RR interval differences above .02.

pyPSG.biomarkers.hrv_bms.comp_PNN50(segment)

This function returns the percentage of the RR interval differences above .05 over a segment of RR time series. :param segment: The input RR intervals time-series. :type segment: 1d-array :return PNN50: The percentage of the RR interval differences above .05.

pyPSG.biomarkers.hrv_bms.comp_PSS(segment)

Compute the Percentage of Short Segments (PSS) in an NN interval segment.

Short segments are defined as segments with fewer than 3 NN intervals.

Parameters:

segment (ndarray) – 1D array of NN intervals.

Returns:

PSS – Percentage of NN intervals that belong to short segments.

Return type:

float

pyPSG.biomarkers.hrv_bms.comp_RMSSD(segment)

This function returns the square root of mean summed squares of RR interval differences.

Parameters:

segment (1d-array) – The input RR intervals time-series.

Returns:

RMSSD: square root of mean summed squares of NN interval differences.

pyPSG.biomarkers.hrv_bms.comp_SD1(segment)

Calculates the standard deviation of RR intervals along the axis perpendicular to the line of identity.

Parameters:

segment (1d-array) – The input RR intervals time-series.

Returns:

SD1: standard deviation of RR intervals along the axis perpendicular to the line of identity

pyPSG.biomarkers.hrv_bms.comp_SD2(segment)

Calculates the standard deviation of RR intervals along the line of identity..

Parameters:

segment (1d-array) – The input RR intervals time-series.

Returns:

SD1: standard deviation of RR intervals along the line of identity

pyPSG.biomarkers.hrv_bms.comp_SDNN(segment)

This function returns the standard deviation over the RR intervals (SDNN) found in the input.

Parameters:

segment (1d-array) – The input RR intervals time-series.

Returns:

SDNN: The std. dev. over the RR intervals.

pyPSG.biomarkers.hrv_bms.comp_SEM(segment)

This function returns standard error of the mean NN interval length.

Parameters:

segment (1d-array) – The input RR intervals time-series.

Returns:

SEM: Standard error of the mean NN interval

pyPSG.biomarkers.hrv_bms.comp_alpha_1(segment)

Calculates the log-log slope of DFA in the low-scale region

Parameters:

segment (1d-array) – The input RR intervals time-series.

Returns:

alpha1: log-log slope of DFA in the low-scale region

pyPSG.biomarkers.hrv_bms.comp_alpha_2(segment)

Calculates the log-log slope of DFA in the low-scale region

Parameters:

segment (1d-array) – The input RR intervals time-series.

Returns:

alpha2: log-log slope of DFA in the high-scale region

pyPSG.biomarkers.hrv_bms.comp_freq(segment, vlf_band=[0.003, 0.04], lf_band=[0.04, 0.15], hf_band=[0.15, 0.4], resample_factor=2.25, freq_osf=4, welch_overlap=50, window_minutes=5)

Compute frequency-domain HRV metrics using resampled RR interval data and Welch’s method. This function estimates the PSD (power spectral density) of a given nn-interval sequence, and calculates the power in various frequency bands.

Parameters:

  • segment (ndarray) – Sequence of NN intervals in seconds.

  • vlf_band (list, optional) – Frequency band for Very Low Frequency (VLF) power, default is [0.003, 0.04] Hz.

  • lf_band (list, optional) – Frequency band for Low Frequency (LF) power, default is [0.04, 0.15] Hz.

  • hf_band (list, optional) – Frequency band for High Frequency (HF) power, default is [0.15, 0.4] Hz.

  • resample_factor (float, optional) – Multiplier for determining uniform resampling frequency (fs = resample_factor × max freq). Default is 2.25.

  • freq_osf (int, optional) – Frequency oversampling factor to increase frequency resolution. Default is 4.

  • welch_overlap (int, optional) – Overlap percentage between Welch windows (0–100). Default is 50.

  • window_minutes (int, optional) – Length of each Welch window in minutes. Default is 5.

Returns:

  • total_power (float): Total spectral power across full frequency range.

  • vlf_power (float): Absolute power in VLF band.

  • lf_power (float): Absolute power in LF band.

  • hf_power (float): Absolute power in HF band.

  • vlf_norm (float): Normalized VLF power (% of total).

  • lf_norm (float): Normalized LF power (% of total).

  • hf_norm (float): Normalized HF power (% of total).

  • lf_hf_ratio (float): LF/HF power ratio.

Return type:

tuple

pyPSG.biomarkers.hrv_bms.comp_poincare(segment)

Calculates HRV metrics from a Poincaré plot of the input data.

Parameters:

segment (1d-array) – The input RR intervals time-series.

Return:sd1:

Standard deviation of RR intervals along the axis perpendicular to the line of identity. sd2: Standard deviation of RR intervals along the line of identity.

pyPSG.biomarkers.hrv_bms.comp_sample_entropy(segment, m, r)

Calculate sample entropy (SampEn) of a signal.

Sample entropy is a measure of the irregularity of a signal.

Parameters:

  • segment (array_like) – The input signal.

  • m (int) – Template length in samples.

  • r (float) – Threshold for matching sample values.

Returns:

The sample entropy value of the input signal.

Return type:

float

pyPSG.biomarkers.hrv_bms.fragmentation_metrics(segment)

Compute fragmentation-related features from an NN interval segment.

Detects inflection points based on changes in the sign of successive differences, and computes the segment lengths between them.

Parameters:

segment (ndarray) – 1D array of NN intervals (e.g., RR intervals).

Returns:

  • N (int): Total number of NN intervals.

  • ip (ndarray): Binary array indicating inflection points (1 where inflection occurs).

  • segment_lengths (ndarray): Lengths of segments between inflection points.

Return type:

tuple

pyPSG.biomarkers.hrv_bms.freqband_power(pxx, f_axis, f_band)

Calculates the power in a frequency band.

Parameters:

  • pxx (ndarray) – Power spectral density values.

  • f_axis (ndarray) – Frequency axis corresponding to pxx.

  • f_band (list or tuple or ndarray, length 2) – Frequency band [f_low, f_high] over which to integrate the power.

Returns:

Power within the specified frequency band.

Return type:

float

pyPSG.biomarkers.hrv_bms.get_all_metrics(rr_intervals, win_len, include_last_partial=False, min_intervals=2)

Calculate all metrics for given intervals.

Parameters:

rr_intervals (1d-array) – The input RR intervals time-series in seconds.

Returns:

A dictionary with all metrics for given intervals.