KymoTrack

lumicks.pylake.kymotracker.kymotrack.KymoTrack

class KymoTrack(time_idx, localization, kymo, channel)

A tracked particle on a kymograph.

Parameters

  • time_idx (array_like) – Frame time indices.

  • localization (LocalizationModel or array_like) – LocalizationModel instance containing localization parameters or list of (sub)pixel coordinates to be converted to spatial position via calibration with pixel size.

  • kymo (Kymo) – Kymograph instance.

  • channel ({"red", "green", "blue"}) – Color channel to analyze

estimate_diffusion(method, max_lag=None, localization_variance=None, variance_of_localization_variance=None)

Estimate diffusion constant

There are three algorithms to determine diffusion constants:

  • CVE: Covariance based estimator. Works directly on the tracks.

  • OLS: Ordinary least-squares estimator based on Mean Squared Displacements (MSD).

  • GLS: Generalized least-squares estimator based on Mean Squared Displacements (MSD).

  1. Covariance based estimator (CVE)

The covariance-based diffusion estimator provides a simple unbiased estimator of diffusion. This estimator was introduced in the work of Vestergaard et al 5. The correction for missing data was introduced in 6. The CVE is unbiased and practically optimal when the signal-to-noise ratio (SNR) is bigger than 1. In this context, the SNR is defined as: \(\sqrt{D \Delta t} / \sigma\).

  1. MSD-based estimators (OLS, GLS)

The estimator for the MSD (\(\rho\)) is defined as:

\[\rho_n = \frac{1}{N-n} \sum_{i=1}^{N-n} \left(r_{i+n} - r_{i}\right)^2\]

In a diffusion problem, the MSD can be fitted to a linear curve.

\[ \begin{align}\begin{aligned}\textrm{intercept} =& 2 d (\sigma^2 - 2 R D dt)\\\textrm{slope} =& 2 d D dt\end{aligned}\end{align} \]

Here \(d\) is the dimensionality of the problem. \(D\) is the diffusion constant. \(R\) is a motion blur constant. \(dt\) is the time step and \(\sigma\) represents the dynamic localization error.

One aspect that is import to consider is that this estimator uses every data point multiple times. As a consequence the elements of rho_n are highly correlated. This means that including more points doesn’t necessarily make the estimates better and can actually make the estimate worse.

There are two ways around this. Either you determine an optimal number of points to use in the estimation procedure (ols) 3 or you take into account the covariances present in the mean squared difference estimates (gls) 4.

The standard error returned by this method is based on 4.

Note that this estimation procedure should only be used for pure diffusion in the absence of drift.

Parameters

  • method ({"cve", "ols", "gls"}) –

    • “cve” : Covariance based estimator 5. Optimal if SNR > 1.

    • ”ols” : Ordinary least squares 3. Determines optimal number of lags.

    • ”gls” : Generalized least squares 4. Takes into account covariance matrix (slower). Can only be used when track is equidistantly sampled.

  • max_lag (int (optional)) – Number of lags to include when using an MSD-based estimator. When omitted, the method will choose an appropriate number of lags to use. For the cve estimator this argument is ignored. When the method chosen is “ols” an optimal number of lags is estimated as determined by 3. When the method is set to “gls” all lags are included.

  • localization_variance (float (optional)) – Estimate of the localization variance. This value can be obtained from estimating an ensemble diffusion constant using cve. This parameter is only used when method=”cve”.

  • variance_of_localization_variance (float (optional)) – Estimate of the variance of the localization variance estimate. This value can be obtained from estimating an ensemble diffusion constant using cve. This parameter is only used when method=”cve”.

References

3(1,2,3)

Michalet, X., & Berglund, A. J. (2012). Optimal diffusion coefficient estimation in single-particle tracking. Physical Review E, 85(6), 061916.

4(1,2,3)

Bullerjahn, J. T., von Bülow, S., & Hummer, G. (2020). Optimal estimates of self-diffusion coefficients from molecular dynamics simulations. The Journal of Chemical Physics, 153(2), 024116.

