Static Plots (matplotlib)

All static plot functions display the figure automatically by default (show=True). Pass show=False to suppress display and get back the matplotlib.figure.Figure for saving or further customization. Functions with an ax parameter can render into an existing axes for composability; when ax=None, a new figure is created.

Lead Waveforms

plot_lead()

Plot a single ECG lead waveform

plot_leads()

Plot multiple leads in a grid layout

plot_12lead()

Plot 12 leads with standard lead names (I, II, III, aVR, …, V6)
ecgdatakit.plotting.plot_lead(lead, peaks=None, title=None, show_grid=False, figsize=(12, 3), ax=None, *, fs=None, show=True, x_axis='time')[source]

Plot a single ECG lead waveform.

Parameters:

  • lead (Lead | ndarray[tuple[Any, ...], dtype[double]]) – ECG lead or raw signal array to plot.

  • peaks (ndarray[tuple[Any, ...], dtype[int_]] | None) – Optional R-peak indices to mark.

  • title (str | None) – Figure title. Defaults to the lead label.

  • show_grid (bool) – Draw ECG paper-style grid (default True).

  • figsize (tuple[float, float]) – Figure size in inches (default (12, 3)).

  • ax (Axes | None) – Existing axes to draw on. A new figure is created if None.

  • fs (int | None) – Sample rate in Hz. Required when lead is a numpy array.

  • show (bool) – Display the plot immediately (default True). Set to False to return the figure without displaying.

  • x_axis (str) – "time" for seconds (default) or "samples" for sample indices (1, 2, …, N).

Return type:

Figure

ecgdatakit.plotting.plot_leads(leads, peaks_dict=None, title=None, show_grid=False, figsize=(12, None), share_x=True, *, fs=None, show=True, x_axis='time', rows=None, cols=None)[source]

Plot multiple leads in a grid layout (vertical stack by default).

Parameters:

  • leads (list[Lead] | ECGRecord | ndarray[tuple[Any, ...], dtype[double]] | list[ndarray[tuple[Any, ...], dtype[double]]]) – Leads to plot. Also accepts a 2-D numpy array (n_leads × n_samples) or a list of 1-D numpy arrays.

  • peaks_dict (dict[str, ndarray[tuple[Any, ...], dtype[int_]]] | None) – {label: peaks_array} for per-lead R-peak markers.

  • title (str | None) – Overall figure title.

  • show_grid (bool) – Draw ECG paper-style grid.

  • figsize (tuple[float, float | None]) – Width is fixed; height is auto-calculated (2 in per row) when None.

  • share_x (bool) – Share the x-axis across all subplots (default True).

  • fs (int | None) – Sample rate in Hz. Required when leads is a numpy array.

  • show (bool) – Display the plot immediately (default True).

  • x_axis (str) – "time" for seconds (default) or "samples" for sample indices.

  • rows (int | None) – Number of rows in the subplot grid. Derived from cols or defaults to one row per lead when neither is given.

  • cols (int | None) – Number of columns in the subplot grid (default 1).

Return type:

Figure

ecgdatakit.plotting.plot_12lead(leads, record=None, title=None, show_grid=False, figsize=(12, None), share_x=True, *, fs=None, show=True, x_axis='time', rows=None, cols=None)[source]

Plot 12 leads with standard lead names (I, II, III, aVR, …, V6).

Unlike plot_leads(), this function assigns the standard 12-lead names when the input contains unnamed leads (e.g. a raw numpy array). The full signal is plotted without cropping.

Parameters:

  • leads (list[Lead] | ECGRecord | ndarray[tuple[Any, ...], dtype[double]] | list[ndarray[tuple[Any, ...], dtype[double]]]) – Leads (or full record) to plot. Also accepts a 2-D numpy array (n_leads × n_samples) or a list of 1-D numpy arrays.

  • record (ECGRecord | None) – If provided, a header with patient/device/measurement info is shown.

  • title (str | None) – Overall figure title.

  • show_grid (bool) – Draw ECG paper-style grid (default True).

  • figsize (tuple[float, float | None]) – Width is fixed; height is auto-calculated (2 in per row) when None.

  • share_x (bool) – Share the x-axis across all subplots (default True).

  • fs (int | None) – Sample rate in Hz. Required when leads is a numpy array.

  • show (bool) – Display the plot immediately (default True).

  • x_axis (str) – "time" for seconds (default) or "samples" for sample indices.

  • rows (int | None) – Number of rows in the subplot grid. Derived from cols or defaults to one row per lead when neither is given.

  • cols (int | None) – Number of columns in the subplot grid (default 1).

