spectrochempy.find_peaks

find_peaks(dataset, height=None, window_length=3, threshold=None, distance=None, prominence=None, width=None, wlen=None, rel_height=0.5, plateau_size=None, use_coord=True, as_result=False)

Find and analyze peaks in spectroscopic data with advanced filtering options.

This function extends scipy.signal.find_peaks by adding spectroscopy-specific features like coordinate system awareness and unit handling. It performs peak detection through local maxima analysis and supports various filtering criteria to identify significant peaks.

Parameters

• dataset (NDDataset) – Input dataset containing spectral data. Must be 1D or 2D with len(X.y) == 1.

• height (float or array-like, optional) – Minimum and/or maximum peak height criteria. Can be specified as: - Single value for minimum height - Tuple (min, max) for height range - Array matching x for position-dependent criteria

• window_length (int, default: 3) – Window size for peak interpolation. Must be odd. Larger values provide smoother interpolation but may miss narrow peaks.

• threshold (float or array-like, optional) – Minimum height difference between peak and neighboring points. Useful for filtering out noise-related peaks.

• distance (float, optional) – Minimum separation between peaks. Peaks closer than this are filtered based on their prominence.

• prominence (float or array-like, optional) – Required prominence (height above surrounding baseline) of peaks.

• width (float or array-like, optional) – Required width of peaks. Interpreted as coordinate units if use_coord=True, otherwise as number of points.

• wlen (int or float, optional) – Window length for prominence calculation. Affects computation speed for large datasets.

• rel_height (float, default: 0.5) – Relative height for width calculation (0-1 range).

• plateau_size (float or array-like, optional) – Required size of peak plateau (flat top).

• use_coord (bool, default: True) – Whether to use coordinate system units instead of array indices.

• as_result (bool, default: False) – If True, return a PeakFindingResult object. If False, preserve the historical (peaks, properties) tuple return.

Returns

• peaks (NDDataset or None) – Dataset containing identified peaks with interpolated positions and heights. Returned when as_result=False.

• properties (dict or None) – Peak properties including heights, widths, prominences, and more. All values use appropriate units when use_coord=True. Returned when as_result=False.

• result (PeakFindingResult) – Structured peak finding result. Returned when as_result=True.

Notes

• Peak positions are refined using quadratic interpolation when window_length > 1

• The function handles units automatically when use_coord=True

• For noisy data, consider preprocessing with smoothing functions

Examples

Basic peak finding with a synthetic spectrum:

>>> x = scp.Coord.linspace(0.0, 10.0, 501, title="x", units="cm^-1")
>>> y = (scp.gaussian(x, ampl=1.0, pos=3.0, width=0.5, normalized=False)
...    + scp.gaussian(x, ampl=0.8, pos=7.0, width=0.6, normalized=False))
>>> ds = scp.NDDataset(y, coordset=[x])
>>> peaks, props = ds.find_peaks(height=0.5)
>>> len(peaks)
2

Physical-unit spacing constraints are accepted when coordinates carry units:

>>> x = scp.Coord.linspace(0.0, 10.0, 501, title="x", units="cm^-1")
>>> y = (scp.gaussian(x, ampl=1.0, pos=3.0, width=0.5, normalized=False)
...    + scp.gaussian(x, ampl=0.8, pos=7.0, width=0.6, normalized=False))
>>> ds = scp.NDDataset(y, coordset=[x])
>>> peaks, props = ds.find_peaks(distance="1 cm^-1", width=0.2)
>>> len(peaks)
2

Return a structured result when a tabular/export representation is useful:

>>> x = scp.Coord.linspace(0.0, 10.0, 501, title="x", units="cm^-1")
>>> y = (scp.gaussian(x, ampl=1.0, pos=3.0, width=0.5, normalized=False)
...    + scp.gaussian(x, ampl=0.8, pos=7.0, width=0.6, normalized=False))
>>> ds = scp.NDDataset(y, coordset=[x])
>>> result = ds.find_peaks(height=0.5, as_result=True)
>>> rows = result.to_dict()
>>> len(rows)
2