sigpyproc.core.filters

sigpyproc.core.filters#

Matched filter class for pulse detection in 1D time series data.

This module contains the MatchedFilter class for pulse detection in 1D time series data. It uses a set of pulse templates with varying widths and selects the template that produces the highest signal-to-noise ratio (SNR) as the best match.

Classes

`MatchedFilter`	Matched filter class for pulse detection in 1D time series data.
`Template`	1D pulse template class for matched filtering.

class sigpyproc.core.filters.MatchedFilter(data, loc_method='median', scale_method='iqr', temp_kind='boxcar', nbins_max=32, spacing_factor=1.5)[source]#

Bases: object

Matched filter class for pulse detection in 1D time series data.

This class implements a matched filter algorithm to detect pulses of varying durations in 1D time series data. It uses a set of pulse templates with varying widths and selects the template that produces the highest signal-to-noise ratio (SNR) as the best match.

Parameters:

datandarray: Input data array for matched filtering (1D).
loc_method{“median”, “mean”, “norm”}, optional: Method to estimate location, by default “median”.
scale_methodstr, optional: Method to estimate scale, by default “iqr”.
temp_kind{“boxcar”, “gaussian”, “lorentzian”}, optional: Type of the pulse template, by default “boxcar”.
nbins_maxint, optional: Maximum number of bins for template width, by default 32.
spacing_factorfloat, optional: Factor for spacing between template widths, by default 1.5.

Attributes:

data: Input data array for matched filtering.
zscores: Computed Z-scores of the input data.
temp_kind: Type of the pulse template.
temp_widths: Template widths used for matched filtering.
temp_bank: List of pulse templates used for matched filtering.
convs: Convolution results for all templates.
peak_bin: Best match template peak bin.
best_temp: Best match template.
snr: Signal-to-noise ratio based on best match template.
best_model: Best match template fit scaled by SNR and data Z-scores.
on_pulse: Best match template pulse region.

Methods

`get_box_width_spacing`(size_max[, spacing_factor])	Get box width spacing for matched filtering.
`plot`([figsize, dpi])	Plot the pulse template.

Raises:

ValueError: If the input data dimension is not 1.

See also

sigpyproc.core.stats.estimate_zscore: Estimate Z-score of input data.
sigpyproc.core.stats.estimate_loc: Estimate location of input data.
sigpyproc.core.stats.estimate_scale: Estimate scale of input data.

Notes

The matched filter is the optimal linear filter for maximizing the signal-to-noise ratio (SNR) of a known pulse template in the presence of additive white noise.

For input data \(x(t)\) and a template \(h(t)\), the matched filter output \(y(t)\) is:

\[y(t) = (x \star h)(t) = \sum_{\tau} x(\tau) h(t - \tau)\]

This is computed efficiently using the FFT-based methods. As per the circular convolution theorem:

\[Y(f) = X(f) H(f)\]

\[y(t) = \mathcal{F}^{-1}(Y(f))\]

where \(\mathcal{F}^{-1}\) is the inverse Fourier transform, \(X(f)\) and \(H(f)\) are the Fourier transforms of \(x(t)\) and \(h(t)\) respectively.

References

[1]

Wikipedia, “Matched filter”, https://en.wikipedia.org/wiki/Matched_filter

[2]

Wikipedia, “Circular convolution”, https://en.wikipedia.org/wiki/Circular_convolution

property data#

Input data array for matched filtering.

Returns:

ndarray: Input data array.

property zscores#

Computed Z-scores of the input data.

Returns:

ZScoreResult: Z-score of the input data.

property temp_kind#

Type of the pulse template.

Returns:

str: Template type.

property temp_widths#

Template widths used for matched filtering.

Returns:

ndarray: Template widths.

property temp_bank#

List of pulse templates used for matched filtering.

Returns:

list[Template]: List of pulse templates.

property convs#

Convolution results for all templates.

Returns:

ndarray: Convolution output.

property peak_bin#

Best match template peak bin.

Returns:

int: Peak bin.

property best_temp#

Best match template.

Returns:

