coseda.peakfinding package

Submodules

coseda.peakfinding.aurora module

Aurora-plot helpers for peak saturation inspection.

coseda.peakfinding.aurora.aurora_points_cache_path(h5file_path, window_size=5)

Return the per-HDF5 cache path for aurora point data.

Parameters:

• h5file_path (str)

• window_size (int)

Return type:

str

coseda.peakfinding.aurora.compute_aurora_histogram(h5file_path, ini_path=None, window_size=5, bins=420, force_recompute=False, progress_callback=None)

Compatibility wrapper for a single-file aurora histogram.

Parameters:

• h5file_path (str)

• ini_path (str | None)

• window_size (int)

• bins (int)

• force_recompute (bool)

• progress_callback (Callable[[str, int, int], None] | None)

Return type:

dict

coseda.peakfinding.aurora.compute_aurora_histogram_for_files(file_specs, window_size=5, bins=420, force_recompute=False, progress_callback=None)

Build an aurora histogram from one or more HDF5/INI file specs.

Parameters:

• file_specs (Iterable[dict])

• window_size (int)

• bins (int)

• force_recompute (bool)

• progress_callback (Callable[[str, int, int], None] | None)

Return type:

dict

coseda.peakfinding.aurora.compute_aurora_points(h5file_path, ini_path=None, window_size=5, chunk_size=8, progress_callback=None)

Compute raw aurora points as Nx2 columns: radius_px, peak_max_pixel.

Parameters:

• h5file_path (str)

• ini_path (str | None)

• window_size (int)

• chunk_size (int)

• progress_callback (Callable[[str, int, int], None] | None)

Return type:

numpy.ndarray

coseda.peakfinding.aurora.image_bit_depth_label(h5file_path)

Return a display label for the HDF5 image dataset bit depth.

Parameters:

h5file_path (str)

Return type:

str

coseda.peakfinding.aurora.load_or_compute_aurora_points(h5file_path, ini_path=None, window_size=5, force_recompute=False, progress_callback=None)

Load cached aurora points or compute and cache them beside the HDF5 file.

Parameters:

• h5file_path (str)

• ini_path (str | None)

• window_size (int)

• force_recompute (bool)

• progress_callback (Callable[[str, int, int], None] | None)

Return type:

tuple[numpy.ndarray, str, bool]

coseda.peakfinding.findpeaks module

coseda.peakfinding.findpeaks.findpeaks8_batch(input_path, batch_size=5000)

coseda.peakfinding.findpeaks.process_batch(images_batch, x0, y0, num_threads, threshold, min_snr, min_pix_count, max_pix_count, local_bg_radius, min_res, max_res, logfile_path, h5file_path)

coseda.peakfinding.findpeaks.process_file(h5file_path, x0, y0, num_threads, threshold, min_snr, min_pix_count, max_pix_count, local_bg_radius, min_res, max_res, logfile_path, batch_size)

coseda.peakfinding.findpeaks.process_image(i, image_data, x0, y0, threshold, min_snr, min_pix_count, max_pix_count, local_bg_radius, min_res, max_res)

coseda.peakfinding.findpeaks.process_single_frame(h5file_path, frame_index, x0, y0, threshold, min_snr, min_pix_count, max_pix_count, local_bg_radius, min_res, max_res)

coseda.peakfinding.findpeaks_dask module

Peak finding with Diffractem’s peakfinder_8 using Dask for batch parallelism.

coseda.peakfinding.findpeaks_dask.findpeaks_dask_batch(input_path, batch_size=1000, progress_callback=None)

Batch entry point: run Dask peak finding for each INI in a folder/file/list.

coseda.peakfinding.findpeaks_dask.findpeaks_dask_file(client, h5file_path, x0, y0, threshold, min_snr, min_pix_count, max_pix_count, local_bg_radius, min_res, max_res, batch_size, progress_callback=None, outputfolder_path=None)

Run peakfinder_8 over an HDF5 stack using Dask batches, then write results once.

Supports per-frame centers from center_x/y (x0=y0=”h5”) or fixed centers, applies an optional /mask (2D only), and emits paramdump/peak_counts when outputfolder_path is provided.

