yasa.hrv_stage

yasa.hrv_stage(data, sf, *, hypno=None, include=(2, 3, 4), threshold='2min', equal_length=False, rr_limit=(400, 2000), verbose=False)[source]

Calculate heart rate and heart rate variability (HRV) features from an ECG.

By default, the cardiac features are calculated for each period of N2, N3 or REM sleep that are longer than 2 minutes.

New in version 0.6.2.

Parameters
datanumpy.ndarray

Single-channel ECG data. Must be a 1D NumPy array.

sffloat

The sampling frequency of the data.

hypnoarray_like

Sleep stage (hypnogram). The heart rate calculation will be applied for each sleep stage defined in include (default = N2, N3 and REM sleep separately).

The hypnogram must have the same number of samples as data. To upsample your hypnogram, please refer to yasa.hypno_upsample_to_data().

Note

The default hypnogram format in YASA is a 1D integer vector where:

  • -2 = Unscored

  • -1 = Artefact / Movement

  • 0 = Wake

  • 1 = N1 sleep

  • 2 = N2 sleep

  • 3 = N3 sleep

  • 4 = REM sleep

includetuple, list or int

Values in hypno that will be included in the mask. The default is (2, 3, 4), meaning that the detection is applied on N2, N3 and REM sleep separately.

thresholdstr

Only periods of a given stage that exceed the duration defined in threshold will be kept in subsequent analysis. The default is 2 minutes (‘2min’). Other possible values include: ‘5min’, ‘15min’, ’30sec’, ‘1hour’, etc. To disable thresholding, use ‘0min’.

equal_lengthbool

If True, the periods will all have the exact duration defined in threshold. That is, periods that are longer than the duration threshold will be divided into sub-periods of exactly the length of threshold.

rr_limittuple

Lower and upper limit for the RR interval. Default is 400 to 2000 ms, corresponding to a heart rate of 30 to 150 bpm. RR intervals outside this range will be set to NaN and filled with linear interpolation. Use rr_limit=(0, np.inf) to disable RR correction.

verbosebool or str

Verbose level. Default (False) will only print warning and error messages. The logging levels are ‘debug’, ‘info’, ‘warning’, ‘error’, and ‘critical’. For most users the choice is between ‘info’ (or verbose=True) and warning (verbose=False). Set this to True if you are getting invalid results and want to better understand what is happening.

Returns
epochspandas.DataFrame

Output dataframe with values (= the sleep stages defined in include) and epoch number as index. The columns are

  • start : The start of the epoch, in seconds from the beginning of the recording.

  • duration : The duration of the epoch, in seconds.

  • hr_mean: The mean heart rate (HR) across the epoch, in beats per minute (bpm).

  • hr_std: The standard deviation of the HR across the epoch, in bpm

  • hrv_rmssd: Heart rate variability across the epoch (RMSSD), in milliseconds.

rpeaksdict

A dictionary with the detected heartbeats (R-peaks) indices for each epoch of each stage. Indices are expressed as samples from the beginning of the epoch. This can be used to manually recalculate the RR intervals, apply a custom preprocessing on the RR intervals, and/or calculate more advanced HRV metrics.

Notes

This function returns three cardiac features for each epoch: the mean and standard deviation of the heart rate, and the root mean square of successive differences between normal heartbeats (RMSSD). The RMSSD reflects the beat-to-beat variance in HR and is the primary time-domain measure used to estimate the vagally mediated changes reflected in heart rate variability.

Heartbeat detection is performed with the SleepECG library: https://github.com/cbrnr/sleepecg

For an example of this function, please see the Jupyter notebook

References

  • Shaffer, F., & Ginsberg, J. P. (2017). An overview of heart rate variability metrics and norms. Frontiers in public health, 258.