5(1,2)

Vestergaard, C. L., Blainey, P. C., & Flyvbjerg, H. (2014). Optimal estimation of diffusion coefficients from single-particle trajectories. Physical Review E, 89(2), 022726.

6

Vestergaard, C. L. (2016). Optimizing experimental parameters for tracking of diffusing particles. Physical Review E, 94(2), 022401.

estimate_diffusion_ols(max_lag=None)

Perform an unweighted fit to the MSD estimates to obtain a diffusion constant

Deprecated since version 0.12.1: This method is replaced by KymoTrack.estimate_diffusion(method="ols") to allow more flexibility in the choice of algorithms and provide additional metadata.

extrapolate(forward, n_estimate, extrapolation_length)

This function linearly extrapolates a track segment towards positive time.

Parameters

  • forward (boolean) – extrapolate forward (True) or backward in time (False)

  • n_estimate (int) – Number of points to use for linear regression.

  • extrapolation_length (float) – How far to extrapolate.

in_rect(rect)

Check whether any point of this KymoTrack falls in the rect given in rect.

Parameters

rect (Tuple[Tuple[float, float], Tuple[float, float]]) – Coordinates should be given as ((min_time, min_coord), (max_time, max_coord)).

interpolate()

Interpolate KymoTrack to whole pixel values

msd(max_lag=None)

Estimate the Mean Square Displacement (MSD) for various time lags.

The estimator for the MSD (\(\rho\)) is defined as:

\[\rho_n = \frac{1}{N-n} \sum_{i=1}^{N-n} \left(r_{i+n} - r_{i}\right)^2\]

Note: This estimator leads to highly correlated estimates, which should not be treated as independent measurements. See 1 for more information.

Parameters

max_lag (int) – Maximum lag to include.

Returns

  • lag_time (array_like) – array of lag times

  • msd (array_like) – array of mean square distance estimates for the corresponding lag times

References

1

Michalet, X., & Berglund, A. J. (2012). Optimal diffusion coefficient estimation in single-particle tracking. Physical Review E, 85(6), 061916.

plot(*, show_outline=True, show_labels=True, axes=None, **kwargs)

A simple line plot to visualize the track coordinates.

Parameters

  • show_outline (bool) – Whether to show black outline around the track.

  • show_labels (bool) – Whether to add axes labels.

  • axes (matplotlib.axes.Axes, optional) – If supplied, the axes instance in which to plot.

  • **kwargs – Forwarded to matplotlib.pyplot.plot().

plot_msd(max_lag=None, **kwargs)

Plot Mean Squared Differences of this trace

The estimator for the MSD (\(\rho\)) is defined as:

\[\rho_n = \frac{1}{N-n} \sum_{i=1}^{N-n} \left(r_{i+n} - r_{i}\right)^2\]

Note: This estimator leads to highly correlated estimates, which should not be treated as independent measurements. See 2 for more information.

Parameters

  • max_lag (int, optional) – Maximum lag to include. When omitted, an optimal number of lags is chosen 2.

  • **kwargs – Forwarded to matplotlib.pyplot.plot().

References

2(1,2)

Michalet, X., & Berglund, A. J. (2012). Optimal diffusion coefficient estimation in single-particle tracking. Physical Review E, 85(6), 061916.

sample_from_image(num_pixels, reduce=<function sum>)

Sample from image using coordinates from this KymoTrack.

This function samples data from the image given in data based on the points in this KymoTrack. It samples from [time, position - num_pixels : position + num_pixels + 1] and then applies the function sum.

Parameters

  • num_pixels (int) – Number of pixels in either direction to include in the sample

  • reduce (callable) – Function evaluated on the sample. (Default: np.sum which produces sum of photon counts).

with_offset(time_offset, coordinate_offset)

Returns an offset version of the KymoTrack

property coordinate_idx

Return spatial coordinates in units of pixels.

property position

The tracked positional coordinates. The units depend on the spatial units of the tracked kymo.

property seconds

The tracked temporal coordinates in seconds.