Find peaks

ba.FindPeaks searches a two-dimensional Datafield and returns estimated peak centers. It leaves the field and its axes unchanged.

Arguments

The full call with default values is:

peaks = ba.FindPeaks(data, 2, "", 0.05)

All arguments after data are optional and positional. For example, ba.FindPeaks(data) uses the same defaults. Keyword arguments are not supported.

Argument Default Meaning
data Required Two-dimensional Datafield to search.
sigma 2 Gaussian standard deviation in bins; at least 1.
option "" Search modifiers described below.
threshold 0.05 Cutoff relative to the processed field’s maximum.

sigma is the standard deviation of the Gaussian peak model along each axis, measured in bins. For a Gaussian, FWHM ≈ 2.355 * sigma, so the default sigma = 2 corresponds to a full width at half maximum of about 4.71 bins.

threshold must be strictly between 0 and 1. It is applied after processing the field; a smaller value allows weaker peaks to be detected.

Search options

Before searching, the default settings estimate and subtract the background and smooth statistical noise using neighboring intensities (the Markov method). The options change these steps:

Modifier Effect
"nobackground" Keep the background in the data.
"nomarkov" Search without noise smoothing.
"log" Use natural logarithms of positive intensities.

Options are case-insensitive. Combine them without spaces or separators, for example "nobackgroundnomarkov".

For "log", every input value must be strictly positive. This is not checked: zeros produce -inf and negative values produce NaN, so the search result is unreliable. Adding a constant before taking the logarithm changes peak shapes and can change the detected peaks.

With "nobackground", negative intensities are treated by magnitude. This also affects "log" when intensities are below 1, and can produce false peaks.

Current limitations

In the current implementation, Markov smoothing followed by peak sharpening can create spurious peaks. If extra peaks appear, use "nomarkov".

For fields with different numbers of X and Y bins, always include "nomarkov" in option. The current Markov implementation can misplace peaks, and can corrupt memory or crash when there are many more Y bins than X bins.

The search also uses absolute numerical cutoffs, so rescaling intensities can change which peaks it reports, even with a relative threshold.

Return value and coordinates

The Python return value is a tuple of (x, y) pairs, or an empty tuple if no peaks are found. The search returns at most 100 peaks. Use sorted(peaks) to order them by X coordinate.

Coordinates are in the input field’s axis units. They include sub-bin offsets and follow the field’s ascending Y axis. These are estimates from the peak-search algorithm, not fitted peak centers; their accuracy depends on the input and search settings.

See the GISAS example for peak finding in a simulated detector image.

Errors

A non-2D field raises RuntimeError. Invalid search modifiers, sigma, or threshold also raise RuntimeError.

Example

This field has one Gaussian peak centered at (25.5, 10.5):

import bornagain as ba
import numpy as np

frame = ba.Frame(
    ba.EquiDivision("x (nm)", 41, 0, 41),
    ba.EquiDivision("y (nm)", 31, 0, 31))
x, y = np.meshgrid(np.arange(41) + 0.5, np.arange(31) + 0.5)
values = 1 + 100 * np.exp(-((x - 25.5)**2 + (y - 10.5)**2) / 8)
data = ba.Datafield(frame, values.ravel().tolist())

peaks = ba.FindPeaks(data, 2, "nomarkov", 0.05)
print(f"{'Peak':>4} {'x (nm)':>12} {'y (nm)':>12}")
for i, (px, py) in enumerate(sorted(peaks), start=1):
    print(f"{i:4d} {px:12.5f} {py:12.5f}")

Output:

Peak       x (nm)       y (nm)
   1     25.50002     10.50002