Template: Best match template.

property snr#

Signal-to-noise ratio based on best match template.

Returns:

float: Signal-to-noise ratio.

property best_model#

Best match template fit scaled by SNR and data Z-scores.

Returns:

ndarray: Best match template fit.

property on_pulse#

Best match template pulse region.

Returns:

tuple[int, int]: Start and end bin of the on pulse region.

plot(figsize=(12, 6), dpi=100)[source]#

Plot the pulse template.

Parameters:

figsizetuple[float, float], optional: Figure size in inches, by default (12, 6).
dpiint, optional: Dots per inch, by default 100.

Returns:

Figure: Matplotlib figure object.

static get_box_width_spacing(size_max, spacing_factor=1.5)[source]#

Get box width spacing for matched filtering.

Parameters:

size_maxint: Maximum number of bins for box template width.
spacing_factorfloat, optional: Spacing factor for width, by default 1.5.

Returns:

ndarray: Width spacing for matched filtering.

class sigpyproc.core.filters.Template(data, width, ref_bin=attr_dict['ref_bin'].default, ref=attr_dict['ref'].default, kind=attr_dict['kind'].default)[source]#

Bases: object

1D pulse template class for matched filtering.

This class represents various pulse shapes as templates for matched filtering and provides methods to generate and visualize them.

Parameters:

datandarray: Pulse template data array (1D).
widthfloat: Width of the pulse template in bins.
ref_binint, optional: Reference bin for the pulse template, by default 0.
ref{“start”, “peak”}, optional: Reference type for the pulse template, by default “start”.
kindstr, optional: Type of the pulse template, by default “custom”.

Attributes:

data
width
ref_bin
ref
kind

Methods

`gen_boxcar`(width)	Generate a boxcar pulse template.
`gen_gaussian`(width[, extent])	Generate a Gaussian pulse template.
`gen_lorentzian`(width[, extent])	Generate a Lorentzian pulse template.
`get_model`(peak_bin, nbins)	Get profile model for the pulse template.
`get_on_pulse`(peak_bin, nbins)	Get on pulse region in the profile model for the pulse template.
`plot`([figsize, dpi])	Plot the pulse template.

Raises:

ValueError: If the input data array is empty or not 1D. If the reference bin is out of bounds.

data#

width#

ref_bin#

ref#

kind#

get_model(peak_bin, nbins)[source]#

Get profile model for the pulse template.

Parameters:

peak_binint: Peak bin in the profile.
nbinsint: Profile size.

Returns:

ndarray: Profile model for the pulse template.

get_on_pulse(peak_bin, nbins)[source]#

Get on pulse region in the profile model for the pulse template.

Parameters:

peak_binint: Peak bin in the model.
nbinsint: Profile size.

Returns:

tuple[int, int]: Start and end bin of the on pulse region.

plot(figsize=(10, 5), dpi=100)[source]#

Plot the pulse template.

Parameters:

figsizetuple[float, float], optional: Figure size in inches, by default (10, 5).
dpiint, optional: Dots per inch, by default 100.

Returns:

Figure: Matplotlib figure object.

classmethod gen_boxcar(width)[source]#

Generate a boxcar pulse template.

Parameters:

widthint: Width of the box in bins.

Returns:

Template: Boxcar pulse template with the reference bin at the start.

classmethod gen_gaussian(width, extent=3.5)[source]#

Generate a Gaussian pulse template.

Parameters:

widthfloat: FWHM of the Gaussian pulse in bins.
extentfloat, optional: Extent of the Gaussian pulse in sigma units, by default 3.5.

Returns:

Template: Gaussian pulse template with the reference bin at the peak.

classmethod gen_lorentzian(width, extent=3.5)[source]#

Generate a Lorentzian pulse template.

Parameters:

widthfloat: FWHM of the Lorentzian pulse in bins.
extentfloat, optional: Extent of the Lorentzian pulse in sigma units, by default 3.5.

Returns:

Template: Lorentzian pulse template.

sigpyproc.core.filters

On this page

sigpyproc.core.filters#