coseda.peakfinding.findpeaks_dask.load_and_process_batch(h5file_path, indices, x0_list, y0_list, threshold, min_snr, min_pix_count, max_pix_count, local_bg_radius, min_res, max_res, pixmask=None)

Load and process a batch of frames with per-frame or fixed centers and optional mask.

coseda.peakfinding.findpeaks_dask.peakfinding_stats(h5file_path, logfile_path)

Calculate and log peak count statistics for an HDF5 file.

coseda.peakfinding.maxres module

Helpers for deriving per-frame maximum peak radius from peakfinding outputs.

coseda.peakfinding.maxres.write_maxres_dataset(h5file_path, center_x='h5', center_y='h5', logfile_path=None, chunk_size=2048)

Create/update /entry/data/maxres with furthest-peak distance from centre.

Distances are in pixels, one value per frame.

coseda.peakfinding.maxres.write_maxres_from_config(configfile, logfile_path=None, chunk_size=2048)

Resolve centres from an INI file and write /entry/data/maxres.

coseda.peakfinding.peakfinder9 module

Numba-accelerated peakfinder9 implementation with Dask parallelism.

Algorithm

For every candidate pixel (i, j) with value val, the following conditions must all pass (identical to the calNG / CrystFEL pf9 logic):

1. val must be the local maximum on the ring:

   val > max(ring_pixels) + minPeakValueOverNeighbors

2. At least max(1, 2*window_radius - 1) ring pixels must be finite.

3. SNR of the peak pixel:

   val > ring_mean + min_snr_max_pixel * ring_std

4. Integrated peak mass of neighbouring pixels that exceed ring_mean + min_snr_peak_pixels * ring_std:

   peak_mass >= min_snr_whole_peak * ring_std

The “ring” is the perimeter of the (2r+1)×(2r+1) square centred on the candidate (pixels at Chebyshev distance exactly r). Masked / bad pixels are excluded via a valid boolean array (no NaN injection needed).

Implementation

Two Numba-compiled kernels replace the NumPy/SciPy approach:

_pf9_compute_candidates (@njit, parallel=True)

Iterates every pixel in parallel across rows. For each valid pixel, computes ring mean, std, and maximum entirely in-register (no temporary arrays), then flags it as a candidate if all pre-checks pass.

_pf9_collect_peaks (@njit)

Serial pass over the candidate map: computes peak mass and centre-of-mass for each candidate and assembles the output arrays.

Output format is identical to the pf8 pipeline (nPeaks, peakXPosRaw, peakYPosRaw, peakTotalIntensity) so the two algorithms are drop-in replacements for each other.

coseda.peakfinding.peakfinder9.find_peaks_pf9(image, mask, window_radius, min_sigma, min_peak_over_neighbors, min_snr_max_pixel, min_snr_peak_pixels, min_snr_whole_peak, max_peaks=500)

Run peakfinder9 on one 2-D frame.

Parameters:

• image (2-D array-like) – Raw detector frame.

• mask (2-D int8 array or None) – 1 = valid pixel, 0 = masked. Same convention as pf8.

• window_radius (int) – Half-side of the square background ring (windowRadius in the pf9 parameter table).

• min_sigma (float) – Floor applied to the background std before SNR comparisons.

• min_peak_over_neighbors (float) – Candidate pixel value must exceed every ring pixel by this many ADU.

• min_snr_max_pixel (float) – Candidate pixel must be at least this many sigma above the ring mean.

• min_snr_peak_pixels (float) – Pixels in the neighbourhood are counted toward peak mass when they are more than this many sigma above the ring mean.

• min_snr_whole_peak (float) – Integrated peak mass divided by ring std must exceed this value.

• max_peaks (int) – Upper bound on the number of peaks returned per frame.

Returns:

• x_list (list of float fast-scan (column) centre-of-mass)

• y_list (list of float slow-scan (row) centre-of-mass)

• intensity_list (list of float peak mass = Σ (val − mean) over peak pixels)

Return type:

tuple[list[float], list[float], list[float]]

