Awesome

mhrv

mhrv is a matlab toolbox for calculating Heart-Rate Variability (HRV) metrics from both ECG signals and RR-interval time series. The toolbox works with ECG data in the PhysioNet [1] WFDB data format.

Features

• WFDB wrappers and helpers. A small subset of the PhysioNet WFDB tools are wrapped with matlab functions, to allow using them directly from matlab. For example,

  • mhrv.wfdb.gqrs - A QRS detection algorithm.
  • mhrv.wfdb.rdsamp - For reading PhysioNet signal data into matlab.
  • mhrv.wfdb.rdann - For reading PhysioNet annotation data into matlab.
  • mhrv.wfdb.wrann - For writing PhysioNet annotation data from matlab datatypes.
  • mhrv.wfdb.wfdb_header - Read record metadata from a WFDB header file (.hea).

• ECG signal processing. Peak detection and RR interval extraction from ECG data in PhysioNet format. For example,

  • mhrv.wfdb.rqrs - Detection of R-peaks in ECG signals (based on PhysioNet's gqrs). Configurable for use with both human and animal ECGs.
  • mhrv.ecg.jqrs/mhrv.ecg.wjqrs - An ECG peak-detector based on a modified Pan & Tompkins algorithm and a windowed version.
  • mhrv.ecg.bpfilt- Bandpass filtering for removing noise artifacts from ECG signals.
  • mhrv.wfdb.ecgrr - Construction of RR intervals from ECG data in PhysioNet format.
  • mhrv.wfdb.qrs_compare - Comparison of QRS detections to reference annotations and calculation of quality measures like Sensitivity, PPV.

• RR-intervals signal processing. Ectopic beat rejection, frequency filtering, nonlinear dynamic and fractal analysis. For example,

  • mhrv.rri.filtrr - Filtering of RR interval time series to detect ectopic (out of place) beats.
  • mhrv.rri.dfa - Detrended Fluctuation Analysis, a method of estimating the fractal scaling exponent of a signal [3].
  • mhrv.rri.mse - Multiscale Sample Entropy, a measure of the complexity of the signal computed on multiple time scales [4].
  • mhrv.rri.sample_entropy - Sample Entropy, a measure of the irregularity of a signal.

• HRV Metrics: Calculating quantitative measures that indicate the activity of the heart based on RR intervals using all standard HRV metrics defined in the literature (see e.g. [2]).

  • mhrv.hrv.hrv_time - Time Domain: AVNN, SDNN, RMSSD, pNNx.
  • mhrv.hrv.hrv_freq - Frequency Domain:
    • Total and normalized power in (configurable) VLF, LF, HF and custom user-defined bands.
    • Spectral power estimation using Lomb, Auto Regressive, Welch and FFT methods.
    • Additional frequency-domain features: LF/HF ratio, LF and HF peak frequencies, power-law scaling exponent (beta).
  • mhrv.hrv.hrv_nonlinear - Nonlinear methods:
    • Short- and long-term scaling exponents (alpha1, alpha2) based on DFA.
    • Sample Entropy and Multiscale sample entropy (MSE).
    • Poincaré plot metrics (SD1, SD2).
  • mhrv.hrv.hrv_fragmentation - Time-domain RR interval fragmentation analysis [5].

• Configuration: The toolbox is fully configurable with many user-adjustable parameters.

  • The configuration files are in human-readable YAML format which is easy to edit and extend.
  • The user can create custom configurations files based on the defatuls.yml file (only overriding what's required).
  • Custom configuration files can be loaded with a single call which updates the defaults for the entire toolbox. This allows simple, reproducible analysis of different datasets that require different analysis configurations. See the mhrv.defaults package.
  • The settings for any of the functions can either be configured globally with configuration yml files or on a per-call basis with matlab-style key-value argument pairs.

• Plotting: All toolbox functions support plotting their output for data visualization. The plotting code is separated from the algorithmic code in order to simplify embedding this toolbox in other matlab applications. See the mhrv.plots package.

• Top-level analysis functions: These functions work with PhysioNet records and allow streamlined HRV analysis by composing the functions of this toolbox.

  • mhrv.mhrv - Analyzes a single PhysioNet record (ECG data or annotations), optionally split into multiple analysis windows. Extracts all supported HRV features and optionally generates plots.
  • mhrv.mhrv_batch - Analyzes many PhysioNet records (ECG data or annotations) which can be further separated into user-defined groups (e.g. Control, Test). Automatically computes HRV metrics per group and generates a comparative summary of the HRV features in each group.

Requirements

• Matlab with Signal Processing toolbox. Should work on Matlab R2014b or newer.
• The PhysioNet WFDB tools. The toolbox can install this for you.

Installation

1. Clone the repo or download the source code.

2. From matlab, run the mhrv_init function from the root of the repo. This function will:

   • Check for the presence of the WFDB tools in your system PATH.
   • If WFDB tools are not detected, it will attempt to automatically download them for you into the folder bin/wfdb under the repository root.
   • Set up your MATLAB path to include the code from this toolbox.

Notes about matlab's pwd and path

Matlab maintains a PWD, or "present working directory". It's the folder you see at the top of the interface, containing the files you see in the file explorer pane. Type pwd at the matlab command prompt to see it's value.

Additionally, matlab maintains a PATH variable, containing a list of folders in which it searches for function definitions (similar to the shell PATH concept). Type path at the matlab command prompt to see it's value.

You don't need to change your pwd to the root of the repo folder for the toolbox to work. You can simple run the mhrv_init function from your current pwd, and it will take care of updating matlab's path. For example, if you cloned or downloaded the toolbox in the folder /Users/myname/mhrv/, you can run the following command from the matlab prompt:

run /Users/myname/mhrv/mhrv_init.m

After this the toolbox will be ready to use, regardless of your pwd.

Manual WFDB Installation

The above steps should be enough to get most users started. In some cases mhrv_init may fail to download the correct binaries for you, or you may want to install them yourself.

• On macOS, you can use homebrew. First install homebrew, then install wfdb with brew tap brewsci/science && brew install -s wfdb.
• On any OS (including macOS), you can compile the WFDB binaries from source using the instructions on their website.

Once you have the binaries, place them in some folder on your $PATH or somewhere under the repo's root folder (bin/wfdb would be a good choice as it's .gitignored) and they will be found and used automatically. You can replace the binaries that were automatically downloaded with your compiled ones. If you used homebrew, they should already be on your $PATH.

If you would like to manually specify a path outside the repo which contains the WFDB binaries (e.g. /usr/local/bin for a homebrew install), you can edit cfg/defaults.yml and set the mhrv.paths.wfdb_path variable to the desired path.

For macOS users it's recommended to install with homebrew, and for linux users it's recommended to install from source, as the binaries provided on the PhysioNet website are very outdated.

Documentation

Documentation is available on readthedocs.

Usage

Exaple of calculating HRV measures for a PhysioNet record downloaded from PhysioNet (in this case from mitdb):

% Download the mitdb/111 record from PhysioNet to local folder named 'db'
>> mhrv.wfdb.download_wfdb_records('mitdb', '111', 'db');

[0.210] >> mitdb: Found 48 records
[0.300] >> mitdb: Found 1 annotators
[0.400] >> mitdb: Downloaded: 111.hea -> db/mitdb/111.hea
[0.500] >> mitdb: Downloaded: 111.atr -> db/mitdb/111.atr
[1.030] >> mitdb: Downloaded: 111.dat -> db/mitdb/111.dat
[1.040] >> mitdb: Done, 1 records downloaded.

% Run HRV analysis
>> mhrv.mhrv('db/mitdb/111', 'window_minutes', 15, 'plot', true);

[0.010] >> mhrv: Processing record db/mitdb/111 (ch. 1)...
[0.010] >> mhrv: Signal duration: 00:30:05.555 [HH:mm:ss.ms]
[0.020] >> mhrv: Analyzing window 1 of 2...
[0.020] >> mhrv: [1/2] Detecting RR intervals from ECG... 1046 intervals detected.
[0.280] >> mhrv: [1/2] Removing ectopic intervals... 13 intervals removed.
[0.300] >> mhrv: [1/2] Calculating time-domain metrics...
[0.310] >> mhrv: [1/2] Calculating frequency-domain metrics...
[0.580] >> mhrv: [1/2] Calculating nonlinear metrics...
[0.660] >> mhrv: [1/2] Calculating fragmentation metrics...
[0.680] >> mhrv: Analyzing window 2 of 2...
[0.680] >> mhrv: [2/2] Detecting RR intervals from ECG... 1065 intervals detected.
[0.930] >> mhrv: [2/2] Removing ectopic intervals... 4 intervals removed.
[0.950] >> mhrv: [2/2] Calculating time-domain metrics...
[0.960] >> mhrv: [2/2] Calculating frequency-domain metrics...
[1.110] >> mhrv: [2/2] Calculating nonlinear metrics...
[1.180] >> mhrv: [2/2] Calculating fragmentation metrics...
[1.190] >> mhrv: Building statistics table...
[1.200] >> mhrv: Displaying Results...
                RR       NN      AVNN      SDNN      RMSSD      pNN50       SEM      BETA_LOMB    HF_NORM_LOMB    HF_PEAK_LOMB    HF_POWER_LOMB    LF_NORM_LOMB    LF_PEAK_LOMB    LF_POWER_LOMB    LF_TO_HF_LOMB    TOTAL_POWER_LOMB    VLF_NORM_LOMB    VLF_POWER_LOMB      SD1       SD2       alpha1     alpha2      SampEn        PIP        IALS        PSS       PAS  
              ______    ____    ______    ______    _______    _______    _______    _________    ____________    ____________    _____________    ____________    ____________    _____________    _____________    ________________    _____________    ______________    _______    ______    ________    _______    _________    _______    _________    ______    ______

    1           1046    1033    858.95    30.958     33.598      14.05    0.96322     -1.1881        63.899         0.16744          443.95            6.6518        0.056809         46.214            0.1041            694.76            25.832            179.47         23.769     36.77     0.64751    0.69834       1.8402     52.662       0.5281    60.213     11.81
    2           1065    1061    841.79    40.042     31.725     12.075     1.2293     -1.4542        51.529         0.16744          394.82            6.7584        0.044849         51.783           0.13116            766.21            35.367            270.99         22.444     51.96     0.70254    0.93526       1.8466     51.555      0.51698    55.702    14.138
    Mean      1055.5    1047    850.37      35.5     32.662     13.063     1.0963     -1.3212        57.714         0.16744          419.38            6.7051        0.050829         48.999           0.11763            730.48              30.6            225.23         23.106    44.365     0.67502     0.8168       1.8434     52.109      0.52254    57.958    12.974
    SE           9.5      14     8.581    4.5421    0.93663    0.98746    0.13305     0.13306        6.1852               0          24.564          0.053267       0.0059799         2.7844          0.013529            35.724            4.7674            45.757        0.66276    7.5954    0.027515    0.11846    0.0032216    0.55351    0.0055598    2.2554    1.1637
    Median    1055.5    1047    850.37      35.5     32.662     13.063     1.0963     -1.3212        57.714         0.16744          419.38            6.7051        0.050829         48.999           0.11763            730.48              30.6            225.23         23.106    44.365     0.67502     0.8168       1.8434     52.109      0.52254    57.958    12.974

[1.220] >> mhrv: Generating plots...
[3.260] >> mhrv: Finished processing record db/mitdb/111.

The window_minutes parameter allow splitting the signal into windows and calculating all metrics per window. You can pass in an empty array [] to disable spliting.

Example plots (generated by the example above):

• ECG R-peak detection
• RR interval time series filtering
• Time-domain HRV Metrics
• Spectrum of interval time series
• Nonlinear HRV Metrics
• Poincaré plot and ellipse fitting

Citing

This toolbox, initially called rhrv, was created as part of my MSc research thesis. It was then renamed and updated to be used as the basis of the PhysioZoo platform for HRV analysis of human and animal data.

To use it in you own research, please cite:

• Rosenberg, A. A. (2018) ‘Non-invasive in-vivo analysis of intrinsic clock-like pacemaker mechanisms: Decoupling neural input using heart rate variability measurements.’ MSc Thesis. Technion, Israel Institute of Technology.

• Behar J. A., Rosenberg A. A. et al. (2018) ‘PhysioZoo: a novel open access platform for heart rate variability analysis of mammalian electrocardiographic data.’ Frontiers in Physiology.

Similar projects

Several other projects exist with various levels of overlapping functionality and purpose.

• The PhysioNet WFDB tools.
• The WFDB toolbox for matlab.
• The R-HRV toolbox for the R language.
• The Kubios software package.
• The PhysioZoo platform for mammalian ECG and HRV analysis.

Attribution

Some of the code in lib/ was created by others, used here as dependencies. Original author attribution exists in the source files.

Contribution

Feel free to send pull requests or open issues via GitHub.

References

1. Goldberger, A. L. et al. (2000) ‘PhysioBank, PhysioToolkit, and PhysioNet’, Circulation, 101(23), pp. E215-20.
2. Task Force of the European Society of Cardiology and the North American Society of Pacing and Electrophysiology. (1996) ‘Heart rate variability. Standards of measurement, physiological interpretation, and clinical use.’, European Heart Journal, 17(3), pp. 354–81.
3. Peng, C.-K., Hausdorff, J. M. and Goldberger, A. L. (2000) ‘Fractal mechanisms in neuronal control: human heartbeat and gait dynamics in health and disease, Self-organized biological dynamics and nonlinear control.’ Cambridge: Cambridge University Press.
4. Costa, M. D., Goldberger, A. L. and Peng, C.-K. (2005) ‘Multiscale entropy analysis of biological signals’, Physical Review E - Statistical, Nonlinear, and Soft Matter Physics, 71(2), pp. 1–18.
5. Costa, M. D., Davis, R. B. and Goldberger, A. L. (2017) ‘Heart Rate Fragmentation : A New Approach to the Analysis of Cardiac Interbeat Interval Dynamics’, Frontiers in Physiology, 8(May), pp. 1–13.