Peakfinder
A set of peak-finding algorithms developed for analysis of data from LCLS pixel array detectors.
Interface
from ... import imagealgos # Generic method # result = imagealgos.algorithm(*args, **kwargs) peaks = imagealgos.peakfinder_v3(data, mask=None, rank=5, r0=7, dr=2, nsigm=3, npix_min=1, npix_max=1000000, thr_atot=0, son_min=0) peaks = imagealgos.peakfinder_v4(data, mask=None, thr_low=10, thr_high=100, rank=5, r0=7, dr=2, npix_min=1, npix_max=1000000, thr_atot=0, son_min=0)
Input
arguments:
data :
1) numpy.array, ndim=2
- 2-d data array for processing
2) [numpy.array
] - list of 2-d data arrays for processing, ndim=2
3) numpy.array
,
- a set of 2-d data arrays for processing; last two indexes are used as 2-d row and column, higher indexes compacted to the segment indexndim>2
keyword arguments for peak finding:
mask : numpy.array (shape,dtype=np.uint16) | None
- expected the same shape/structure as data
- pixel mask with 0/1 for bad/good pixel
rank : int
- radial size of the region (2*rank+1
rows and columns) around pixel for peak finding
thr
_low : float
- low threshold on pixel intensity for 'Droplet'
finder
thr_high
: float
- high threshold on pixel intensity for 'Droplet'
finder
r0 : float
- internal radius of the ring for evaluation of background and noise rms
dr : float
- width of the ring for evaluation of background and noise rms
nsigm : float
- threshold in number of noise rms for 'Ranker'
keyword arguments for peak selection:
npix_min
: int
- minimum number of pixels in the peak
npix_max
: int
- maximum number of pixels in the peak
thr_atot
: float
- threshold on total peak intensity
son_min
: float
- threshold on signal over noise (S/N) value
Output
peaks
:
list
of peak
objects, where peak
is a container of attributes.
peak attributes:
seg : int
- 2-d segment index beginning from 0, e.g. in CSPAD this index should be in the range from 0 to 31row : int
- row (beginning from 0) of the pixel with maximal intensitycol : int
- column (beginning from 0) of the pixel with maximal intensitynpix : int
- number of pixels accounted in the peakamp_max : float
- maximal intensity among peak pixelsamp_total : float
- total intensity of all pixels accounted in the peakrow_cgrav : float
- row coordinate of the peak evaluated as a "center of gravity" over pixels accounted in the peak using their intensities as weightscol_cgrav : float
- column coordinate of the peak evaluated as a "center of gravity" over pixels accounted in the peak using their intensities as weightsraw_sigma : float
- row coordinate spread rms evaluated in the "center of gravity" algorithmcol_sigma : float
- column coordinate spread rms evaluated in the "center of gravity" algorithmbkgd : float
- per pixel background averaged level estimated for pixels in the ring region (parameters
) around peak centerr0
, dr
noise : float
- per pixel noise r.m.s. estimated for pixels in the ring region (parameters
) around peak centerr0
, dr
son : float
- signal over noise ratio estimated asamp_total
/(noise * sqrt(
npix
))pixinds : list
- list of peak indextuple
(row, col
) for pixels accounted in the peak
peak methods:
row_min() : int
- minimal row of the pixel group accounted in the peakrow_max() : int
- maximal row of the pixel group accounted in the peakcol_min() : int
- minimal column of the pixel group accounted in the peakcol_max() : int
- maximal column of the pixel group accounted in the peak- other methods involving data and
pixinds
Peak-finding algorithms
Method peakfinder is a wrapper around a few algorithms. First argument mode
switches between different peak-finding algorithms. Each algorithm works in a few stages. First stage is a search for peak candidates or "seed" peaks and this is a most distinctive part between algorithms:
- v4 - Droplet - or droplet-finder is a two-threshold algorithm searching for groups of connected pixels with intensity above
thr
_low
around group central pixel with intensity exceedingthr_high
in the region restricted by the radial parameterrank
. In the loop over all pixels each pixel with intensity grater or equalthr_high
is considered as a peak candidate. For each candidate recursive algorithm is launched and searches for a group of connected pixels with intensity grater or equalthr
_low
in the square region with dimensions2*rank+1
pixel in rows and columns. Pixels of the group are marked as busy on 2-d map and are not used for other groups. Central pixel of the peak candidate should have maximal intensity in the group of connected pixels, otherwise recursion is terminated and all group pixels released for further search. Two neighbor pixels with intensity abovethr
_low
and having common boarder are assumed connected. Pixels having a single common vertex are assumed disconnected. Background meanbkgd
and rmsnoise
values are evaluated for pixels in the ring with internal radiusr0
and widthdr
around central pixel. Pixels with intensity abovethr
_low
are excluded from evaluation of background. - v3 - Ranker - searches peak candidates as group of connected pixels around local intensity maximums of specified
rank
. Maps of local maximums and minimums of specifiedrank
are generated fordata
array. Parameterrank
defines a square region with dimensions2*rank+1
pixels in rows and columns around center pixel. Each local maximum is considered as a peak candidate. Its background meanbkgd
andnoise
values are evaluated using surrounding pixels in the ring with internal radiusr0
and widthdr
. Pixels marked as local maximums and minimums (for symmetry) of specified rank in rows and columns are excluded in evaluation of the background parameters.NOTE:
due to excluded extremes the background rms is under-estimated in this algorithm, so set parameternsigm
wisely. Then, for each peak candidate local threshold parameterthr=
(no exclusion forbkgd
+nsigm*noisensigm=0
) is used. Recursive algorithm searches for the group of connected pixels with intensity above local thresholdthr
in therank
-restricted region.
Other stages of all algorithms are about the same.
- returned values of
amp_max
andamp_total
are background corrected by subtractingbkgd
andbkgd
*
, respectivelynpix
- signal over noise
son
is evaluated asamp_total
/(noise * sqrt(
,npix
)) - output list of peaks is generated from the list of seed peaks complying with selection parameters
npix_min, npix_max, amax_thr, atot_thr, son_min
.
Comments
- Chuck: use specific methods in stead of single wrapper
- cpo:
- look at scipy optimize, skimage ransac
- think about returning dictionary vs. object with attributes
- consider make row_min a method
- turn off background subtraction in intuitive way? r0=None or dr=None
- vote to do v4 only for now
- all kwarg
- worry about seg
- vote to only support 2D array, at least at beginning
- 2016-11-09 grp mtg (cpo, David, Wilko):
- use meaningful parameters
- separate arguments and keywards with default parameters
- check input validity (i.e. pyvalid) that keyargs are not misspelled.
- peaks - dict(arrays)