biosppy.signals.egm¶

This module provides methods to process intracardiac EGM (Electrogram) signals.

copyright:

2015-2026 by Instituto de Telecomunicacoes

license:

BSD 3-clause, see LICENSE for more details.

Functions

`call_lat_method`(lat_method, filtered_signal, ...)	Checks **kwargs against valid optional parameters for the selected method and calls it with the valid arguments.
`compare_activation_times`([signal, ...])	Compare activation times calculated by different methods for a single EGM signal.
`dominant_frequency`([signal, sampling_rate, plot])	Get the dominant frequency of the EGM signal.
`dvdt_lat`([signal, sampling_rate, woi, ...])	Calculate activation time based on maximum negative dv/dt from EGM signal.
`egm`([signal, sampling_rate, type, rhythm, ...])	Process intracardiac EGM (Electrogram) signals.
`get_activation_times`([signals, ...])	Calculate activation times for multiple EGM signals.
`get_voltage`([signal, woi, reference])	Get the maximum voltage of the EGM signal.
`get_voltages`([signals, woi, reference])	Get the maximum voltages for multiple EGM signals.
`get_woi`(signal, woi_from, woi_to[, reference])	Extracts a window of interest (WOI) from the EGM signal.
`max_lat`([signal, sampling_rate, woi, ...])	Calculate activation time based on maximum amplitude from EGM signal.
`min_lat`([signal, sampling_rate, woi, ...])	Calculate activation time based on minimum amplitude from EGM signal.
`nleo`([signal, sampling_rate, woi, ...])	Calculate activation time based on the NLEO (Non-Linear Energy Operator) method.
`nleo_lat`([signal, sampling_rate, woi, ...])	Calculate the NLEO (Non-Linear Energy Operator) and activation times from EGM signals.
`organization_index`([signal, sampling_rate])	Calculate organization index of the EGM signal.
`regularity_index`([signal, sampling_rate])	Calculate regularity index of the EGM signal.
`shannon_entropy`([signal, sampling_rate, plot])	Calculate Shannon entropy of the EGM signal.

biosppy.signals.egm.call_lat_method(lat_method, filtered_signal, sampling_rate, verbose=False, **kwargs)[source]¶

Checks **kwargs against valid optional parameters for the selected method and calls it with the valid arguments.

Parameters:

lat_method (function) – The method to calculate activation time (e.g., ‘nleo_activation_time’).
filtered_signal (array) – The preprocessed EGM signal to analyze.
sampling_rate (float) – The sampling frequency of the EGM signal.
woi (list, optional) – Window of interest as [from, to] in samples. If provided, the EGM signal will be cropped to this window.
reference (int, optional) – Reference sample index for the window of interest. If provided, the window will be centered around this reference.
plot (bool, optional) – If True, plots the EGM signal with activation time marked.
**kwargs (dict) – Additional keyword arguments to pass to the activation time method.

Returns:

lat_index (int) – Index corresponding to the activation time of the EGM signal.
lat (float) – Activation time in milliseconds. If woi is provided, time is centered in the window.

biosppy.signals.egm.compare_activation_times(signal=None, sampling_rate=1000.0, woi=None, reference=None, plot=False)[source]¶

Compare activation times calculated by different methods for a single EGM signal.

Parameters:

signal (array) – An array with the EGM signal.
sampling_rate (int, float, optional) – Sampling frequency (Hz) of the EGM signal (default is 1000 Hz).
woi (list, optional) – Window of interest as [from, to] in samples. If provided, the EGM signal will be cropped to this window.
reference (int, optional) – Reference sample index for the window of interest. If provided, the window will be centered around this reference.
plot (bool, optional) – If True, plots the EGM signal with activation times marked.

Returns:

lat_index_nleo (int) – Index corresponding to the activation time from NLEO method.
lat_index_dvdt (int) – Index corresponding to the activation time from -dv/dt method.
lat_index_max (int) – Index corresponding to the activation time from maximum amplitude method.
lat_index_min (int) – Index corresponding to the activation time from minimum amplitude method.
lat_nleo (float) – Activation time in milliseconds from NLEO method.
lat_dvdt (float) – Activation time in milliseconds from -dv/dt method.
lat_max (float) – Activation time in milliseconds from maximum amplitude method.
lat_min (float) – Activation time in milliseconds from minimum amplitude method.

biosppy.signals.egm.dominant_frequency(signal=None, sampling_rate=1000.0, plot=False)[source]¶

Get the dominant frequency of the EGM signal.

Parameters:

signal (array) – An array with the EGM signal.
sampling_rate (int, float, optional) – Sampling frequency (Hz) of the EGM signal (default is 1000 Hz).
plot (bool, optional) – If True, plots the power spectral density of the EGM signal.

Returns:

dominant_freq (float) – The dominant frequency of the EGM signal in Hz.
fft_freqs (array) – The frequencies of the power spectral density of the dominant frequency spectrum.
psd (array) – The power spectral density of the dominant frequency spectrum.

