ECGSim-Advanced: An Open-Source Interactive Simulator for Teaching Electrolyte, Conduction, and Repolarization Abnormalities in Electrocardiography

Implementation

ECGSim-Advanced is developed using the R programming language (version 4.5.1)¹⁷ and the Shiny web application framework (version 1.10.0)¹⁸ to create an interactive and browser-based user interface. Data transformation and internal logic are managed using the dplyr package (version 1.1.4),¹⁹ while ECG visualization is handled by ggplot2 (version 3.5.2).²⁰ User-triggered events and dynamic UI behaviour are enabled using shinyjs (version 2.1.0.9011).²¹

ECG waveform generation

The simulator generates ECG signals through the summation of Gaussian-modelled waveform components. Each wave - P, Q, R, S, T, and U - is constructed using the generate_segment() function defined as:

Where A is the amplitude, t is time, c is the wave centre, and sigma is derived from the duration and shape of the wave.

Custom functions model each wave:

Parameter translation and reactive logic

User input from the interface (e.g., selected mode, heart rate, QTc, electrolyte state) is converted into numeric waveform parameters via the current_ecg_params() function. These values are then passed to generated_ecg_trace() to create a beat-by-beat ECG signal over a standard time window.

Simulation modes

ECGSim-Advanced provides dedicated simulation modes for four pathological domains: electrolyte imbalance, AV conduction blocks, QT interval syndromes, and normal sinus rhythm. Within each mode, users can manipulate relevant parameters in real time - such as heart rate, QTc interval, potassium and calcium levels, or atrial and ventricular rates - to generate ECG waveforms reflecting pathophysiological changes. The electrolyte mode allows selection of hypokalaemia, hyperkalemia, hypocalcaemia, or hypercalcemia; the AV block mode includes first-, second- (Mobitz type I and II), and third-degree AV blocks; and the QT syndrome mode enables simulation of both Long and Short QT Syndromes. The waveform morphology dynamically responds to these inputs, with underlying Gaussian functions adjusted to reflect user-defined settings. A summary of available modes, user-controlled parameters, and key ECG features is shown in Table 1.

User interface

The user interface of ECGSim-Advanced (see Figure 1) is composed of two primary components: a sidebar and a main display panel. The sidebar facilitates mode selection and provides adjustable controls, including sliders and dropdown menus, enabling users to modify simulation parameters dynamically. The main display panel features a real-time electrocardiogram (ECG) plot that updates in response to parameter adjustments. Additionally, it incorporates a calliper tool designed for precise measurement of intervals (dX) and amplitudes (dY). Dynamic text boxes are integrated to present updated interval values and educational summaries, enhancing the learning experience by providing immediate feedback and contextual information.

Figure 1. Screenshot of the ECGSim-advanced user interface.

The left sidebar enables selection of simulation mode (e.g., electrolyte imbalance, AV block, QT syndrome) and adjustment of key parameters, including heart rate (30–180 bpm), paper speed (25/50 mm/s), and ECG gain (0.5x–2x). The main panel displays a real-time ECG waveform on standard grid paper, which updates dynamically with parameter changes. Simulated interval measurements (PR, QRS, QT, QTc) are automatically calculated and shown below the controls. The caliper tool allows manual measurement of waveform intervals and amplitudes. Key ECG findings and educational notes are presented beneath the waveform, and a clinical vignette selection system is integrated at the bottom for case-based learning.

Clinical vignettes

An integrated vignette system provides real-world clinical scenarios. When a vignette is selected (e.g., “Post-Thyroidectomy Paraesthesias”), the application automatically loads corresponding simulation parameters (e.g., hypocalcemia), generates the relevant ECG trace, and provides a diagnostic prompt with explanation.

System Requirements and Launch Instructions

Workflow

Interactive simulation output

The ECGSim-Advanced interface provides real-time feedback, displaying an ECG waveform that dynamically adjusts with any user input. The plot replicates standard ECG paper, with customizable paper speed (25 mm/s or 50 mm/s) and gain (0.5x, 1x, 2x). Calipers allow direct point-to-point measurements for both interval duration (dX) and voltage amplitude (dY). Below the waveform, live values for PR, QRS, QT, and QTc intervals are continuously updated.

Accuracy of pathological simulation

ECGSim-Advanced reliably reproduces hallmark ECG features under various pathological states. The application generates waveform changes consistent with established diagnostic criteria. In simulations of electrolyte imbalances, hypokalemia is represented with flattened or inverted T-waves, ST segment depression, and pronounced U-waves ( Figure 2A). For hyperkalemia, the application produces peaked T-waves, prolonged PR intervals, absent P-waves, and widened QRS complexes ( Figure 2B). Hypocalcaemia is simulated by producing ST segment lengthening and QT interval prolongation ( Figure 3A), while hypercalcemia leads to a shortened ST segment and abbreviated QT interval ( Figure 3B).

Figure 2. Potassium imbalance simulations.

(A) Hyperkalemia: Peaked T-waves, PR prolongation (240 ms), absent P-waves, and QRS widening (140 ms). (B) Hypokalemia: Flattened T-waves, ST segment depression (0.8 mm), and prominent U-waves. Simulations were generated at 75 bpm, 25 mm/s paper speed and 10 mm/mV (1x) ECG gain.

Figure 3. Calcium disturbance simulations.

(A) Hypercalcemia: Shortening of the QTc (313 ms) and ST segment (B) Hypocalcemia: ST segment lengthening and QTc prolongation (470 ms). Simulations were generated at 75 bpm, 25 mm/s paper speed and 10 mm/mV (1x) ECG gain.

