Software Open Access
Heartprints - A Dynamical Portrait of Cardiac Arrhythmia
Published: March 8, 2003. Version: 1.0.0
Goldberger AL, Amaral LAN, Glass L, Hausdorff JM, Ivanov PCh, Mark RG, Mietus JE, Moody GB, Peng C-K, Stanley HE. PhysioBank, PhysioToolkit, and PhysioNet: Components of a New Research Resource for Complex Physiologic Signals (2003). Circulation. 101(23):e215-e220.
As part of an effort to visualize and to understand the dynamics of cardiac arrhythmias with frequent ventricular ectopy, we have developed a new representational technique termed "heartprints." These heartprints are a combination of seven histograms generated from an annotated record of heartbeat time intervals. An example is shown in heartprint.png.
Each of the seven panels of the heartprint contains data that typically span 20 to 24 hours, the length of an entire long-term (Holter) ECG recording. The three upper panels, left to right, are:
- the histogram of V-V intervals (the time intervals between successive, but not necessarily consecutive, premature ventricular (V)-beats)
- the histogram of NIB (the number of normal (N) beats intervening between successive V-beats)
- the histogram of N-V (coupling) intervals (the time interval between a V-beat and the preceding normal beat)
The four lower panels share a common vertical axis (representing the underlying N-N interval length), and all but the first of these share common horizontal axes with the corresponding panels in the upper row. From left to right, the four lower panels are:
- the histogram of N-N intervals (the time intervals between consecutive normal beats, reflecting the underlying sinus rhythm)
- the scattergram of V-V intervals stratified by the underlying N-N intervals
- the scattergram of NIB stratified by the underlying N-N intervals
- the scattergram of N-V intervals stratified by the underlying N-N intervals
When a V-beat occurs, the N-N (sinus) interval cannot be observed directly, since the V-beat usually inhibits the occurrence of what would otherwise have been a normal beat. In such cases, the neighboring beats are used to estimate the missing observations, permitting reconstruction of the underlying sinus interval time series. (See the comments at the beginning of hp_scatter.c. Note that the quality of this reconstruction determines the reliability of the resulting figures. Alternative reconstruction algorithms, such as that implemented by nguess, may be significantly more robust and accurate in other applications that require reconstruction of the N-N interval time series, such as power spectral density estimation using the FFT.)
Using the reconstructed normal rhythm, we select all segments containing N-N intervals that fall in a given bin of the N-N interval histogram, and we compute the histograms of the V-V intervals, NIBs, and N-V intervals among the data selected in this way to obtain a horizontal stripe of each of the lower histograms. In the V-V, NIB, and N-V scattergrams, we represent the number of observations by shades of grey, where a darker shading represents more observations. This process is repeated for each bin in the N-N interval histogram.
The patterns apparent in these heartprints may reveal the dynamics of the underlying mechanism of ventricular ectopy.
Obtaining the heartprints package
- A Unix-like operating system or environment (such as GNU/Linux, Mac OS/X, MS-Windows with the freely available Cygwin environment, Solaris, or another version of Unix) including awk, cc or gcc, make, perl, sh (or a compatible shell such as bash), and tar.
- Unless you already have an RR interval list in the correct format for a recording you wish to study, you will need to install the WFDB Software Package, version 10.3.2 or later. This package includes two different programs (sqrs and wqrs) for detecting the QRS complexes (beats) in a digitized ECG and recording their locations in beat annotation files, and a program (ann2rr) for preparing an RR interval list from an annotation file (such as those in PhysioBank or those created using sqrs or wqrs). The WFDB Software Package is available freely from this site in portable C source form and as ready-to-run binaries for several popular platforms.
- plt version 2.3 or later (including imageplt), also available freely from this site in portable C source form and as ready-to-run binaries for several popular platforms.
Downloading and installing the heartprints package:
- Download the heartprints.tar.gz archive.
- Unpack it using a command such as:
tar xfvz heartprints.tar.gz
- Enter the heartprints/src source directory and compile the software:
cd heartprints/src make
- Install the software:
Using the heartprints package
The heartprint shell script reads a beat annotation file (either from a local copy or directly from the PhysioNet web server). It uses ann2rr (included in the WFDB Software Package) to create an RR interval list, which is then passed to hp_rrlist for analysis.
The hp_rrlist program reads an RR interval list, reconstructs the N-N intervals and accumulates the data for the heartprint histograms and scattergrams using hp_scatter, formats these data for plotting using hp_hist, and invokes plt to produce a heartprint.
Beat Annotation Files
Annotation files are the standard way of storing information about the locations (times of occurrence) and types of events that occur during the recordings available in PhysioBank. Beat annotation files are available for most of the PhysioBank records that include ECGs.
If you wish to study a recording for which no beat annotation file is available, you may be able to create one with sqrs or wqrs (included in the WFDB Software Package). Note, however, that these applications do not distinguish between normal and ectopic beats; it will be necessary to edit the annotation files they create and to change the annotations of the ventricular ectopic beats in order to obtain a (non-trivial) heartprint.
Interbeat (RR) Interval Lists
RR interval lists as used by hp_rrlist are in text format, consisting of two columns (intervals in seconds and annotations). Interval lists in this format can be prepared from beat annotation files using ann2rr. Use a command of the form
ann2rr -r record -a annotator -c -i s -w >record.rr
where record is the record name and annotator is the annotator name of the beat annotation file you wish to study. (If you choose a PhysioBank record and have not previously downloaded the annotation file into a local directory, ann2rr obtains the annotations directly from PhysioNet. For details on the options used in this command, see ann2rr in the WFDB Applications Guide.) For example, the command
ann2rr -r chfdb/chf02 -a ecg -c -i s -w >chf02.rr
creates an interval list from the ecg beat annotations for record chf02 of the BIDMC Congestive Heart Failure Database. The first few lines of output from this command are:
0.620 N 0.624 N 0.612 N 0.624 N 0.624 N 0.620 N 0.636 N 0.648 N 0.624 N 0.616 N 0.452 V 0.788 N 0.632 N . . .
Each N in the interval list indicates that a normal sinus beat occurs at the end of the corresponding interval. The V marks a premature ventricular beat.
Generating a heartprint in an X window
Both heartprint and hp_rrlist are text mode applications that must be run in a terminal window (under MS-Windows, a Command or Cygwin window). If an X11 server is running, use one of the commands below to make a heartprint in an X window.
To make a heartprint from a beat annotation file, use heartprint, by typing a command in the form:
heartprint -r record -a annotator
where record is the record name, and annotator is the annotator name of the beat annotation file you wish to study. (If you have not previously downloaded the annotation file into a local directory, heartprint (via ann2rr) obtains the annotations directly from PhysioNet.)
To make a heartprint from an RR interval list, use hp_rrlist, by typing a command in the form:
hp_rrlist -i record.rr -F frequency
where record.rr is the file containing the RR interval list in the format shown above, and frequency is the sampling frequency, in Hz, of the original ECG signal(s). If the -i ... option is omitted, hp_rrlist reads the interval list from its standard input.
Specifying the sampling frequency when using hp_rrlist affects the bin size of the histograms (for higher sampling frequencies the bins are narrower). If the -F ... option is omitted from the command, hp_rrlist assumes that the ECG signal(s) were sampled at 128 Hz.
If you don't know the sampling frequency, and if the original record is available, the sampling frequency can be determined using the command
sampfreq is included in the WFDB Software Package.
Note that generating a heartprint may require up to a minute. imageplt may report warnings of out-of-range points during this period; be patient and wait for the heartprint to appear.
Generating a PDF, PNG, or PostScript-format heartprint
Use the option -T format with either heartprint or hp_rrlist to generate output in another format. The choices for format are pdf, png, ps, and eps. When using any of these options, redirect the standard output into a file or a file viewer. For example,
heartprint -r record -a annotator -T ps >record.ps
-T ps specifies that the output should be in PostScript format, and record.ps is the name of the output file to be created.
Options for heartprint and hp_rrlist
By default, heartprint and hp_rrlist determine the range of the N-N histogram automatically by eliminating bins at either end of the range having fewer than five members. The heartprint can be customized by specifying the N-N interval limits. Use these options to do so:
- -m NNmin
- specifies the minimum N-N interval included in the lower panels of the heartprint
- -M NNmax
- specifies the maximum N-N interval included in the lower panels of the heartprint
Specifing the N-N interval limits allows you to scale the image along the vertical axis for greater or lesser resolution. Appropriate limits may be difficult to determine from the RR list; if so, try making a heartprint with automatically-determined limits first, then choose limits based on what you see. For example:
hp_rrlist -i chf02.rr -F 250 -m .5 -M 1 -T eps >chf02.eps
will create a heartprint in eps (encapsulated PostScript) format with a bin width of (1/250) seconds, showing only data segments containing N-N intervals between .5 and 1 second in the lower panels.
A detailed description of the heartprints algorithm and its application can be found in:
Schulte-Frohlinde V, Ashkenazy Y, Goldberger AL, Ivanov PCh, Costa M, Morley-Davies A, Stanley HE, Glass L. Complex patterns of abnormal heartbeats. Phys Rev E 66(3-1):031901; 2002 (September).
Schulte-Frohlinde V, Ashkenazy Y, Ivanov PCh, Glass L, Goldberger AL, Stanley HE. Noise effects on the complex patterns of abnormal heartbeats. Phys Rev Lett 87(6):068104; 2001 (6 August).
V Schulte-Frohlinde, Y Ashkenazy, AL Goldberger, PCh Ivanov, M Costa, A Morley-Davies A, HE Stanley HE, L Glass.
Beth Israel Deaconess Medical Center and Harvard Medical School, Boston, USA
Anyone can access the files, as long as they conform to the terms of the specified license.
License (for files):
Open Data Commons Attribution License v1.0
Total uncompressed size: 98.6 KB.
Access the files
- Download the files using your terminal:
wget -r -N -c -np https://physionet.org/files/heartprints/1.0.0/
|heartprint.png (download)||29.6 KB||2019-04-12|
|heartprints.tar.gz (download)||42.9 KB||2019-04-12|