[docs]defhrv_frequency(peaks,sampling_rate=1000,ulf=(0,0.0033),vlf=(0.0033,0.04),lf=(0.04,0.15),hf=(0.15,0.4),vhf=(0.4,0.5),psd_method="welch",show=False,silent=True,normalize=True,order_criteria=None,interpolation_rate=100,**kwargs):"""**Computes frequency-domain indices of Heart Rate Variability (HRV)** Computes frequency domain HRV metrics, such as the power in different frequency bands. * **ULF**: The spectral power of ultra low frequencies (by default, .0 to .0033 Hz). Very long signals are required for this to index to be extracted, otherwise, will return NaN. * **VLF**: The spectral power of very low frequencies (by default, .0033 to .04 Hz). * **LF**: The spectral power of low frequencies (by default, .04 to .15 Hz). * **HF**: The spectral power of high frequencies (by default, .15 to .4 Hz). * **VHF**: The spectral power of very high frequencies (by default, .4 to .5 Hz). * **TP**: The total spectral power. * **LFHF**: The ratio obtained by dividing the low frequency power by the high frequency power. * **LFn**: The normalized low frequency, obtained by dividing the low frequency power by the total power. * **HFn**: The normalized high frequency, obtained by dividing the low frequency power by the total power. * **LnHF**: The log transformed HF. Note that a minimum duration of the signal containing the peaks is recommended for some HRV indices to be meaningful. For instance, 1, 2 and 5 minutes of high quality signal are the recommended minima for HF, LF and LF/HF, respectively. .. tip:: We strongly recommend checking our open-access paper `Pham et al. (2021) <https://doi.org/10.3390/s21123998>`_ on HRV indices for more information. Parameters ---------- peaks : dict Samples at which cardiac extrema (i.e., R-peaks, systolic peaks) occur. Can be a list of indices or the output(s) of other functions such as :func:`.ecg_peaks`, :func:`.ppg_peaks`, :func:`.ecg_process` or :func:`.bio_process`. Can also be a dict containing the keys `RRI` and `RRI_Time` to directly pass the R-R intervals and their timestamps, respectively. sampling_rate : int, optional Sampling rate (Hz) of the continuous cardiac signal in which the peaks occur. ulf : tuple, optional Upper and lower limit of the ultra-low frequency band. By default (0, 0.0033). vlf : tuple, optional Upper and lower limit of the very-low frequency band. By default (0.0033, 0.04). lf : tuple, optional Upper and lower limit of the low frequency band. By default (0.04, 0.15). hf : tuple, optional Upper and lower limit of the high frequency band. By default (0.15, 0.4). vhf : tuple, optional Upper and lower limit of the very-high frequency band. By default (0.4, 0.5). psd_method : str Method used for spectral density estimation. For details see :func:`.signal_power`. By default ``"welch"``. silent : bool If ``False``, warnings will be printed. Default to ``True``. show : bool If ``True``, will plot the power in the different frequency bands. normalize : bool Normalization of power by maximum PSD value. Default to ``True``. Normalization allows comparison between different PSD methods. order_criteria : str The criteria to automatically select order in parametric PSD (only used for autoregressive (AR) methods such as ``"burg"``). Defaults to ``None``. interpolation_rate : int, optional Sampling rate (Hz) of the interpolated interbeat intervals. Should be at least twice as high as the highest frequency in vhf. By default 100. To replicate Kubios defaults, set to 4. To not interpolate, set interpolation_rate to None (in case the interbeat intervals are already interpolated or when using the ``"lombscargle"`` psd_method for which interpolation is not required). **kwargs Additional other arguments. Returns ------- DataFrame DataFrame consisting of the computed HRV frequency metrics, which includes: .. codebookadd:: HRV_ULF|The spectral power of ultra low frequencies (by default, .0 to .0033 Hz). \ Very long signals are required for this to index to be extracted, otherwise, \ will return NaN. HRV_VLF|The spectral power of very low frequencies (by default, .0033 to .04 Hz). HRV_LF|The spectral power of low frequencies (by default, .04 to .15 Hz). HRV_HF|The spectral power of high frequencies (by default, .15 to .4 Hz). HRV_VHF|The spectral power of very high frequencies (by default, .4 to .5 Hz). HRV_TP|The total spectral power. HRV_LFHF|The ratio obtained by dividing the low frequency power by the high frequency \ power. HRV_LFn|The normalized low frequency, obtained by dividing the low frequency power by \ the total power. HRV_HFn|The normalized high frequency, obtained by dividing the low frequency power by \ the total power. HRV_LnHF|The log transformed HF. See Also -------- ecg_peaks, ppg_peaks, hrv_summary, hrv_time, hrv_nonlinear Examples -------- .. ipython:: python import neurokit2 as nk # Download data data = nk.data("bio_resting_5min_100hz") # Find peaks peaks, info = nk.ecg_peaks(data["ECG"], sampling_rate=100) # Compute HRV indices using method="welch" @savefig p_hrv_freq1.png scale=100% hrv_welch = nk.hrv_frequency(peaks, sampling_rate=100, show=True, psd_method="welch") @suppress plt.close() .. ipython:: python # Using method ="burg" @savefig p_hrv_freq2.png scale=100% hrv_burg = nk.hrv_frequency(peaks, sampling_rate=100, show=True, psd_method="burg") @suppress plt.close() .. ipython:: python # Using method = "lomb" (requires installation of astropy) @savefig p_hrv_freq3.png scale=100% hrv_lomb = nk.hrv_frequency(peaks, sampling_rate=100, show=True, psd_method="lomb") @suppress plt.close() .. ipython:: python # Using method="multitapers" @savefig p_hrv_freq4.png scale=100% hrv_multitapers = nk.hrv_frequency(peaks, sampling_rate=100, show=True,psd_method="multitapers") @suppress plt.close() References ---------- * Pham, T., Lau, Z. J., Chen, S. H. A., & Makowski, D. (2021). Heart Rate Variability in Psychology: A Review of HRV Indices and an Analysis Tutorial. Sensors, 21(12), 3998. * Stein, P. K. (2002). Assessing heart rate variability from real-world Holter reports. Cardiac electrophysiology review, 6(3), 239-244. * Shaffer, F., & Ginsberg, J. P. (2017). An overview of heart rate variability metrics and norms. Frontiers in public health, 5, 258. * Boardman, A., Schlindwein, F. S., & Rocha, A. P. (2002). A study on the optimum order of autoregressive models for heart rate variability. Physiological measurement, 23(2), 325. * Bachler, M. (2017). Spectral Analysis of Unevenly Spaced Data: Models and Application in Heart Rate Variability. Simul. Notes Eur., 27(4), 183-190. """# Sanitize input# If given peaks, compute R-R intervals (also referred to as NN) in millisecondsrri,rri_time,_=_hrv_format_input(peaks,sampling_rate=sampling_rate)# Process R-R intervals (interpolated at 100 Hz by default)rri,rri_time,sampling_rate=intervals_process(rri,intervals_time=rri_time,interpolate=True,interpolation_rate=interpolation_rate,**kwargs)ifinterpolation_rateisNone:t=rri_timeelse:t=Nonefrequency_band=[ulf,vlf,lf,hf,vhf]# Find maximum frequencymax_frequency=np.max([np.max(i)foriinfrequency_band])power=signal_power(rri,frequency_band=frequency_band,sampling_rate=sampling_rate,method=psd_method,max_frequency=max_frequency,show=False,normalize=normalize,order_criteria=order_criteria,t=t,**kwargs)power.columns=["ULF","VLF","LF","HF","VHF"]out=power.to_dict(orient="index")[0]out_bands=out.copy()# Components to be entered into plotifsilentisFalse:forfrequencyinout.keys():ifout[frequency]==0.0:warn("The duration of recording is too short to allow"" reliable computation of signal power in frequency band "+frequency+"."" Its power is returned as zero.",category=NeuroKitWarning,)# Normalizedtotal_power=np.nansum(power.values)out["TP"]=total_powerout["LFHF"]=out["LF"]/out["HF"]out["LFn"]=out["LF"]/total_powerout["HFn"]=out["HF"]/total_power# Logout["LnHF"]=np.log(out["HF"])# pylint: disable=E1111out=pd.DataFrame.from_dict(out,orient="index").T.add_prefix("HRV_")# Plotifshow:_hrv_frequency_show(rri,out_bands,ulf=ulf,vlf=vlf,lf=lf,hf=hf,vhf=vhf,sampling_rate=sampling_rate,psd_method=psd_method,order_criteria=order_criteria,normalize=normalize,max_frequency=max_frequency,t=t,)returnout
def_hrv_frequency_show(rri,out_bands,ulf=(0,0.0033),vlf=(0.0033,0.04),lf=(0.04,0.15),hf=(0.15,0.4),vhf=(0.4,0.5),sampling_rate=1000,psd_method="welch",order_criteria=None,normalize=True,max_frequency=0.5,t=None,**kwargs):if"ax"inkwargs:ax=kwargs.get("ax")kwargs.pop("ax")else:__,ax=plt.subplots()frequency_band=[ulf,vlf,lf,hf,vhf]# Compute sampling rate for plot windowsifsampling_rateisNone:med_sampling_rate=np.median(np.diff(t))# This is just for visualization purposes (#800)else:med_sampling_rate=sampling_rateforiinrange(len(frequency_band)):# pylint: disable=C0200min_frequency=frequency_band[i][0]ifmin_frequency==0:min_frequency=0.001# sanitize lowest frequencywindow_length=int((2/min_frequency)*med_sampling_rate)ifwindow_length<=len(rri)/2:breakpsd=signal_psd(rri,sampling_rate=sampling_rate,show=False,min_frequency=min_frequency,method=psd_method,max_frequency=max_frequency,order_criteria=order_criteria,normalize=normalize,t=t,)_signal_power_instant_plot(psd,out_bands,frequency_band,ax=ax)