Plotting

Functions of ecgdatakit.plotting.

Static Plots

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[double]) – ECG lead or raw signal array to plot.

  • peaks (NDArray[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 False).

  • 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[double] | list[NDArray[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[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 (in order) when the input is a numpy array. The full signal is plotted without cropping; with a shared x-axis the range covers the longest lead.

Parameters:

  • leads (list[Lead] | ECGRecord | NDArray[double] | list[NDArray[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 False).

  • 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_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:

  • lead (Lead | NDArray[double]) – ECG lead or raw signal array to plot.

  • peaks (NDArray[int_] | None) – R-peak indices. Auto-detected if None.

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

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

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

  • title (str | None)

  • figsize (tuple[float, float])

  • ax (Axes | None)

Return type:

Figure

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

Plot segmented heartbeats.

Parameters:

  • lead (Lead | NDArray[double]) – Source ECG lead or raw signal array.

  • beats (list[Lead] | None) – Pre-segmented beats. Segmented automatically if None. When given, they must have been cut with the same before window so the time axis is right.

  • peaks (NDArray[int_] | None) – R-peak indices for segmentation.

  • overlay (bool) – True: overlay all beats with their mean; False: waterfall display.

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

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

  • before (float) – Window in seconds before and after each R-peak (default 0.2, 0.4). Time 0 on the x-axis is the R-peak.

  • after (float) – Window in seconds before and after each R-peak (default 0.2, 0.4). Time 0 on the x-axis is the R-peak.

  • figsize (tuple[float, float])

  • ax (Axes | None)

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:

  • lead (Lead | NDArray[double]) – Source ECG lead or raw signal array.

  • peaks (NDArray[int_] | None) – R-peak indices.

  • before (float) – Seconds before R-peak.

  • after (float) – Seconds after R-peak.

  • 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_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[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[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

ecgdatakit.plotting.plot_rr_tachogram(rr_ms, figsize=(10, 3), ax=None, *, show=True)[source]

Plot RR interval tachogram.

Parameters:

  • rr_ms (NDArray[double]) – RR intervals in milliseconds.

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

  • figsize (tuple[float, float])

  • ax (Axes | None)

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:

  • rr_ms (NDArray[double]) – RR intervals in milliseconds.

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

  • figsize (tuple[float, float])

  • ax (Axes | None)

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

ecgdatakit.plotting.plot_quality(leads, figsize=(10, 5), *, fs=None, show=True, seconds=None)[source]

Signal quality dashboard: SQI bar chart per lead.

The quality metrics run over the whole of each lead by default, which takes a few seconds per lead on a 24 h Holter. Pass seconds to assess only the start of each lead.

Parameters:

  • leads (list[Lead] | ECGRecord | NDArray[double] | list[NDArray[double]]) – Leads to assess. Also accepts a 2-D numpy array (n_leads × n_samples) or a list of 1-D numpy arrays.

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

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

  • seconds (float | None) – Assess only the first seconds of each lead (default: whole lead).

  • figsize (tuple[float, float])

Return type:

Figure

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

Comprehensive ECG report page.

Includes a header with patient/device info, the standard 3 x 4 layout (each column shows its own 2.5 s of the first 10 s: I/II/III from 0 to 2.5 s, aVR/aVL/aVF from 2.5 to 5 s, and so on), a 10 s lead II rhythm strip, and signal quality for the same first 10 s. Longer recordings (e.g. Holter) are not drawn beyond the first 10 s; use plot_lead() on a slice to look elsewhere.

The paper grid uses 0.2 s / 0.5 mV squares when the leads are in a voltage unit. Leads in raw counts are drawn with automatic amplitude ticks and labelled “raw counts”.

Parameters:
Return type:

Figure

Interactive Plots

ecgdatakit.plotting.iplot_lead(lead, peaks=None, title=None, height=300, *, fs=None, show=True, x_axis='time')[source]

Interactive single lead with hover showing time/amplitude.

Parameters:

  • lead (Lead | NDArray[double]) – ECG lead or raw signal array to plot.

  • peaks (NDArray[int_] | None) – Optional R-peak indices to mark.

  • title (str | None) – Figure title.

  • height (int) – Figure height in pixels.

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

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

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

Return type:

Figure

ecgdatakit.plotting.iplot_leads(leads, peaks_dict=None, title=None, height=None, *, fs=None, show=True, x_axis='time', rows=None, cols=None)[source]

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

Parameters:

  • leads (list[Lead] | ECGRecord | NDArray[double] | list[NDArray[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[int_]] | None) – {label: peaks_array} for per-lead peak markers.

  • title (str | None) – Overall title.

  • height (int | None) – Figure height (auto-calculated if None).

  • 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.iplot_12lead(leads, record=None, title=None, height=None, *, fs=None, show=True, x_axis='time', rows=None, cols=None)[source]

Interactive 12-lead plot with standard lead names.

Unlike iplot_leads(), this function assigns the standard 12-lead names (I, II, III, aVR, …, V6), in order, when the input is a numpy array. The full signal is plotted without cropping.

Parameters:

  • leads (list[Lead] | ECGRecord | NDArray[double] | list[NDArray[double]]) – Leads (or 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) – Optional record for header annotations.

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

  • height (int | None) – Figure height in pixels (auto-calculated if None).

  • 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.iplot_peaks(lead, peaks=None, title=None, height=350, *, fs=None, show=True, x_axis='time')[source]

Interactive lead with R-peak markers.

Hover on peaks shows peak index, RR interval, and instantaneous HR.

Parameters:

  • lead (Lead | NDArray[double]) – ECG lead or raw signal array to plot.

  • peaks (NDArray[int_] | None) – R-peak indices. Auto-detected if None.

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

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

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

  • title (str | None)

  • height (int)

Return type:

Figure

ecgdatakit.plotting.iplot_spectrum(lead, method='welch', height=400, *, fs=None, show=True)[source]

Interactive spectrum with frequency band highlighting.

Parameters:

  • lead (Lead | NDArray[double]) – ECG lead or raw signal array.

  • 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).

  • height (int)

Return type:

Figure

ecgdatakit.plotting.iplot_rr_tachogram(rr_ms, height=300, *, show=True)[source]

Interactive RR interval tachogram.

Parameters:

  • rr_ms (NDArray[double]) – RR intervals in milliseconds.

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

  • height (int)

Return type:

Figure

ecgdatakit.plotting.iplot_poincare(rr_ms, height=500, *, show=True)[source]

Interactive Poincaré plot with SD1/SD2 ellipse.

Parameters:

  • rr_ms (NDArray[double]) – RR intervals in milliseconds.

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

  • height (int)

Return type:

Figure

ecgdatakit.plotting.iplot_report(record, height=1200, *, show=True, x_axis='time')[source]

Interactive full ECG report.

Shows the first 10 s of up to 12 leads and a lead II rhythm strip of the whole recording with a range slider. A rhythm strip longer than 200 000 samples is drawn with min/max decimation and a warning.

Parameters:

  • record (ECGRecord) – Full ECG record.

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

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

  • height (int)

Return type:

Figure

Edit this page Report an issue