trackpy.batch

trackpy.batch(frames, diameter, minmass=100, maxsize=None, separation=None, noise_size=1, smoothing_size=None, threshold=None, invert=False, percentile=64, topn=None, preprocess=True, max_iterations=10, filter_before=None, filter_after=True, characterize=True, engine='auto', output=None, meta=None)

Locate Gaussian-like blobs of some approximate size in a set of images.

Preprocess the image by performing a band pass and a threshold. Locate all peaks of brightness, characterize the neighborhoods of the peaks and take only those with given total brightness (“mass”). Finally, refine the positions of each peak.

Parameters:

frames : list (or iterable) of images

diameter : odd integer or tuple of odd integers

This may be a single number or a tuple giving the feature’s extent in each dimension, useful when the dimensions do not have equal resolution (e.g. confocal microscopy). The tuple order is the same as the image shape, conventionally (z, y, x) or (y, x). The number(s) must be odd integers. When in doubt, round up.

minmass : float

The minimum integrated brightness. Default is 100 for integer images and 1 for float images, but a good value is often much higher. This is a crucial parameter for eliminating spurious features. .. warning:: The mass value was changed since v0.3.0

maxsize : float

maximum radius-of-gyration of brightness, default None

separation : float or tuple

Minimum separtion between features. Default is diameter + 1. May be a tuple, see diameter for details.

noise_size : float or tuple

Width of Gaussian blurring kernel, in pixels Default is 1. May be a tuple, see diameter for details.

smoothing_size : float or tuple

Size of boxcar smoothing, in pixels Default is diameter. May be a tuple, see diameter for details.

threshold : float

Clip bandpass result below this value. Default, None, defers to default settings of the bandpass function.

invert : boolean

Set to True if features are darker than background. False by default.

percentile : float

Features must have a peak brighter than pixels in this percentile. This helps eliminate spurious peaks.

topn : integer

Return only the N brightest features above minmass. If None (default), return all features above minmass.

preprocess : boolean

Set to False to turn off bandpass preprocessing.

max_iterations : integer

max number of loops to refine the center of mass, default 10

filter_before : boolean

Use minmass (and maxsize, if set) to eliminate spurious features based on their estimated mass and size before refining position. Default (None) defers to trackpy, to optimize for performance.

filter_after : boolean

Use final characterizations of mass and size to eliminate spurious features. True by default.

characterize : boolean

Compute “extras”: eccentricity, signal, ep. True by default.

engine : {‘auto’, ‘python’, ‘numba’}

output : {None, trackpy.PandasHDFStore, SomeCustomClass}

If None, return all results as one big DataFrame. Otherwise, pass results from each frame, one at a time, to the put() method of whatever class is specified here.

meta : filepath or file object, optional

If specified, information relevant to reproducing this batch is saved as a YAML file, a plain-text machine- and human-readable format. By default, this is None, and no file is saved.

Returns:

DataFrame([x, y, mass, size, ecc, signal])

where mass means total integrated brightness of the blob, size means the radius of gyration of its Gaussian-like profile, and ecc is its eccentricity (0 is circular).

See also

locate
performs location on a single image
minmass_version_change
to convert minmass from v0.2.4 to v0.3.0

Notes

This is an implementation of the Crocker-Grier centroid-finding algorithm. [R3]

Locate works with a coordinate system that has its origin at the center of pixel (0, 0). In almost all cases this will be the topleft pixel: the y-axis is pointing downwards.

References

[R3](1, 2) Crocker, J.C., Grier, D.G. http://dx.doi.org/10.1006/jcis.1996.0217