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-2026 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 or later, please upgrade to BRAVEHEART version 1.6.0 or later.

Supported ECG Formats:

BRAVEHEART can read a wide variety of 12-lead ECG formats including:

1. Unformatted .txt and .csv
2. GE MUSE XML
3. Philips XML
4. HL7 annotated ECG (aECG) XML
5. DICOM
6. ISHNE
7. Physionet/WFDB .dat
8. SCP-ECG
9. EDF
10. GE Marquette ASCII
11. Cardiosoft XML
12. Schiller XML
13. Physionet .csv
14. GE Prucka recording system
15. Abbott Workmate Claris recording system .txt
16. Norav 1200M .rdt
17. Megacare XML
18. Edan .dat
19. MFER .mwf
20. Zoncare ZQECG XML
21. Mortara ELI XML
22. EP Tracer recording system
23. Labsystem Pro recording system

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.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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.

7. 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

8. 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.

9. 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

10. 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

11. 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.

12. 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.

13. 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.

14. 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. J Am Heart Assoc. 2025, Jun 18:e040814.

15. 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.

16. 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.

17. 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.

18. 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 Oct 14:S1547-5271

19. HF Stabenau, JD Matos, DB Kramer, A Sau, L Pastika, E Sieliwonczyk, K Patlatzoglou, NS Peters, P Tung, FS Ng, R Nezafat, and JW Waks. The Spatial Ventricular Gradient is a Non-Invasive, Vectorcardiographic Correlate of Cardiac Fibrosis. J Interv Card Electrophysiol, 2025 Oct 9.

20. E Sieliwonczyk, A Sau, K Patlatzoglou, KA McGurk, L Pastika, PK Thami, M Mangino, SL Zheng, G Powell, L Curran, RJ Buchan, P Theotokis, NS Peters, B Loeys, DB Kramer, JW Waks, FS Ng, and JS Ware. Unsupervised Feature Extraction Using Deep Learning Empowers Discovery of Genetic Determinants of the Electrocardiogram. Genome Med}, 2025 Oct 9;17(1):118.

21. K Patlatzoglou, L Pastika, J Barker, E Sieliwonczyk, GR Khattak, B Zeidaabadi, AH Ribeiro, JS Ware, NS Peters, ALP Ribeiro, DB Kramer, JW Waks, A Sau, and FS Ng. The Cost of Explainability in Artificial Intelligence-Enhanced Electrocardiogram Models. NPJ Digit. Med. 2025 8, 747.

22. M Gurnani, K Patlatzoglo, J Barker, L Pastika, B Zeidaabadi, I Antoun, GA Ng, P Inglese, L Curran, D O’Regan, NS Peters, DB Kramer, JW Waks, A Sau, and FS Ng. Deriving Novel Atrial Fibrillation Phenotypes Using a Tree-Based Artificial Intelligence-Enhanced Electrocardiography Approach. NPJ Digit. Med. 2025 Dec 4.

23. JW Waks, M Poulin, P Tung, HF Stabenau, A Haouzi, JD Clarke, P Zimetbaum, A d’Avila, B Ultimo, KA Guibone, K Kiernan, A Medline, NS Peters, A Sau, FS Ng, DB Kramer, A Shvilkin, RJ Laham, and AE Buxton. Heart Rhythm O2. 2026 In Press.

If you have used BRAVEHEART for your research project, let us know, as 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.