Software Open Access
TWAnalyser - A T-wave Alternans Detector
Published: Nov. 18, 2008. Version: 1.0.0
Khaustov A, Nemati S, Clifford GD An open-source standard T-wave alternans detector for benchmarking signals. Computers in Cardiology 2008.
Please include the standard citation for PhysioNet:
(show more options)
Goldberger, A., Amaral, L., Glass, L., Hausdorff, J., Ivanov, P. C., Mark, R., ... & Stanley, H. E. (2000). PhysioBank, PhysioToolkit, and PhysioNet: Components of a new research resource for complex physiologic signals. Circulation [Online]. 101 (23), pp. e215–e220.
This software suite consists of Matlab implementations of the widely used Spectral Method (SM) and Modified Moving Average (MMA) for T-wave alternans (TWA) detection. It was initially developed for the PhysioNet/CinC Challenge 2008, in which these and a wide variety of other methods were evaluated and compared in blinded tests, using a data set that included ECGs with and without TWA as well as synthetic ECGs with calibrated amounts of artificial TWA. The implementation of SM presented here scored second in the open-source category and third overall with a score of 0.881. TWAanalyser's implementation of MMA received a score of 0.400. (A third method, which combined both algorithms, scored 0.834, not quite as well as SM alone. In this case, ECGs in which SM did not detect TWA were assigned a TWA estimate of 0, and all others were assigned the MMA algorithm's TWA estimate.) Most of the work to improve the score resulted from adjustments to filtering and alignment.
TWAnalyser has been tested on both Windows XP (SP2) and Linux (Fedora Core 4-9) using Matlab R13 (6.5) and R2006b (7.3).
TWAnalyser accepts digitized ECGs in PhysioBank-compatible formats. If you have ECGs in some other format and have Matlab software for reading them, it's not too difficult to modify TWAnalyser to work with your format. Otherwise, create PhysioBank-compatible records from your ECGs. If you wish to analyze a lengthy recording, you may wish to divide it into short segments (a few minutes each) first; this will save a lot of time.
TWAnalyser requires a set of Q-onset, S-end, and T-end annotations for the ECGs to be analysed. If these are not available, TWAnalyser uses ecgpuwave to produce them. You also have the option of providing your own annotation files. In that case the names of the annotation files should end with .vf or .pu and their contents should mimic the format used by ecgpuwave. Specifically, annotation files should be stored in PhysioBank-compatible format, and they should include:
- Q-onset annotations (anntyp = WFON, num = 1, chan = 0)
- S-end annotations (anntyp = WFOFF, num = 1, chan = 0)
- T-end annotations (anntyp = WFOFF, num = 2, chan = 0)
Read about annotations here.
TWAnalyser requires Matlab and WFDB. If the required annotations (see above) are not already available for the ECGs to be analyzed, ecgpuwave is also required. TWAnalyser and all of its prerequisite software are freely available under the terms of the GPL, with the exception of Matlab. It may be possible to run TWAnalyser using GNU Octave or another freely available replacement for Matlab, but this has not been tested.
- Install Matlab, WFDB, WFDB_tools, and ecgpuwave if you have not already done so.
- Download and unpack twa-mfiles.tar.gz (or twa-mfiles.zip; or download individual source files for TWAnalyser).
- Add the twa-mfiles directory to the Matlab path.
Under Windows, you may follow the same procedure as for Linux. Alternatively:
- Install Matlab if you have not already done so.
- Download and unpack twa-windows.zip.
- Enter the twa-windows directory and run setup.bat from the Windows command prompt.
Note that twa-windows.zip includes Windows executables that were built using version 10.4.4 of the WFDB library (from May 2006), which lacks features of recent versions such as support for reading EDF files.
There are three commands that will start the analysis for you. From the Matlab command prompt type one of the following:
DoTWASpectral [performs the SM and provides a graphical interface to explore the results]
You are prompted to locate the ECG file you want to analyze. The SM interface consists of an ECG window, windows displaying successive superimposed beats, alternans series, periodogram and averaged periodogram. Navigation is possible in the ECG, superimposed beat and alternans series windows. One ECG lead at a time is displayed. You can switch leads using the button at the upper right corner of the interface window. A summary of the analysis results is at the top. All three available options (see the paper) for SM are displayed simultaneously (i.e., respective alternans series, periodograms and averaged periodograms are superimposed). You can remove the options you don't need by altering Param.MethodForEctopy in DoTWASpectral.m.
DoTWAbyMMA [performs the MMA and provides a graphical interface to explore the results]
You are prompted to locate the ECG file you want to analyze. The MMA interface consists of ECG window, windows displaying superimposed even and odd averages for the current interval, alternans value trend and two windows containing (even and odd) averages for previous and current interval plotted against the current beat. Navigation is possible in the ECG and trend windows. One lead at a time is displayed. You can switch leads using the button at the upper right corner of the interface window. A text string summarizing the analysis results is displayed at the top of the window.
BatchTWA [performs a batch analysis for a set of records and outputs results into a text file]
For batch processing, set the current Matlab directory to the directory with all the data files. You are prompted to locate a file that contains a list of records to analyse (one record per string, no extensions). All available analysis options are performed. If you don't need something - alter the Metric and Method lists in BatchTWA.m . The results are stored in the current directory, in files twa_SM_replace.txt, twa_SM_differences.txt, twa_SM_lomb.txt, and twa_MMA.txt.
We have a long to-do list planned for this software, including: pre-filtering with PCA (as was used by the winning closed-source entry in the competition, although this entry did not provide TWA magnitudes, only rankings); reporting of heart rate (TWA that manifests above 110 BPM is unlikely to be clinically significant); tests to determine the effects of the unevenly sampled nature of TWA; dealing with TWA phase changes (after ectopy for example) and indicators to quantify this effect.
- Khaustov A, Nemati S, Clifford GD An open-source standard T-wave alternans detector for benchmarking signals. Computers in Cardiology 2008. The conference presentation of this work is also available here ([HTML] or [PPT]).
- Martinez JP, Olmos S Methodological principles of T wave alternans analysis: a unified framework. IEEE Transactions on Biomedical Engineering 52(4): 599-613; April 2005. (External link; requires subscription. The descriptions of the SM and MMA methods in this paper were the basis for the implementations of these methods presented here.)
This project was a joint effort by Alexander Khaustov of the St.-Petersburg Institute of Cardiological Technics (INCART), and by Shamim Nemati and Gari Clifford of MIT. The software was contributed to PhysioNet by INCART. Please refer your questions to email@example.com.
Total uncompressed size: 0 B.
Access the files
Download the files using your terminal:
wget -r -N -c -np https://physionet.org/files/twanalyser/1.0.0/
Download the files using AWS command line tools:
aws s3 sync s3://physionet-open/twanalyser/1.0.0/ DESTINATION