skills/neurokit2/references/hrv.md
Checked 2026-07-23 against NeuroKit2 0.2.13 stable runtime/source, the official HRV API/tutorial, and HRV/RSA measurement guidance.
HRV analysis needs beat timing plus a defensible classification/correction policy. Distinguish:
Do not relabel automatically corrected RR or PPG intervals as NN. Preserve raw waveform, raw peaks, corrected peaks, excluded segments, correction categories, and interval units.
Accepted NeuroKit2 inputs include:
ecg_peaks(), ppg_peaks(), ecg_process(), or
bio_process(); andRRI (milliseconds) and RRI_Time (seconds).Always pass the sampling rate of the continuous signal in which peak indices were defined.
time = nk.hrv_time(peaks, sampling_rate=250)
frequency = nk.hrv_frequency(peaks, sampling_rate=250)
nonlinear = nk.hrv_nonlinear(peaks, sampling_rate=250)
all_domains = nk.hrv(peaks, sampling_rate=250)
All four return one-row DataFrames. hrv() concatenates the available domains and can
append RSA when its input contains processed respiration data. Columns vary with data
length, kwargs, available modalities, and release.
Pinned 0.2.13 observations:
hrv_time() returned 25 columns, including HRV_MeanNN, HRV_SDNN,
HRV_RMSSD, HRV_SDSD, HRV_CVNN, HRV_CVSD, robust interval summaries,
HRV_pNN50, HRV_pNN20, HRV_HTI, and HRV_TINN. Long-segment indices
(SDANN*, SDNNI*) can be NaN when duration is insufficient.hrv_frequency() returned exactly HRV_ULF, HRV_VLF, HRV_LF, HRV_HF,
HRV_VHF, HRV_TP, HRV_LFHF, HRV_LFn, HRV_HFn, and HRV_LnHF in the
default probe.hrv_nonlinear() returned Poincaré, asymmetry, fragmentation, DFA/MFDFA,
entropy/fractal, Lempel–Ziv, and symbolic-dynamics columns. Stable 0.2.13 added
default HRV_Symbolic_EqualProb4_* features.Do not hard-code a “complete” HRV column list. Persist list(result.columns) and map
only prespecified outputs.
Time-domain metrics are milliseconds where applicable. Frequency power is based on millisecond intervals and therefore commonly has ms²-derived units, but normalization and estimator settings change interpretation.
processed_rri, processed_time, interpolation_rate = nk.intervals_process(
rri_ms,
intervals_time=time_s,
interpolate=True,
interpolation_rate=4,
detrend=None,
)
peaks = nk.intervals_to_peaks(rri_ms, sampling_rate=1000)
intervals_process() returns three objects: intervals in milliseconds, timestamps in
seconds, and interpolation rate. intervals_to_peaks() returns integer peak indices,
with a constructed first peak. Verify external-device interval definitions and dropped
beats before conversion.
Duration requirements are metric-, population-, protocol-, and estimator-specific. Use these conservative planning principles:
Do not compare metrics estimated from unequal durations without a validated strategy. Report exact usable duration and beat count after exclusions, not nominal acquisition duration.
ecg_process() requests artifact correction automatically in 0.2.13. If that is not
the planned policy, run ecg_clean() and ecg_peaks() explicitly.
Heavy correction can manufacture smooth HRV. A segment with excessive ectopy, detachment, or motion may need exclusion rather than interpolation.
Stable signature:
hrv_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", normalize=True, interpolation_rate=100, ...
)
Set interpolation_rate=4 to approximate a common Kubios interpolation choice; set it
to None for already-interpolated intervals or Lomb–Scargle. Record detrending,
interpolation, PSD method, window/order, frequency bands, and normalization.
Do not interpret HRV_LFHF as a direct “sympathovagal balance.” LF contains mixed
influences; HF depends on breathing frequency/depth and can miss respiratory variation
outside the default 0.15–0.4 Hz band.
PPG pulse timing includes pre-ejection and pulse-transit effects, and varies with site, vascular state, posture, temperature, motion, contact pressure, and sensor design. Label results PRV/PPG-derived HRV and validate against synchronized ECG for the endpoint, conditions, sites, and population. Agreement at rest does not imply agreement during exercise or stress.
Stable signature:
hrv_rsa(
ecg_signals, rsp_signals=None, rpeaks=None,
sampling_rate=1000, continuous=False,
window=None, window_number=None
)
Use synchronized processed ECG and respiration DataFrames:
rsa = nk.hrv_rsa(
ecg_signals,
rsp_signals,
rpeaks=ecg_info,
sampling_rate=100,
continuous=False,
)
The pinned summary returned a dict with P2T and Gates statistics, including
RSA_P2T_Mean, RSA_P2T_SD, RSA_P2T_NoRSA, RSA_PorgesBohrer, and Gates
mean/SD/log fields. continuous=True returned a same-length DataFrame with
RSA_P2T and RSA_Gates.
Requirements:
RSA/HF-HRV is often related to cardiac vagal modulation but is not a direct, context-free vagal-tone assay. Respiration, activity, beta-adrenergic influence, age, posture, and within- versus between-person contrasts can change interpretation.