ECGAug
Version 1.0

A Novel Method of Generating Augmented Annotated Electrocardiogram QRST Complexes and Rhythm Strips

License

Copyright 2020 Jonathan W. Waks and Hans F. Stabenau Beth Israel Deaconess Medical Center, Boston MA

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

Manuscript:

A detailed description of the ECGAug method is available at https://www.sciencedirect.com/science/article/abs/pii/S001048252100202X HF Stabenau, CP Bridge, and JW Waks, ECGAug: A Novel Method of Generating Augmented Annotated Electrocardiogram QRST Complexes and Rhythm Strips, Computers in Biology and Medicine, 2021, In Press

Files:

ECGAug software package contains the following files:

1. Augparams.m - Matlab class for various augmentation input parameters
2. ecgaug_script.m - Matlab script for running the main ECGAug program (QRST recombination and transformation)
3. recombine_qrst.m - Matlab function to recombine 2 QRST templates into a new QRST template
4. rhythmstrip.m - Matlab function for creating rhythm scripts
5. rhythmstrip_script.m - Matlab script for creating rhythm strips
6. transform_qrst.m - Matlab function to transform/distort a QRST template
7. Outparams.m - Matlab class for output of various parameters generated by ECGAug functions
8. view_signals.m - Matlab script to the included example(P)QRST templates
9. \templates - Folder that includes 40 (P)QRST templates/fiducial points (.mat) for use with ECGAug

See comments/headers/documetation within each file for additional information

Up to date files can be found at http://github.com/BIVectors/ECGAug

Running ECGAug for the first time:

For QRST template recombination/transformation:

1. Open Augparams.m
2. Edit input_folder to point to the folder with included templates (line 49)
3. Edit output_folder to point to whatever directory you would like to used for saved figures/signals (line 53)
4. Edit tot_aug num (number of recombined QRST complexes) in ecgaug_script.m (line 37)
5. Edit num_aug_beats (number of transformations per recombined QRST complex) in ecgaug_script.m (line 40)
6. Edit other parameters in Augparams.m if wanted (default should work fine for testing)
7. Run ecgaug_script.m

For rhythm strip generation:

1. Open Augparams.m
2. Edit input_folder to point to the folder with included templates (line 49)
3. Edit output_folder to point to whatever directory you would like to used for saved figures/signals (line 53)
4. Edit other parameters in Augparams.m if wanted (default should work fine for testing)
5. Open rhythmstrip_script.m
6. Set number of rhythm strips to generate (num_strips) (line 34)
7. Run rhythmstrip_script.m.

To view the included signals:

1. Open view_signals.m
2. Edit input_folder (line 28) to point to the folder with included signal templates
3. Run view_signals.m

Customize for your own signal format:

To accommodate your own specific file format and format for storing signals and fiducial points, will likely have to edit specific sections of rhythmstrip_script.m and ecgaug_script.m. See the headers for these files for additional information on which sections of code that should be modified which in general are demarcated by %-------------------%

Default settings in Augparams.m are set to be aggressive for demonstration purposes. In some cases large transformations may be wanted, but in other cases you may want to make the transformation parameters less aggressive. The following parameters in Augparams.m are likely to be more physiological (and generate more subtle changes)

% LESS AGRESSIVE TRANSFORMATION PARAMETERS

% Shift: Linear translation in Y-axis
% Range = shift_min to shift_max
    shift_min = -0.1;
    shift_max = 0.1;

% Stretch: Deformation in X-axis
% Range = 1 + stretch_min to 1 + stretch_max
    stretch_min = -0.2;
    stretch_max = 0.2

% Scale: Deformation in Y-axis
% Range =  = 1 + scale_min to 1 + scale_max
    scale_min = -0.2;
    scale_max = 0.2;

File naming conventions:

1. Recombined QRST signals/figures are labeled as 'QRS1 filename'__'TW2 filename'_recombined
2. Transformed QRST signals/figures are labeled as 'filename_syn_i' where 'filename' is the file input into transform_qrst .m (could be a recombined signal filename) and 'i' is the number of the transformation for that file (if generating multiple transformations per input file)..
3. Rhythm strip signals and figures are named as rhythm_syn_'datetime'_ where 'datetime' is the date/time that the signal was passed into rhythmstip() (so that signals and figures will have same name)
4. The individual beat morphologies and variations that are used to create the rhythm strip are saved in a figure named rhythm_syn_'datetime'_beats

Matlab Setup:

To ensure that the generated augmented ECG files are saved with the appropriate Augparams (limits and actual values used for augmented signal generation) you will need to ensure that Augparams.m and Outparams.m are added to the Matlab path. Failure to do so will not generate an error, but will not attach the Augparams to the generated files.

Datastructures:

Recombined QRST Signals:

Recombined QRST signals (.mat files) are stored in a data structure named recombo with the following contents:

sig_new -- recombined signal stored as a 1 x n double

Q -- location (in samples) of QRS onset

S -- location (in samples) of QRS offset

Tend -- location (in samples) of T wave offset

ap -- Augparam ranges used to generate the recombined signal (see Augparams.m for details)

op -- Specific parameters used to generate the recombined signal

fname1 -- Filename for signal 1 (default for QRS signal)

fname2 -- Filename for signal 2 (default for the TW signal)

Transformed QRST Signals:

Transformed QRST signals (.mat files) are stored in a data structure with the following contents:

file1 -- filename for signal (combination of fname1 and fname2)

sig -- recombined signal stored as a 1 x n double

Q -- location (in samples) of QRS onset

S -- location (in samples) of QRS offset

Tend -- location (in samples) of T wave offset

ap -- Augparam ranges used to generate the recombined signal (see Augparams.m for details)

op -- specific parameters used to generate the recombined signal

Rhythm Strips:

Rhythms strip signals (.mat files) are stored in a data structure named rhythm with the following contents:

rhythm -- rhythm strip signal stored as a 1 x n double

n_morph -- number of different QRST morphologies used in the rhythm strip

n_variants -- number of variants for each QRST morphology -- eg [4 2] means morpholgy #1 has 4 variants, morpholgy #2 has 2 variants etc.

Qloc -- locations of QRS onset for beats 1 through n

Sloc-- locations of QRS offset for beats 1 through n

Tendloc-- locations of T wave offset for beats 1 through n

morph -- which morphology was used for each beat in the rhythm strip -- eg [1 3] means morphology #1 was used for beat 1 and morphology #3 was used for beat 2 etc.

beat -- which variant was used for each beat in the rhythm strip -- eg [2 1] means variant 2 of the first morphology was used for beat 1, variant 1 of the second morphology was used for beat 2 etc.

ap -- Augparam ranges used to generate the recombined signal (see Augparams.m for details)

files-- list of filenames used for various QRST morphologies

date_time -- date and time of signal generation (used for naming files)