biosppy.signals.egm.dvdt_lat(signal=None, sampling_rate=1000.0, woi=None, reference=None, plot=False)[source]¶

Calculate activation time based on maximum negative dv/dt from EGM signal.

Parameters:

signal (array) – An array with the EGM signal.
sampling_rate (int, float, optional) – Sampling frequency (Hz) of the EGM signal (default is 1000 Hz).
woi (list, optional) – Window of interest as [from, to] in samples. If provided, the EGM signal will be cropped to this window.
reference (int, optional) – Reference sample index for the window of interest. If provided, the window will be centered around this reference.
plot (bool, optional) – If True, plots the EGM signal with activation time marked.

Returns:

lat_index (int) – Index corresponding to the activation time of the EGM signal.
lat (float) – Activation time in milliseconds. If woi is provided, time is centered in the window.

biosppy.signals.egm.egm(signal=None, sampling_rate=1000.0, type='bipolar', rhythm=None, woi=None, reference=None, method='nleo', threshold=None, show=True)[source]¶

Process intracardiac EGM (Electrogram) signals. The outputs of this function depend on the rhythm of the EGM signal.

Parameters:

signal (array) – An array with the EGM signal.
sampling_rate (int, float, optional) – Sampling frequency (Hz) of the EGM signal (default is 1000 Hz).
type (str, optional) – Type of EGM signal. Must be ‘bipolar’ or ‘unipolar’ (default is ‘bipolar’).
rhythm (str) – Rhythm of the EGM signal. Must be ‘sinus’ or ‘af’.
woi (array, optional) – Window of interest as [from, to] in samples. If provided, the EGM signal will be cropped to this window.
reference (int, optional) – Reference sample index for the window of interest. If provided, the window will be centered around this reference.
method (str, optional) – Method to calculate activation time. Must be ‘nleo’, ‘dvdt’, ‘max’, or ‘min’ (default is ‘nleo’).
threshold (float, optional) – Threshold for the NLEO signal. If provided, the NLEO signal will be thresholded.
show (bool, optional) – If True, show a summary plot.

Returns:

ts (array) – Signal time axis reference (seconds).
filtered (array) – Filtered EGM signal.
active_regions (array) – Active regions of the EGM signal.
ts_windowed (array) – Time axis reference for the windowed EGM signal (seconds).
windowed (array) – Windowed EGM signal.
lat_index (int) – Index corresponding to the activation time of the EGM signal.
lat (float) – Activation time in milliseconds.
df (float) – Dominant frequency (Hz).
freqs (array) – Frequencies of dominant frequency spectrum (Hz).
power (array) – Power of dominant frequency spectrum.
entropy (float) – Shannon entropy of the EGM signal.
oi (float) – Organization index of the EGM signal.
ri (array) – Regularity index of the EGM signal.

biosppy.signals.egm.get_activation_times(signals=None, sampling_rate=1000.0, woi=None, reference=None, method='nleo')[source]¶

Calculate activation times for multiple EGM signals.

Parameters:

signals (array) – A 2D array where each row is an EGM signal.
sampling_rate (int, float, optional) – Sampling frequency (Hz) of the EGM signals (default is 1000 Hz).
woi (list, optional) – Window of interest as [from, to] in samples. If provided, each EGM signal will be cropped to this window.
reference (int, optional) – Reference sample index for the window of interest. If provided, the window will be centered around this reference.

Returns:

lat_indexes (int) – Indexes corresponding to the activation times of each EGM signal.
lats (float) – Activation times in milliseconds. If woi is provided, time is centered in the window.

biosppy.signals.egm.get_voltage(signal=None, woi=None, reference=None)[source]¶

Get the maximum voltage of the EGM signal.

Parameters:

signal (array) – An array with the EGM signal.
woi (list, optional) – Window of interest as [from, to] in samples. If provided, the EGM signal will be cropped to this window.
reference (int, optional) – Reference sample index for the window of interest. If provided, the window will be centered around this reference.

Returns:

voltage (float) – The maximum voltage of the EGM signal.

biosppy.signals.egm.get_voltages(signals=None, woi=None, reference=None)[source]¶

Get the maximum voltages for multiple EGM signals.

Parameters:

signals (array) – A 2D array where each row is an EGM signal.
woi (list, optional) – Window of interest as [from, to] in samples. If provided, each EGM signal will be cropped to this window.
reference (int, optional) – Reference sample index for the window of interest. If provided, the window will be centered around this reference.

Returns:

voltages (array) – An array of maximum voltages for each EGM signal.

biosppy.signals.egm.get_woi(signal, woi_from, woi_to, reference=None)[source]¶

Extracts a window of interest (WOI) from the EGM signal.

Parameters:

signal (array) – An array with the EGM signal.
woi_from (int) – Starting index of the window of interest.
woi_to (int) – Ending index of the window of interest.
reference (int, optional) – Reference sample index for the window of interest. If provided, the window will be centered around this reference.

