BRAVEHEART v1.2.2

Changelog for BRAVEHEART v1.2.2

Contact us at [email protected] with any questions or concerns.

ECG Formats:

1. Frequency, units per mV, and data orientation (columns or rows) can be adjusted for the "Generic.csv" ECG file format using the external file generic_csv_params.csv. This allows users to adjust these attributes without needing to edit code in any MATLAB files, and will allow users running BRAVEHEART via compiled executable to edit these variables as needed for their specific ECG data. See user guide section 23 for additional details.

2. Added ability to directly read Physionet .dat/.hea format ECGs. See user guide section 23 for further details.

New Additions:

1. Added quality probability to the Summary Figure.

2. Added some basic heart rate variability measures. See user guide section 24.4 for further details.

3. Added ECG path and filename, individual beat statistics results, quality metrics, and annotation parameters to exported .mat files. See user guide section 25 for further details.

4. The location of R peaks for beats that are initially detected but then removed via PVC detection, outlier detection, manually, or due to incomplete QRST complexes usually during the very start/end of an ECG recording, are now stored in the Beats results class. See user guide section 10.1.1 for further details.

5. Added T wave mechanical dispersion (TMD) and T wave residuum (TWR) to the VCG_Morphology results class (see user guide section 27 for further details).

BRAVEHEART v1.2.1

Changelog for BRAVEHEART v1.2.1

Contact us at [email protected] with any questions or concerns.

New Additions:

1. Rewrote code to calculate normal ranges for various VCG parameters to improve efficiency and readability. See user guide section 22 for further details.

2. BRAVEHEART GUI now extracts information on race from XML/DICOM files for the purposes of calculating normal value ranges. If no information on race is available, BRAVEHEART assumes that the patient is white. The default race can be changed by editing line 3184 of braveheart_gui.m. BRAVEHEART Batch does not extract demographic information as this is only used for displaying normal ranges in the GUI.

3. BRAVEHEART GUI now extracts information on age, sex, and race from DICOM files and HL7 XML files in addition to all other supported XML formats.

4. GUI features for changing demographics have been changed. BRAVEHEART no longer assumes anything about missing values of age, race, sex, and BMI. If any of these values are missing, the appropriate normal ranges are calculated using margins. See user guide section 22 for further details.

5. Added buttons to GUI section 6.6 to open the ECG file and to display select demographic data from XML files. See user guide section 12.7 for further information.

6. If the load directory option is chosen when loading a directory, a counter is now displayed with the specific ECG number and the total number of ECGs that can be loaded using the next and previous ECG buttons. See user guide section 12.2 for further details.

7. Added new variable VM_max_rpk_loc which returns the time (in ms) after QRS onset of the maximum R peak in lead VM. This corresponds to the time of maximal distance of the VCG loop from the origin. See user guide section 24.3 for further details.

8. Added keyboard shortcuts for common actions within the BRAVEHEART GUI. See user guide section 26 for further details.

Bug Fixes:

1. Fixed a bug that resulted in incorrect localization of the T wave maximum voltage value in there was very large ST segment deviation.

ECG Formats:

1. Added ability to read Schiller XML format. See user guide section 23 for further details.

Changes to Mac Executable Installation:

1. Installation of the Mac executable has been improved and significantly simplified. Installation no longer requires the .command script to copy .csv files to ~/home/BRAVHEART. The .csv files now reside in the directory where the executable is stored and they can be edited as needed from this location rather than ~/home/BRAVHEART. Installation instructions in user guide section 4 have been updated.

BRAVEHEART v1.2.0

Changelog for BRAVEHEART v1.2.0

Contact us at [email protected] with any questions or concerns.

New Additions:

1. Added variables for the area under the vector magnitude (VM) lead QRS and T wave individually. The area under the full VM QRST complex remains unchanged in the variable sai_vm. See user guide Chapter 24.1 for additional information.

2. Added variables for the speed-time integrals of the entire QRST complex, as well as of the QRS complex and T wave individually. See user guide Chapter 24.1 for additional information.

3. Rewrote code to calculate max/min speed in QRST complex, QRS complex, and T wave to improve efficiency and readability.

4. Renamed annotation parameter blanking_samples, which is the value for the blanking window after QRS onset used for speed calculations in Annoparams.m to blanking_window_q.

