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. Note that these should be of integer type.

  • 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.

Raises

TypeError – If time indices are not of integer type.

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\). Note that for 1D confocal scans, we neglect the effect of motion blur (R=0).

  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”.

Raises

  • ValueError – if method == "cve", but the KymoTrack has fewer than 3 time intervals defined.

  • ValueError – if method == "cve", the source kymograph does not have a clearly defined motion blur constant, and a localization variance is supplied as an argument. As a result, the diffusion constant cannot be reliably calculated. In this case, do not provide a localization uncertainty.

  • NotImplementedError – if the tracked kymograph had disjoint time intervals (such as for a temporally downsampled kymograph).

Warns

RuntimeWarning – if method == "cve" and the source kymograph does not have a clearly defined motion blur constant. As a result, the localization variance and standard error for the diffusion constant will not be available. Estimates that are unavailable are returned as np.nan.

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.

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.

Raises

  • ValueError – If there are insufficient points to extrapolate a linear curve from (two points). This can be due to too few points being available, or n_estimate being smaller than two.

  • RuntimeError – If this line consists of fewer than two points, it cannot be extrapolated.

in_rect(rect, all_points=False)

Check whether points of this KymoTrack fall in the given rect.

Parameters

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

  • all_points (bool) – Require that all points fall inside the rectangle.

Returns

is_inside

Return type

bool

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 (np.ndarray) – array of lag times

  • msd (np.ndarray) – 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.