coseda.peakfinding.peakfinder9.find_peaks_pf9_multiscale(image, mask, window_radii, min_sigma, min_peak_over_neighbors, min_snr_max_pixel, min_snr_peak_pixels, min_snr_whole_peak, max_peaks=500)

Run pf9 with one or more window radii and merge the results.

When window_radii is a single int this is identical to find_peaks_pf9. When it is a list, each radius is run independently and the resulting peak lists are merged with _merge_peaks() (strongest peaks kept, duplicates within max(radii) + 1 pixels suppressed).

This lets you cover both dense patterns (small r keeps background ring outside neighbouring peaks) and sparse patterns (large r gives a more stable background estimate) in the same run.

Parameters:

• image (np.ndarray)

• mask (np.ndarray | None)

• min_sigma (float)

• min_peak_over_neighbors (float)

• min_snr_max_pixel (float)

• min_snr_peak_pixels (float)

• min_snr_whole_peak (float)

• max_peaks (int)

Return type:

tuple[list[float], list[float], list[float]]

coseda.peakfinding.peakfinder9.findpeaks9_dask_batch(input_path, batch_size=1000, progress_callback=None)

Batch entry point: run pf9 for each INI file in input_path.

Reads the following keys from the [Parameters] section of each INI:

Parameters:

• input_path (str)

• batch_size (int)

Return type:

None

coseda.peakfinding.peakfinder9.findpeaks9_dask_file(client, h5file_path, x0, y0, window_radius, min_sigma, min_peak_over_neighbors, min_snr_max_pixel, min_snr_peak_pixels, min_snr_whole_peak, min_res, max_res, batch_size, progress_callback=None, outputfolder_path=None)

Run pf9 over an HDF5 frame stack using Dask, then write results.

Output datasets are identical to the pf8 pipeline so both algorithms are interchangeable downstream:

• /entry/data/nPeaks

• /entry/data/peakXPosRaw

• /entry/data/peakYPosRaw

• /entry/data/peakTotalIntensity

Parameters:

• client (dask.distributed.Client)

• h5file_path (str)

• x0 (int or "h5") – Beam centre. Pass "h5" for both to read per-frame centres from entry/data/center_x / center_y.

• y0 (int or "h5") – Beam centre. Pass "h5" for both to read per-frame centres from entry/data/center_x / center_y.

• window_radius (int)

• min_sigma (float)

• min_peak_over_neighbors (float)

• min_snr_max_pixel (float)

• min_snr_peak_pixels (float)

• min_snr_whole_peak (float)

• min_res (float) – Radial resolution ring limits in pixels.

• max_res (float) – Radial resolution ring limits in pixels.

• batch_size (int)

• progress_callback (callable(done, total) or None)

• outputfolder_path (str or None) – If given, saves peak_counts.npy and paramdump.txt there.

Return type:

None

Module contents

Peakfinding routines (single-threaded and Dask).

coseda.peakfinding.findpeaks8_batch(input_path, batch_size=5000)

coseda.peakfinding.findpeaks_dask_batch(input_path, batch_size=1000, progress_callback=None)

Batch entry point: run Dask peak finding for each INI in a folder/file/list.

coseda.peakfinding.findpeaks_dask_file(client, h5file_path, x0, y0, threshold, min_snr, min_pix_count, max_pix_count, local_bg_radius, min_res, max_res, batch_size, progress_callback=None, outputfolder_path=None)

Run peakfinder_8 over an HDF5 stack using Dask batches, then write results once.

Supports per-frame centers from center_x/y (x0=y0=”h5”) or fixed centers, applies an optional /mask (2D only), and emits paramdump/peak_counts when outputfolder_path is provided.

coseda.peakfinding.process_single_frame(h5file_path, frame_index, x0, y0, threshold, min_snr, min_pix_count, max_pix_count, local_bg_radius, min_res, max_res)

coseda.peakfinding.write_maxres_dataset(h5file_path, center_x='h5', center_y='h5', logfile_path=None, chunk_size=2048)

Create/update /entry/data/maxres with furthest-peak distance from centre.

Distances are in pixels, one value per frame.

coseda.peakfinding.write_maxres_from_config(configfile, logfile_path=None, chunk_size=2048)

Resolve centres from an INI file and write /entry/data/maxres.