Returns:

egm_woi (array) – The EGM signal cropped to the window of interest.

biosppy.signals.egm.max_lat(signal=None, sampling_rate=1000.0, woi=None, reference=None, plot=False)[source]¶

Calculate activation time based on maximum amplitude from EGM signal.

Parameters:

signal (array) – An array with the EGM signal.
sampling_rate (int, float, optional) – Sampling frequency (Hz) of the EGM signal (default is 1000 Hz).
woi (list, optional) – Window of interest as [from, to] in samples. If provided, the EGM signal will be cropped to this window.
reference (int, optional) – Reference sample index for the window of interest. If provided, the window will be centered around this reference.
plot (bool, optional) – If True, plots the EGM signal with activation time marked.

Returns:

lat_index (int) – Index corresponding to the activation time of the EGM signal.
lat (float) – Activation time in milliseconds. If woi is provided, time is centered in the window.

biosppy.signals.egm.min_lat(signal=None, sampling_rate=1000.0, woi=None, reference=None, plot=False)[source]¶

Calculate activation time based on minimum amplitude from EGM signal.

Parameters:

signal (array) – An array with the EGM signal.
sampling_rate (int, float, optional) – Sampling frequency (Hz) of the EGM signal (default is 1000 Hz).
woi (list, optional) – Window of interest as [from, to] in samples. If provided, the EGM signal will be cropped to this window.
reference (int, optional) – Reference sample index for the window of interest. If provided, the window will be centered around this reference.
plot (bool, optional) – If True, plots the EGM signal with activation time marked.

Returns:

lat_index (int) – Index corresponding to the activation time of the EGM signal.
lat (float) – Activation time in milliseconds. If woi is provided, time is centered in the window.

biosppy.signals.egm.nleo(signal=None, sampling_rate=1000.0, woi=None, reference=None, threshold=None, plot=False)[source]¶

Calculate activation time based on the NLEO (Non-Linear Energy Operator) method.

Parameters:

signal (array) – An array with the EGM signal.
sampling_rate (int, float, optional) – Sampling frequency (Hz) of the EGM signal (default is 1000 Hz).
woi (list, optional) – Window of interest as [from, to] in samples. If provided, the EGM signal will be cropped to this window.
reference (int, optional) – Reference sample index for the window of interest. If provided, the window will be centered around this reference.
plot (bool, optional) – If True, plots the EGM signal with activation time marked.

Returns:

nleo (array) – The NLEO of the EGM signal.
nleo_filt (array) – The low-pass filtered NLEO.
nleo_threshold (array) – The thresholded NLEO signal.
lat_index (int) – Index corresponding to the activation time of the EGM signal.
lat (float) – Activation time in milliseconds. If woi is provided, time is centered in the window.

biosppy.signals.egm.nleo_lat(signal=None, sampling_rate=1000.0, woi=None, reference=None, plot=False)[source]¶

Calculate the NLEO (Non-Linear Energy Operator) and activation times from EGM signals.

Parameters:

egm (np.ndarray) – An array with the EGM signal.
sampling_rate (int, float, optional) – Sampling frequency (Hz).
woi (list, optional) – Window of interest as [from, to] in samples. If provided, the EGM signal will be cropped to this window.
reference (int, optional) – Reference sample index for the window of interest. If provided, the window will be centered around this reference.
plot (bool, optional) – If True, plots the EGM signal with activation time marked.

Returns:

nleo (np.ndarray) – The NLEO of the EGM signal.
nleo_filt (np.ndarray) – The low-pass filtered NLEO.
lat_index (np.ndarray) – Activation time corresponding to the EGM signal.

biosppy.signals.egm.organization_index(signal=None, sampling_rate=1000.0)[source]¶

Calculate organization index of the EGM signal.

Parameters:

signal (array) – An array with the EGM signal.
sampling_rate (int, float, optional) – Sampling frequency (Hz) of the EGM signal (default is 1000 Hz).

Returns:

organization_index (float) – Organization index of the EGM signal.

biosppy.signals.egm.regularity_index(signal=None, sampling_rate=1000.0)[source]¶

Calculate regularity index of the EGM signal.

Parameters:

signal (array) – An array with the EGM signal.
sampling_rate (int, float, optional) – Sampling frequency (Hz) of the EGM signal (default is 1000 Hz).

Returns:

regularity_index (float) – Regularity index of the EGM signal.

biosppy.signals.egm.shannon_entropy(signal=None, sampling_rate=1000.0, plot=False)[source]¶

Calculate Shannon entropy of the EGM signal.

Parameters:

signal (array) – An array with the EGM signal.
sampling_rate (int, float, optional) – Sampling frequency (Hz) of the EGM signal (default is 1000 Hz).
plot (bool, optional) – If True, plots the histogram of the EGM signal voltages.

Returns:

shannon_entropy (float) – Shannon entropy of the EGM signal.