GitHub

Heart Rate Variability Features

HeartRateLab extracts 53 HRV features across 4 analysis domains from inter-beat-interval (IBI) time series data.

Every feature has a full "Pokédex" entry in the HRV Variable Zoo: definition, equation, normative distribution, resource cost, seminal citation, and per-field application evidence (clinical, sports & peak-performance, contemplative practice), all referenced against the HRV knowledge base.

Feature Domains

1. Time Domain (20 features)

Statistics of the NN/RR intervals and their successive differences, the classic, cheapest, most-reported HRV panel:

  • mean: Mean inter-beat interval
  • sdnn: Standard deviation of NN intervals
  • median: Median inter-beat interval
  • max: Maximum inter-beat interval
  • min: Minimum inter-beat interval
  • mean_hr: Mean heart rate (BPM)
  • std_hr: Standard deviation of heart rate
  • max_hr: Maximum heart rate
  • min_hr: Minimum heart rate
  • median_hr: Median heart rate (BPM)
  • range_hr: Range (max − min) of instantaneous heart rate
  • sdsd: Standard deviation of successive differences
  • range: Range of inter-beat intervals
  • rmssd: Root mean square of successive differences
  • sdann: Standard deviation of 5-min average NN intervals
  • pnn50: Proportion of successive differences > 50 ms
  • pnn20: Proportion of successive differences > 20 ms
  • cvsd: Coefficient of variation of successive differences
  • cvnni: Coefficient of variation of NN intervals (SDNN / mean)
  • rRR: Median relative RR interval distance

2. Frequency Domain (12 features)

Power in the ULF/VLF/LF/HF bands of the RR power spectrum, plus band ratios and peak frequencies:

  • ulf: Ultra-low frequency power (0–0.003 Hz)
  • vlf: Very low frequency power (0.003–0.04 Hz)
  • lf: Low frequency power (0.04–0.15 Hz)
  • hf: High frequency power (0.15–0.4 Hz)
  • tp: Total power (0.003–0.4 Hz)
  • lf_peak: Peak frequency in the LF band
  • hf_peak: Peak frequency in the HF band
  • lf_hf_ratio: LF/HF power ratio
  • lf_relative: LF power as proportion of total power
  • hf_relative: HF power as proportion of total power
  • lf_percentage: LF power as percentage of total power
  • hf_percentage: HF power as percentage of total power

3. Geometric (8 features)

Shape descriptors of the Poincaré / Lorenz return map and the RR histogram, robust to occasional artifacts:

  • sd1: Poincaré plot short-term variability
  • sd2: Poincaré plot long-term variability
  • sd2_sd1: Ratio of SD2 to SD1 (cardiac sympathetic index)
  • sd1_sd2_area: Poincaré plot ellipse area
  • cvi: Cardiac vagal index
  • ccsi: Corrected cardiac sympathetic index
  • triangular_index: HRV triangular index
  • tinn: Triangular interpolation of the NN interval histogram

4. Nonlinear (13 features)

Entropy, complexity, and fractal-scaling measures probing the nonlinear structure of cardiac control (need adequate record length):

  • apen: Approximate entropy
  • sampen: Sample entropy
  • hurst: Hurst exponent
  • renyi0: Rényi entropy of order 0
  • renyi1: Rényi entropy of order 1 (Shannon)
  • renyi2: Rényi entropy of order 2
  • shan_en: Shannon entropy of the IBI histogram
  • svd_en: Singular value decomposition entropy
  • fuzzyen: Fuzzy entropy
  • spec_en: Spectral entropy
  • perm_en: Permutation entropy
  • mse: Multiscale entropy complexity index
  • dfa2: Detrended fluctuation analysis long-term scaling exponent (α₂)

The short-term DFA exponent α₁ is available as the dfa1 representation (HeartRateLab.Features.function_registry["dfa1"](m)), a building block rather than a registry feature, so it does not appear in extract_feature_set output.

Feature Extraction

Basic Usage

extract_feature_set returns a one-row DataFrame with one column per feature. The features keyword selects a preset set (:default, :fast, :all, :nonlinear) or an explicit vector of feature names:

using HeartRateLab

# Load data
ibis = read_txt("data.txt")

# Default set (time, frequency, geometric: excludes nonlinear and ulf)
features = extract_feature_set(ibis)

# All 53 features (adds the expensive nonlinear set)
features_all = extract_feature_set(ibis; features=:all)

# Only the nonlinear features
features_nl = extract_feature_set(ibis; features=:nonlinear)

# Custom subset by name
features_custom = extract_feature_set(ibis; features=["mean", "sdnn", "rmssd", "lf", "hf"])

Signal Length Requirements

Different features require minimum signal lengths:

# Check valid features for a given signal length
valid = valid_features(length(ibis))

# Features table
# Signal length 10:  14 features
# Signal length 50:  30 features
# Signal length 100: 41 features
# Signal length 128: 53 features (all)

Feature Preprocessing

Features are automatically computed with preprocessing:

# Preprocessing steps (automatic)
# 1. Replace outliers with NaN
# 2. Interpolate missing values
# 3. Compute features from clean IBI series
# 4. Return NaN for invalid features

# Note: ensure input IBIs are in milliseconds

API Reference