5. Added annotation parameter blanking_window_t, which is the value for the blanking window after T wave onset used for speed calculations, to Annoparams.m. Previously this was always set to 0, resulting in the possibility of incorrect max speed or max speed location in the T wave due if the location of QRS offset was too early by a few samples. The nominal value is blanking_window_t = 20, which ignores the first 20 ms of the T wave when calculating max/min/median speed.

6. Speed blanking windows, blanking_window_q and blanking_window_t, now take values in milliseconds instead of samples to allow more standardized blanking when using ECGs with different sampling frequencies.

7. Edited and reorganized GUI Section 6.5 which displays VCG speed information. Added a text box so both blanking_window_q and blanking_window_t can be edited in the GUI. Speed graph now displays the QRS onset and T wave onset blanking windows. See user guide Chapter 12.7 for further details.

8. Speed figure (GUI section 6.5) X-axis now assigns a time of 0 ms to the QRS onset. This only affects the speed graph X-axis; the times of max/min speed were always relative to QRS onset.

ECG Formats:

1. Modified load_edf.m, which loads European Data Format (.edf) ECG files, to be more robust to variations in labeling of leads within .edf files.

Bug Fixes:

1. Fixed a bug that threw an error when running batch in MATLAB R2024a.

2. Fixed a bug where the Mac executable install script would fail if the name of the directory containing files had a space in it.

User Guide:

1. Updated tables and text to better reflect additions made in previous versions. Fixed typo in the equation for SVG elevation in the Equations section of the user guide (user guide Chapter 25).

Note for compiled Mac version of BRAVEHEART GUI:

Due to changes to Annoparams.csv, make sure to re-install the .csv files into the home/users//braveheart folder even if you were using an older version of the GUI.

BRAVEHEART v1.1.3

Changelog for BRAVEHEART v1.1.3

Contact us at [email protected] with any questions or concerns.

ECG Formats:

1. Modified load_dicom.m, which loads DICOM (.dcm) ECG files, to be more robust to variations in labeling of leads within .dcm files