The AV block mode encompasses first-, second-, and third-degree conduction disturbances. First-degree AV block is rendered as uniform prolongation of the PR interval with preserved atrioventricular conduction. Second-degree AV block is illustrated using static templates for both Mobitz type I (Wenckebach), defined by progressive PR interval prolongation culminating in a non-conducted P-wave, and Mobitz type II, which features fixed PR intervals with intermittent dropped QRS complexes. Third-degree (complete) AV block is simulated with dissociated atrial and ventricular rhythms, displaying distinct, fixed P and QRS rates ( Figure 4).

Figure 4. Third-degree AV block simulation.

Complete atrioventricular dissociation with independent regular atrial (70 bpm) and ventricular (40 bpm) rhythms. Simulated using atrial and ventricular rate inputs as described in Methods. Simulations were generated at 75 bpm, 25 mm/s paper speed and 10 mm/mV (1x) ECG gain.

In the context of repolarisation disorders, ECGSim-Advanced generates a prolonged QTc interval (e.g., 500 ms) with broad, low-amplitude T-waves for Long QT Syndrome ( Figure 5A), and a shortened QT interval with narrow, peaked T-waves for Short QT Syndrome ( Figure 5B). The QT interval is derived from QTc using Bazett’s formula: QT = QTc · √RR. Across all tested pathological states, the simulated ECG waveforms and interval measurements were consistent with published electrocardiographic standards, supporting the accuracy and educational value of the platform.

Figure 5. Repolarization disorder simulations.

(A) Long QT Syndrome: QTc prolongation (490 ms) with broad, low-amplitude T-waves at 75 bpm. (B) Short QT Syndrome: Shortened QTc (315 ms) with narrow, peaked T-waves at 75 bpm. QT values calculated using Bazett’s formula. Simulations were generated at 75 bpm, 25 mm/s paper speed and 10 mm/mV (1x) ECG gain.

Use case 1: Simulating severe hyperkalaemia

Severe hyperkalaemia is simulated by selecting the Electrolyte Imbalance mode, setting potassium as the target electrolyte, and adjusting the concentration to the hyperkaliaemic range with a base heart rate of 60 bpm. The resulting ECG displays tall, peaked T-waves, PR interval prolongation, flattening or absence of P-waves, and QRS widening. Educational notes describe the progressive changes of hyperkalaemia, and interval measurements confirmed prolongation of PR and QRS durations with characteristic T-wave alterations.

Use case 2: Simulating third-degree (complete) av block

The simulator was configured in AV Blocks mode to model a third-degree AV block. The atrial rate was set to 80 beats per minute, representing regular P-wave activity, while the ventricular escape rate was set to 35 beats per minute to simulate independent ventricular rhythm. The resulting ECG trace demonstrated classic AV dissociation, with regular P-waves at 80 bpm and independent, regular QRS complexes at 35 bpm. As expected in complete AV block, the PR interval was not applicable. Educational notes explained the mechanism of AV dissociation and the nature of escape rhythms, while interval measurements confirmed the distinct atrial and ventricular rates characteristic of this conduction abnormality.

Use case 3: Simulating long qt syndrome (LQTS)

For this scenario, the simulator was set to QT Syndromes mode with Long QT Syndrome selected, a target QTc of 500 ms, and a base heart rate of 70 beats per minute. The resulting ECG trace demonstrated a visibly prolonged QT interval, with T-wave morphology appearing broader than normal. Educational annotations described the clinical features and risks associated with LQTS, including the potential for Torsades de Pointes and common aetiologies. Interval measurements confirmed a QT interval consistent with a QTc of approximately 500 ms at the specified heart rate.

Use case 4: Engaging with a clinical vignette (e.g., “Post-thyroidectomy paraesthesias”)

In this scenario, the user selects the clinical vignette titled “Post-Thyroidectomy Paraesthesias” from the dropdown menu. The simulator presents a case description of a 42-year-old female who develops circumoral numbness three days after total thyroidectomy, accompanied by a related diagnostic question. Upon vignette selection, the system automatically switches to Electrolyte Imbalance mode, selects calcium as the relevant electrolyte, and sets the level to hypocalcaemia. The ECG display updates to reflect features characteristic of hypocalcaemia, notably a prolonged QT interval resulting from ST segment lengthening. When the user clicks “Show Clues & Explanation,” the simulator reveals the diagnosis of hypocalcaemia, outlines the expected ECG findings, and provides a rationale linking the clinical scenario to the observed electrocardiographic changes.

Comparison with existing tools

Several commercial and academic ECG education platforms exist, including Life in the Fast Lane ECG Library, ECGPedia, and PhysioNet simulators. While these resources offer high-quality static ECGs and explanations, they generally lack the flexibility for real-time manipulation of waveform characteristics. Tools like SimECG or SimVentricular may provide rhythm training but often require institutional licenses or focus narrowly on arrhythmias. ECGSim-Advanced fills a unique niche by simulating morphological rather than rhythmic changes and offering transparent, modifiable source code.

Limitations

Despite its advantages, the simulator has several limitations. First, it is currently limited to a single-lead representation (Lead II approximation), which restricts the simulation of conditions requiring spatial analysis across multiple leads (e.g., STEMI localization). Second, the use of Gaussian approximations, while computationally efficient, may not fully replicate the complex morphologies seen in clinical practice. Third, dynamic rhythm simulation (e.g., progressive PR lengthening in Mobitz I) is not yet implemented; second-degree AV blocks are shown as static representations with accompanying educational notes.

Additionally, no formal user study has yet been conducted to assess learning outcomes, usability metrics, or long-term knowledge retention. Such validation will be important for future educational deployment and comparison with existing resources.

Future directions

Planned enhancements include:

The tool’s open-source nature makes it well-suited for collaborative development by the broader medical education and cardiology communities. It also allows easy adaptation for use in simulation labs, flipped classrooms, or remote learning environments.