Return type:

Figure

Annotations & Beats

plot_peaks()

Plot lead with R-peak markers and RR interval annotations

plot_beats()

Plot segmented heartbeats

plot_average_beat()

Plot ensemble-averaged beat with ±1 SD shading
ecgdatakit.plotting.plot_peaks(lead, peaks=None, title=None, figsize=(12, 3), ax=None, *, fs=None, show=True, x_axis='time')[source]

Plot lead with R-peak markers and RR interval annotations.

Parameters:
Return type:

Figure

ecgdatakit.plotting.plot_beats(lead, beats=None, peaks=None, overlay=True, figsize=(8, 5), ax=None, *, fs=None, show=True)[source]

Plot segmented heartbeats.

Parameters:
Return type:

Figure

ecgdatakit.plotting.plot_average_beat(lead, peaks=None, before=0.2, after=0.4, figsize=(6, 4), ax=None, *, fs=None, show=True)[source]

Plot ensemble-averaged beat with ±1 SD shading.

Parameters:
Return type:

Figure

Frequency Domain

plot_spectrum()

Plot power spectral density or FFT magnitude spectrum

plot_spectrogram()

Plot time-frequency spectrogram (STFT)
ecgdatakit.plotting.plot_spectrum(lead, method='welch', figsize=(10, 4), ax=None, *, fs=None, show=True)[source]

Plot power spectral density or FFT magnitude spectrum.

Parameters:

  • lead (Lead | ndarray[tuple[Any, ...], dtype[double]]) – ECG lead or raw signal array to analyse.

  • method (str) – "welch" for PSD or "fft" for magnitude spectrum.

  • fs (int | None) – Sample rate in Hz. Required when lead is a numpy array.

  • show (bool) – Display the plot immediately (default True).

  • figsize (tuple[float, float])

  • ax (Axes | None)

Return type:

Figure

ecgdatakit.plotting.plot_spectrogram(lead, nperseg=256, figsize=(12, 4), ax=None, *, fs=None, show=True)[source]

Plot time-frequency spectrogram (STFT).

Parameters:

  • lead (Lead | ndarray[tuple[Any, ...], dtype[double]]) – ECG lead or raw signal array.

  • nperseg (int) – Segment length for STFT.

  • fs (int | None) – Sample rate in Hz. Required when lead is a numpy array.

  • show (bool) – Display the plot immediately (default True).

  • figsize (tuple[float, float])

  • ax (Axes | None)

Return type:

Figure

HRV

plot_rr_tachogram()

Plot RR interval tachogram

plot_poincare()

Poincaré plot: RR(n) vs RR(n+1) with SD1/SD2 ellipse

plot_hrv_summary()

Combined HRV dashboard: tachogram, Poincaré, frequency bands, metrics
ecgdatakit.plotting.plot_rr_tachogram(rr_ms, figsize=(10, 3), ax=None, *, show=True)[source]

Plot RR interval tachogram.

Parameters:
Return type:

Figure

ecgdatakit.plotting.plot_poincare(rr_ms, figsize=(6, 6), ax=None, *, show=True)[source]

Poincaré plot: RR(n) vs RR(n+1) with SD1/SD2 ellipse.

Parameters:
Return type:

Figure

ecgdatakit.plotting.plot_hrv_summary(rr_ms, figsize=(14, 8), *, show=True)[source]

Combined HRV dashboard: tachogram, Poincaré, frequency bands, metrics.

Parameters:
Return type:

Figure

Quality

plot_quality()

Signal quality dashboard: SQI bar chart per lead
ecgdatakit.plotting.plot_quality(leads, figsize=(10, 5), *, fs=None, show=True)[source]

Signal quality dashboard: SQI bar chart per lead.

Parameters:
Return type:

Figure

Full Report

plot_report()

Comprehensive ECG report page
ecgdatakit.plotting.plot_report(record, figsize=(16, 20), *, show=True)[source]

Comprehensive ECG report page.

Includes header with patient/device info, 12-lead grid, rhythm strip, and quality indicators.

Parameters:
Return type:

Figure