2. Added the ability to read most SCP-ECG format (.scp) ECGs using load_scpecg.m and format string format = 'scp_ecg'. Utilized open source code from The BioSig Project v3.8.4 (https://biosig.sourceforge.net). This format is quite complex, and there are many variations, including some with encoded data, but should be able to load the ECG signals for most versions of this file format. Other data from the files such as age and gender is not currently extracted. See user guide Chapter 23 for additional information on ECG formats.

3. Added the ability to read European Data Format (EDF) (.edf) ECGs using load_edf.m and format string format = 'edf'. See user guide Chapter 23 for additional information on ECG formats and some specific information on how BRAVEHART reads and processes some .edf files from Physionet.

4. Added the ability to read Physionet format .csv files. See user guide Chapter 23 for additional information on ECG formats.

5. Added the ability to read ASCII text files exported from the Abbott WorkMate Claris EP recording system (.txt) using load_claris.m and format string format = 'claris'. Claris exports each lead as a separate text file, and the load_claris.m function will find all leads exported from the same page regardless of which file/lead is chosen during loading. The Claris loading function also will check to see if there is Session Information file that contains information on sampling frequency and signal gain. Note that because the Workmate Claris EP recording system exports each lead as an individual file, if you run batch (via the GUI or command line), the software will see each lead as a new ECG, and therefore each "ECG" will show up in the results 12 times. We are working on a solution to this - in the interim, the batch process will take longer than it should, and you will have to delete the 11 duplicate rows for each ECG. See user guide Chapter 23 for additional detailed information specifically on the Claris ECG format and for other ECG formats.

Bug Fixes:

1. Fixed bug that caused an error when using the ECG Splitter utlity (See user guide Chapter 12.7 for additional information).

Note for compiled Mac version of BRAVEHEART GUI:

Due to the addition of new file formats, make sure to re-install the .csv files into the home/users/<username>/braveheart folder even if you were using an older version of the GUI.

BRAVEHEART v1.1.2

Changelog for BRAVEHEART v1.1.2

Contact us at [email protected] with any questions or concerns.

Changes to ECG Formats:

1. Edited load_philipsxml.m to allow loading more variations in Philips XML format files. See user guide Chapter 23 for details.

Bug Fixes:

1. Fixed bug that prevented display of the Filtering figure in the GUI (see user guide Chapter 20.12).

2. Mac OS: Fixed bug that prevented display of external reference files (userguide, equations, etc) from their respective buttons when running the compiled GUI.

3. Added some missing file format extensions to get_source_ext.m

Other Changes:

1. Updated Copyright in file headers to include the year 2024.

BRAVEHEART v1.1.1

Changelog for BRAVEHEART v1.1.1

Contact us at [email protected] with any questions or concerns.

New Additions:

1. Added QRS frontal plane axis = $\arctan(\frac{2 \cdot aVF}{\sqrt{3} \cdot I})$ to Lead_Morphology.m results class.

2. Added QRS area, T wave area, and QRST area to Lead_Morphology.m results class.

3. Added new figure clarifying angle definitions.

4. Added figure displaying QRS frontal axis when the Lead Morphology button is clicked.

Bug Fixes:

1. Fixed bug that resulted in errors in T wave location in the Lead_Morphology.m results class when sampling frequency was not 500 Hz.

Other Changes:

1. Updated user guide with a new section on the equations used by BRAVEHEART and to reflect changes in this version.

Known Bugs:

1. Mac deployed/compiled versions of the software are not opening external files when clicking on relevant buttons in the GUI (eg for user guide or equations). Working on a fix. In the meantime, the files can be viewed on GitHub and/or downloaded. The user guide is provided in the .zip file. This does not affect the Windows version of the deployed/compiled software or when running directly from MATLAB.

BRAVEHEART v1.1.0

Changelog for BRAVEHEART v1.1.0

Contact us at [email protected] with any questions or concerns.

New Additions:

1. Refactored quality assessment code to fix the parallel ECG batch processing bug noted below. Created a new Qualparams class (Qualparams.m) to contain the quality presets to avoid needing to reload the data from the external .csv file multiple times. To edit the quality presets while using MATLAB, instead of editing the external file quality_presents.csv, the presets are now editable via the file Qualparams.m. The external file named quality_presents.csv has been renamed Qualparams.csv to be consistent. When running BRAVEHEART via compiled executable, quality parameters are set via editing the external file Qualparams.csv, similar to how editing Annoparams.csv is handled. See user guide Chapter 16.3 for details of the new Qualparams class.

2. Added test cases to test_braveheart.m to check the function and integrity of quality checking if any changes are made to BRAVEHEART code (see user guide Chapter 26 for details).

3. Added console logging (to file logfile.txt) when using executable versions to assist with troubleshooting any errors (see user guide Chapter 27.6 for details).

Bug Fixes:

1. Fixed bug that resulted in parallel ECG batch processing not working only when using a compiled executable version of BRAVEHEART (both GUI and command line). Parallel batch ECG processing now works in the compiled GUI and command line versions of BRAVEHEART.

Other Changes:

1. Updated user guide with a new section on Qualparams (see user guide Chapter 16) as noted above.

BRAVEHEART v1.0.2

Changelog for BRAVEHEART v1.0.2

Contact us at [email protected] with any questions or concerns.

Bug Fixes:

1. Fixed a bug related to median beat annotations being incorrect by a small number of samples if the ECG sampling frequency was not 500 Hz or 1000 Hz. ECGs sampled at 500 Hz or 1000 Hz were not affected by this bug, and in general, the effect should be very small for ECGs sampled at > 500 Hz. If you previously processed ECGs with sampling frequencies other than 500 Hz or 1000 Hz, this version may result is very slight differences in output, with larger differences seen with ECGs sampled at < 500 Hz. If you previously processed ECGs with sampling frequencies other than 500 Hz or 1000 Hz we recomend that you reprocess your data with this new version to have the most accurate results.

2. Fixed a bug that resulted in errors which prevented calculating results in the `LeadMorphology.m' results class for ECGs sampled at < 500 Hz.

Existing Bugs:

1. Became aware of a bug that results in parallel ECG batch processing not working only when using a compiled executable version of BRAVEHEART (both GUI and command line). Parallel processing works fine in versions that run via MATLAB source code. While a fix is being worked on, parallel processing via the compiled versions of BRAVEHEART has been disabled - regardless of if parallel processing is chosen, the batch will process in series. This only impacts the speed of batch processing. A fix will be released ASAP.

ECG Formats:

1. Edited load_cardiosoftxml.m to address issues related to how different versions of the Cardiosoft XML format changed how XML label attibutes were formatted. This new version should be robust to formatting changes.

2. Edited load_hl7xml.m to address issue related to end of line characters causing errors when reading HL7 format XML when the XML file was generated on different operating systems.

3. Edited load_dicom.m to allow DICOM data with 8-bit unsigned integer data in addition to existing 16-bit unsigned integer data. Made this function more robust to formatting variations. (Note: Use of this function requires the MATLAB Image Processing Toolbox).

GUI Generated Figures:

1. Fixed issue with the "Offsets" figure (see user guide Section 15.2 and Figure 25) not displaying if a lead was missing from the ECG file.

2. Fixed issue with the "Lead Morphology" figure (see user guide Section 20.7 and Figure 43) not displaying if a lead was missing from the ECG file.

Other Changes:

1. Updated user guide with minor changes and fixes for typographic errors.

BRAVEHEART v1.0.1

Changelog for BRAVEHEART v1.0.1

Contact us at [email protected] with any questions or concerns.

This update adds a few minor updates and does not change any core functionality of BRAVEHEART. Assuming that the settings in Annoparams.m or the GUI are unchanged, output from ECG processing will be unchanged (except for the software version number) and will yield the same results.

Changes to Denoising/Filtering Settings:

1. The default wavelet decomposition level for high-frequency denoising/low-pass filtering has been changed from 2 to 1 in Annoparams.m and Annoparams.csv. This corresponds to a cutoff frequency of 125 Hz for ECGs sampled at 500 Hz and a cutoff freqyency of 250 Hz for ECGs sampled at 1000 Hz. This value can be changed by editing Annoparams.m or Annoparams.csv (see User Guide Chapter 6)

2. When using the GUI and changing ECG formats, the nominal high-frequency denoising/low-pass filtering cutoff frequency has been increased from 62.5 Hz to 125 Hz for ECGs sampled at 500 and 1000 Hz based on the sampling frequency that is associated with the ECG format in ecg_formats.csv and ecg_source_gui.m. ECGs sampled at 500 Hz will therefore use wavelet decomposition level 1, and ECGs sampled at 1000 Hz will use wavelet decomposition level 2. ECGs with sampling frequencies other than 500 or 1000 Hz are set to level 1 regardless of their sampling frequency.

3. Increased the maximum level of low-frequency (high-pass) wavelet decomposition from 11 to 14 when using the GUI. This allows use of ECGs with sampling frequencies up to 2000 Hz and a high-pass frequency of 0.06 Hz (level 14 with a sampling frequency of 2000 Hz). This only has an effect when using the GUI as when running the software via braveheart_batch.m the high-pass wavelet decomposition level is set manually via Annoparams.m or Annoparams.csv.

4. Added error handling if the user chooses a wavelet decomposition level for baseline wander removal that is above the maximum level of $n_{\mathrm{max}} = \mathrm{floor}(\mathrm{log_{2}} L)$ where $L$ is the length of the signal.

5. Added more mother wavelets to the GUI. The wavelet name dropdowns for both high- and low- frequency denoising now include Symelet ('sym') 4-10 and Daubechies ('db') 4-10 wavelets. Any mother wavelet from MATLAB can be added if using the command line version of BRAVEHEART and setting the wavelet name in Annoparams.m or Annoparams.csv. A full list of MATLAB wavelets and their associated strings can be found in the MATLAB documentation or by typing waveinfo in the MATLAB Command Window. Note that high-frequency denoising/low-pass filtering requires use of orthogonal wavelets.

6. When selecting an ECG format via the GUI, the high-pass cutoff frequency is set automatically based on the sampling frequency to the wavelet level which gives the first decomposition level that is < 0.25 Hz. The level can still be edited manually in the GUI dropdowns after the ECG is loaded. The command line version still requires the wavelet level for low frequency denoising/high pass filtering to be set manually in Annoparams.m.

New ECG Formats:

1. Added the ability to read Cardiosoft XML files.

Other Changes:

1. Updated user guide with minor changes/fixes/clarifications, additions to the Troubleshooting section, and new sections about adding custom ECG filtering schemes and information on how to adjust denoising/filtering parameters.

2. Very small update to normal ranges based on minor edits from our newly published manuscript now available at:
   Stabenau et al. 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, In Press. DOI: https://doi.org/10.1111/jce.16062

BRAVEHEART v1.0.0

Initial public release