📄 / / profiles / r-and-d / raw_evidence / scientific-agent-skills / skills / neurokit2 / references / hrv.md

Heart-rate variability and RSA

Heart-rate variability and RSA

Checked 2026-07-23 against NeuroKit2 0.2.13 stable runtime/source, the official HRV API/tutorial, and HRV/RSA measurement guidance.

Define the interval series

HRV analysis needs beat timing plus a defensible classification/correction policy. Distinguish:

RR/RRI: intervals between detected R peaks;
NN: intervals between beats judged normal sinus beats; and
PP/PRV: intervals between peripheral pulse peaks.

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:

a list/array of peak sample indices;
marker/info objects from ecg_peaks(), ppg_peaks(), ecg_process(), or bio_process(); and
a dict with RRI (milliseconds) and RRI_Time (seconds).

Always pass the sampling rate of the continuous signal in which peak indices were defined.

Current functions and schemas

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.

Units and interval helpers

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.

Recording duration

Duration requirements are metric-, population-, protocol-, and estimator-specific. Use these conservative planning principles:

Five minutes is the conventional standardized short-term HRV window.
RMSSD can be computed on shorter windows, but ultra-short estimates require endpoint- and population-specific reliability/validity evidence.
A spectral segment should contain enough cycles of the lowest frequency interpreted. Five minutes is a practical reference for conventional LF/HF short-term analysis.
Do not interpret ULF from a short recording; it is conventionally associated with long, often 24-hour recordings.
VLF physiological interpretation in short recordings is uncertain.
Entropy, DFA, MFDFA, correlation dimension, and RQA need enough beats for stable estimation; defaults returning a number do not establish adequacy.

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.

Ectopy and artifact policy

Inspect ECG/PPG quality and peak overlays.
Review the tachogram and interval histogram.
Identify non-sinus beats separately from detector errors when possible.
Report raw and corrected beat counts and percentage.
Limit interpolation/correction according to a prespecified exclusion rule.
Repeat key analyses under plausible correction choices.

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.

Frequency domain

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-derived variability

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.

Respiratory sinus arrhythmia

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:

shared clock, sampling grid, and defined lag/drift policy;
valid R peaks and respiration cycles;
enough cycles/windows for the chosen method;
measured respiration rate and context; and
reporting of P2T/Gates method and all window parameters.

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.

Analysis/report checklist

package version and observed output schema;
ECG/PPG source, sensor/site, sampling, clock, units, and raw-data access;
duration, usable duration, beat count, and exclusions;
peak detector, quality method, ectopy/artifact criteria, and correction percentage;
RRI/NN/PRV terminology;
PSD/interpolation/detrending/bands/normalization;
respiration measurement and rate/depth context;
prespecified metrics and multiplicity control; and
no diagnostic, monitoring, or medical-device claim without separate validation.