trackpy.refine_leastsq¶

trackpy.refine_leastsq(f, reader, diameter, separation=None, fit_function='gauss', param_mode=None, param_val=None, constraints=None, bounds=None, compute_error=False, pos_columns=None, t_column='frame', max_iter=10, max_shift=1, max_rms_dev=1.0, residual_factor=100000.0, **kwargs)¶

Refines overlapping feature coordinates by least-squares fitting to radial model functions.

This does not raise an error if minimization fails. Instead, coordinates are unchanged and the added column cost will contain NaN.

Parameters:

fDataFrame

pandas DataFrame containing coordinates of features. Required columns are the position columns (see pos_columns)

Any fit parameter (which are at least ‘background’, ‘signal’ and ‘size’) that is not present should be either given as a standard value in the param_val argument, or be present as a default value in the used fit function.

If a FramesSequence is supplied as a reader, the time column (see t_column is also required.

readerpims.FramesSequence, pims.Frame, or ndarray

A pims.FrameSequence is an object that returns an image when indexed. It also provides the frame_shape attribute. If not a FrameSequence is given a single image is assumed and all features that are present in f are assumed to be in that image.

diameternumber or tuple

Determines the feature mask diameter that is used for the refinement. Use a tuple to account for anisotropic pixel sizes (e.g. (7, 11)).

separationnumber or tuple, optional

Determines the distance below which features are considered in the same cluster. By default, equals diameter. As the model feature function is only defined up to diameter, it does not effect the refine results if this value is increased above diameter.

fit_functionstring or or dict, optional

The type of fit function. Either one of the default functions {'gauss', 'hat', 'ring', 'inv_series_<number>'}, or a custom function defined using a dictionary. Defaults to 'gauss'.

The fit function is loosely defined as follows:

\[ \begin{align}\begin{aligned}F(r, A, \sigma, \vec{p}) = B + A f(r, \vec{p})\\r^2 = \frac{x - c_x}{\sigma_x}^2 + \frac{y - c_y}{\sigma_y}^2\end{aligned}\end{align} \]

In which \(r\) denotes the reduced distance to the feature center, \(B\) the background intensity of the image, \(A\) (‘signal’) the maximum value of the feature, \(\vec{p}\) a list of extra model parameters, \(\sigma\) (‘size’) the radial distance from the feature center at which the value of \(f(r)\) has decayed to \(1/e \approx 0.37\), and \(\vec{c}\) the coordinate of the feature center.

So size is smaller than the apparent radius of the feature. Typically, it is three to four times lower than the diameter.

The 'gauss' function is a Gaussian, without any extra parameter
The 'hat' function is solid disc of relative size disc_size, and gaussian smoothed borders.
The 'ring' model function is a displaced gaussian with parameter thickness.
The inv_series_<number> model function is the inverse of an even polynomial containing <number> parameters (signal_mult / (1 + a r**2 + b r**4 + c r*2 + …) signal_mult is best chosen such that the maximum of the polynomial equals 1.

Define your own model function with a dictionary, containing:

params : list of str List of custom parameter names. The list has the same length as the p ndarray in fun and dfun. It does not include background, signal, or size.
fun : callable The image model function. It takes arguments (r2, p, ndim).
- r2 is a 1d ndarray containing the squared reduced
  radial distances (see the above definition).
- p is an array of extra feature parameters
- ndim is the number of dimensions in the image
The function returns an ndarray of the same shape as r2, containing the feature intensity values up to a maximum of 1.
dfun : callable, optional The analytical derivative of the image model function fun. The function takes the same arguments as fun.

It returns a length-two tuple, with the following elements:
1. (because of performance considerations) the image model function, exactly as returned by fun
2. the partial derivatives of fun in each point r2 as a list of 1d ndarrays. The first element is the derivative with respect to r2, the following elements w.r.t. the custom shape parameters as defined in params. Hence, the number of elements in this list is len(params) + 1.
default : dict, optional Default parameter values. For instance dict(thickness=0.2)
continuous : boolean, optional Default True. Set this to False if \(f(|r|)\) is not continuous at \(r = 0\). In that case, all pixels closer than 1 pixel to the center will be ignored.

param_modedict, optional

For each parameter, define whether it should be optimized or be kept constant. This also allows for constraining parameters to be equal within each cluster or equal for all frames.

Each parameter can have one of the following values:

'var' : the parameter is allowed to vary for each feature independently
'const' : the parameter is not allowed to vary
'cluster' : the parameter is allowed to vary, but is equal within each cluster
'global' : the parameter is allowed to vary, but is equal for each feature
'frame' : Not yet implemented
'particle' : Not yet implemented

Default values for position coordinates and signal is 'var', for background 'cluster' and for all others 'const'. Background cannot vary within one cluster, as regions overlap.

param_valdict, optional

Default parameter values.

constraintstuple of dicts, optional

Provide constraints for the parameters that are optimized. Each constraint consists of a dictionary containing the following elements:

type : str Constraint type: ‘eq’ for equality, which means that the constraint function result is to be zero. ‘ineq’ for inequality, which means that the constraint function result is to be greater than zero.
fun : callable The function defining the constraint. The function is provided a 3d ndarray with on the axes (<cluster>, <feature>, <parameter>) parameters are (background, signal, <pos>, <size>, <other>).
args : sequence, optional Extra arguments to be passed to the function.
cluster_size : integer Size of the cluster to which the constraint applies

The parameter array that is presented to the constraint function is slightly different from the 2D array of per-feature parameters used in vect_from_params, in the sense that that the first axis (axis 0) is extra.

The 3D array of feature parameters that is presented to the constraint function is defined as follows:

Axis 0, the grouping axis, which mostly has a length of 1, but in the case that the features that are optimized at once belong to different clusters (e.g. 1 image with 10 dimers) the length of this axis is the number of clusters that are optimized together (in this example, 10).
Axis 1, the feature axis, contains the individual features. In the example of 10 dimers, this axis would have a size of 2.
Axis 2, the parameter axis, contains the parameters. The order is ['background', 'signal', <pos>, <size>, <extra>]

bounds: dict

Bounds on parameters, in the following forms:

Absolute bounds {'x': [low, high]}
Difference bounds, one-sided {'x_abs': max_diff}
Difference bounds, two-sided {'x_abs': [max_diff_below, max_diff_above]}
Relative bounds, one-sided {'x_rel': max_fraction_below}
Relative bounds, two-sided {'x_rel': [max_fraction_below, max_fraction_above]}

When the keyword pos is used, this will be distributed to all pos_columns (but direct values of each positions will have precedence) When the keyword size is used, this will be distributed to all sizes, in the case of anisotropic sizes (also, direct values have precedence)

For example, {'x': (2, 6), 'x_abs': (4, 6), 'x_rel': (1.5, 2.5) would limit the parameter 'x' between 2 and 6, between x-4 and x+6, and between x/1.5 and x*2.5. The narrowest bound is taken.

compute_errorboolean, optional

Requires numdifftools to be installed. Default False. This is an experimental and untested feature that estimates the error in the optimized parameters on a per-feature basis from the curvature (diagonal elements of the Hessian) of the objective function in the optimized point.

pos_columns: list of strings, optional

Column names that contain the position coordinates. Defaults to ['y', 'x'] or ['z', 'y', 'x'], if 'z' exists.

t_column: string, optional

Column name that denotes the frame index. Default 'frame'.

max_iter: int, optional

Max number of whole-pixel shifts in refine. Default 10.

max_shift: float, optional

Maximum satisfactory out-of-center distance. When the fitted gaussian is more out of center, do extra iteration. Default 1.

max_rms_devfloat, optional

Maximum root mean squared difference between the final fit and the (preprocessed) image, in units of the image maximum value. Default 1.

residual_factorfloat, optional

Factor with which the residual is multiplied, something internal inside SLSQP makes it work best with this set around 100000. (which is Default)

kwargsoptional

other arguments are passed directly to scipy.minimize. Defaults are dict(method='SLSQP', tol=1E-6, options=dict(maxiter=100, disp=False))

Returns:

DataFrame of refined coordinates. Added columns:

‘cluster’: the cluster id of the feature.
‘cluster_size’: the size of the cluster to which the feature belongs
‘cost’: root mean squared difference between the final fit and
the (preprocessed) image, in units of the cluster maximum value. If the optimization fails, no error is raised feature fields are unchanged, and this field becomes NaN.
(experimental) standard errors of variable parameters (‘x_std’, etc.) (only if compute_error is true)