BRAVEHEART: Open-Source Software for Automated Electrocardiographic and Vectorcardiographic Analysis

Hans Fredrich Stabenau, MD, PhD & Jonathan W. Waks, MD
Harvard-Thorndike Electrophysiology Institute, Department of Cardiovascular Medicine,
Beth Israel Deaconess Medical Center, Harvard Medical School, Boston, MA, USA
braveheart.ecg@gmail.com

What is BRAVEHEART?

BRAVEHEART (Beth Israel Analysis of Vectors of the Heart) is a modular, customizable, open-source software package for processing electrocardiograms (ECGs) and vectorcardiograms (VCGs) for research purposes.
BRAVEHEART was built using MATLAB and requires a version after R2022a (http://www.mathworks.com) as well as the following toolboxes to run via source code: * Wavelet toolbox * Signal processing toolbox * Deep learning toolbox * Parallel computing toolbox (optional)

For users without access to MATLAB or all required toolboxes, we have also provided executables for Windows and Mac operating systems that can be run without needing MATLAB installed.

The most up to date version of the software can be found on GitHub at http://www.github.com/BIVectors/BRAVEHEART, where the software, source code, and executables for Windows and Mac are available under version 3 of the General Public License (GPL) (http://www.gnu.org/licenses/gpl-3.0.en.html).

License

Copyright 2016-2025 Jonathan W. Waks and Hans F. Stabenau
All rights reserved.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/ or the LICENSE file included in this repository.

Installation & User Guide/Software Methods

A detailed user guide that covers installation and use of the software, including a quick start guide and examples of ECG/VCG processing, is available in the file braveheart_userguide.pdf.

A manuscript describing the software methods in detail is available in the file braveheart_methods.pdf and as a manuscript in Computer Methods and Programs in Biomedicine (DOI: https://doi.org/10.1016/j.cmpb.2023.107798).

Frequently Encountered Issue - GUI Not Displaying Correctly

If the GUI is not displaying completely first check that your monitor resolution is at least 1920 x 1080. If your monitor resolution is adequate but the GUI is still not fully displaying, your computer display settings likely have some form of scaling turned on; this setting increases the size of text to improve readability, but also effectively reduces the screen resolution. Instructions for how to disable this setting can be found below or in the user guide section 29.1:

To disable screen scaling:
+ Windows 10: Open the Ease of Access settings with Windows key + U. Under Make everything bigger on the Display tab, change to 100%.
+ Windows 11: Open Settings and then Display. Under Scale & layout, expand the Scale menu and change to 100%.
+ Mac OS: Open System Preferences and then Display. Choose Scaled Resolution and then More Space

Frequently Encountered Issue - GUI Looks Abnormal in R2025a

If you are using MATLAB R2025a, please upgrade to version 1.6.0 or later.

Supported ECG Formats:

BRAVEHEART can read a wide variety of 12-lead ECG formats including: 1. GE MUSE XML 2. Philips XML 3. HL7 XML 4. DICOM 5. ISHNE 6. GE Marquette ASCII 7. Cardiosoft XML 8. Schiller XML 9. SCP-ECG 10. EDF 11. Physionet .dat 12. Physionet .csv 13. GE Prucka 14. Abbott Workmate Claris ASCII 15. Unformatted .txt and .csv 16. Norav 1200M .rdt 17. Megacare XML 18. Edan .dat 19. MFER .mwf

If you need BRAVEHEART to read another ECG format let us know and we will help add it.

How to Cite Use of BRAVEHEART

Please include the link to this GitHub repository and cite our manuscript in Computer Methods and Programs in Biomedicine. The upper right section of this repository has a CITATION file that will provide the appropriate references which are also reproduced here:

Citation:
Hans F. Stabenau and Jonathan W. Waks. BRAVEHEART: Open-source software for automated electrocardiographic and vectorcardiographic analysis. Computer Methods and Programs in Biomedicine. Volume 242, Dec 2023, 107798. DOI: https://doi.org/10.1016/j.cmpb.2023.107798
Stabenau, HF and Waks, JW. BRAVEHEART: Open-source software for automated electrocardiographic and vectorcardiographic analysis. Comput Methods Programs Biomed. Volume 242, Dec 2023, 107798. DOI: https://doi.org/10.1016/j.cmpb.2023.107798

Bibtex: ``` @Article{BRAVEHEART, Author="Stabenau, H. F. and Waks, J. W. ", Title="{{B}{R}{A}{V}{E}{H}{E}{A}{R}{T}: {O}pen-source software for automated electrocardiographic and vectorcardiographic analysis}", Journal="Comput Methods Programs Biomed", Year="2023", Volume="242", Pages="107798", Month="Dec", doi = {https://doi.org/10.1016/j.cmpb.2023.107798} }

```

Publications

The software has been used for ECG/VCG analysis in the following publications:
1. HF Stabenau, C Shen, LG Tereshchenko, and JW. Waks. Changes in global electrical heterogeneity associated with dofetilide, quinidine, ranolazine, and verapamil. Heart Rhythm, 2020 Mar;17(3):460-467.

1. HF Stabenau, C Shen, P Zimetbaum, AE Buxton, LG Tereshchenko, and JW Waks. Global electrical heterogeneity associated with drug-induced torsades de pointes. Heart Rhythm, 2021 Jan;18(1):57-62.

2. HF Stabenau, CP Bridge, and JW Waks. ECGAug: A novel method of generating augmented annotated electrocardiogram QRST complexes and rhythm strips. Comput Biol Med, 2021 Jul;134:104408.

3. HF Stabenau, M Marcus, JD Matos, I McCormick, D Litmanovich, WJ Manning, BJ Carroll, and JW Waks. The spatial ventricular gradient is associated with adverse outcomes in acute pulmonary embolism. Ann Noninvasive Electrocardiol, 2023, Jan 24;e13041.

4. AN Rosas Diaz, HF Stabenau, GP Hurtado, S Warack, JW Waks, and A Asnani. The spatial ventricular gradient is an independent predictor of anthracycline-associated cardiotoxicity. JACC: Adv, 2(2):100269, 2023.

5. HF Stabenau, A Sau, DB Kramer, NS Peters, FS Ng, and JW Waks. Limits of the Spatial Ventricular Gradient and QRST Angles in Patients with Normal Electrocardiograms and No Known Cardiovascular Disease Stratified by Age, Sex, and Race. J Cardiovasc Electrophysiol, 2023 Nov;34(11):2305-2315.

6. N Isaza, HF Stabenau, DB Kramer, A Sau, P Tung, TR Maher, AH Locke, P Zimetbaum, A d’Avila, NS Peters, LG Tereshchenko, FS Ng, AE Buxton, and JW Waks. The Spatial Ventricular Gradient is Associated with Inducibility of Ventricular Arrhythmias During Electrophysiology Study. Heart Rhythm, 2024 Nov;21(11):2160-2167

7. L Pastika, A Sau, K Patlatzoglou, E Sieliwonczyk, AH Ribeiro, KA McGurk, S Khan, D Mandic, WR Scott, JS Ware, NS Peters, ALP Ribeiro, DB Kramer, JW Waks, and FS Ng. Deep Neural Network-derived Electrocardiographic Body Mass Index as a Predictor of Cardiometabolic Disease. NPJ Digit. Med. 2024 Jun 25;7(1):167.

8. A Sau, L Pastika, E Sieliwonczyk, K Patlatzoglou, AH Ribeiro, KA McGurk, B Zeidaabadi, H Zhang, K Macierzanka, D Mandic, E Sabino, L Giatti, SM Barreto, L do Valle Camelo, I Tzoulaki, DP O’Regan, NS Peters, JS Ware, ALP Ribeiro, DB Kramer, JW Waks, and FS Ng. Artificial intelligence-enabled electrocardiogram for mortality and cardiovascular risk estimation: a model development and validation study Lancet Digit Health. 2024 Nov;6(11):e791-e802

9. M Raad, DB Kramer, HF Stabenau, E Anyanwu, DS Frankel, and JW Waks. The Spatial Ventricular Gradient Is Associated with Pacing-Induced Cardiomyopathy. Heart Rhythm. 2024. In Press

10. A Sau, J Barker, L Pastika, E Sieliwonczyk, K Patlatzoglou, KA McGurk, NS Peters, DP O'Regan, JS Ware, DB Kramer, JW Waks, and FS Ng. Artificial Intelligence-Enhanced Electrocardiography for Prediction of Incident Hypertension. JAMA Cardiol. 2025, Jan 2.

11. K Macierzanka, A Sau, K Patlatzoglou, L Pastika, E Sieliwonczyk, M Gurnani, NS Peters, JW Waks, DB Kramer, and FS Ng. Siamese neural network-enhanced electrocardiography can re-identify anonymised healthcare data. Eur Heart J Digit Health. 2025, Feb 25.

12. A Sau, E Sieliwonczyk, K Patlatzoglou, L Pastika, K McGurk, AH Ribeiro, ALP Ribeiro, JE Ho, NS Peters, JS Ware, U Tayal, DB Kramer, JW Waks, and FS Ng. Artificial intelligence- enhanced electrocardiography for the identification of a sex-related cardiovascular risk continuum: a retrospective cohort study. Lancet Digit Health. 2025 Mar;7(3):e184-e194.

13. M Gurnani, K Patlatzoglou, J Barker, D Bivona, L Pastika, E Sieliwonczyk, B Zeidaabadi, P Inglese, L Curran, AD Arnold, D O'Regan, Z Whinnett, KC Bilchick, NS Peters, DB Kramer, JW Waks, A Sau, and FS Ng. Revisiting Abnormalities of Ventricular Depolarization: Redefining Phenotypes and Associated Outcomes Using Tree-Based Dimensionality Reduction. Siamese neural network-enhanced electrocardiography can re-identify anonymised healthcare data. J Am Heart Assoc. 2025, Jun 18:e040814.

14. Y Liang, A Sau, B Zeidaabadi, J Barker, K Patlatzoglou, L Pastika, E Sieliwonczyk, Z Whinnett, NS Peters, Z Yu, X Liu, S Wang, H Lu, DB Kramer, JW Waks, Y Su, J Ge, and FS Ng. Artificial intelligence-enhanced electrocardiography to predict regurgitant valvular heart diseases: an international study. Eur Heart J. 2025 Jul 16:ehaf448.

15. AJ Shepherd, HF Stabenau, A Sau, P Tung, TR Maher, S Yang, AH Locke, P Zimetbaum, GF Michaud, A d'Avila, NS Peters, AE Buxton, FS Ng, DB Kramer, and JW Waks. Larger Spatial Ventricular Gradient Magnitude is Associated with Higher Rates of Response to Cardiac Resynchronization Therapy. Heart Rhythm O2, 2025 In Press.

16. A Sau, H Zhang, J Barker, L Pastika, K Patlatzoglou, B Zeidaabadi, A El-Medany, GR Khattak, KA McGurk, E Sieliwonczyk, JS Ware, NS Peters, DB Kramer, JW Waks, and, FS Ng. Artificial Intelligence-Enhanced Electrocardiography for Complete Heart Block Risk Stratification. JAMA Cardiol., 2025 Aug 20:e252522.

17. A Sau, E Sieliwonczyk, J Barker, B Zeidaabadi, L Pastika, K Patlatzoglou, GR Khattak, KA McGurk, NS Peters, DB Kramer, JW Waks, JS Ware, and FS Ng. Prediction of incident atrial fibrillation: a comprehensive evaluation of conventional and AI-enhanced approaches. Heart Rhythm, 2025 In Press.

If you have used BRAVEHEART for your research project we would be happy to include a reference to your manuscript!

Contributing

Please contact the authors by email at braveheart.ecg@gmail.com if you are interested in contributing to the project.