KymoTrackGroup

lumicks.pylake.kymotracker.kymotrack.KymoTrackGroup

class KymoTrackGroup(kymo_tracks)

Tracks on a kymograph.

ensemble_diffusion(method, *, max_lag=None)

Determine ensemble based diffusion estimates.

Determines ensemble based diffusion estimates for the entire group of KymoTracks. This method assumes that all tracks experience the same diffusion and computes an averaged diffusion estimate.

Parameters

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

    • “cve” : Covariance based estimator. Optimal if SNR > 1. Ensemble average is determined by determining the weighted average of the individual track estimates. The standard error is computed by determining the weighted average of the associated standard errors for each estimate (Equation 57 and 58 from Vestergaard 7). See KymoTrack.estimate_diffusion() for more detailed information and references.

    • ”ols” : Ordinary least squares. Determines the ensemble mean squared displacements for the entire KymoTrackGroup and estimates a diffusion constant for it. See KymoTrack.estimate_diffusion() for more detailed information and references.

  • max_lag (int) – Maximum number of lags to include when using the ordinary least squares method (OLS).

References

7

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

ensemble_msd(max_lag=None, min_count=2) → lumicks.pylake.kymotracker.detail.msd_estimation.EnsembleMSD

This method returns the weighted average of the Mean Squared Displacement (MSD) for all tracks in this group.

This method determines the MSDs per track and determines the weighted average of them. The intrinsic assumption made when computing this quantity is that all tracks are independent and all trajectories sample the same environment and undergo the same type of diffusion.

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\]

For a diffusion process \(\rho_n\) is gamma distributed. From the additivity of independent gamma distributions we know that for \(N_T\) tracks of equal length 1:

\[E[\rho^{ens}_n] = \rho_n\]

and

\[E[(\sigma^{ens})^2] = \frac{\sigma}{N_T}\]

In reality, the tracks will not have equal length, therefore the returned statistics are weighted by the number of samples that contributed to the estimate. If all the tracks were of equal length with no missing data points, the weighting will have no effect on the estimates.

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 number of lags to compute.

  • min_count (int) – If fewer than min_count tracks contribute to the MSD at a particular lag then that lag is omitted.

References

1(1,2)

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

estimate_diffusion(method, *args, min_length=None, **kwargs)

Estimate diffusion constant for each track in the group.

Calls KymoTrack.estimate_diffusion() for each track. See the documentation for that method for more detailed information and references.

Parameters

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

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

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

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

  • min_length (None or int (optional)) – Discards tracks shorter than a certain length from the analysis. If None (the default) tracks shorter than 3 points if method == "cve" or 5 points if method == "ols" or "gls" will be discarded.

  • **kwargs – forwarded to KymoTrack.estimate_diffusion()

fit_binding_times(n_components, *, exclude_ambiguous_dwells=True, tol=None, max_iter=None)

Fit the distribution of bound dwelltimes to an exponential (mixture) model.

Parameters

  • n_components (int) – Number of components in the model. Currently only values of {1, 2} are supported.

  • exclude_ambiguous_dwells (bool) – Determines whether to exclude dwelltimes which are not exactly determined. If True, tracks which start in the first frame or end in the last frame of the kymograph are not used in the analysis, since the exact start/stop times of the binding event are not definitively known.

  • tol (float) – The tolerance for optimization convergence. This parameter is forwarded as the ftol argument to scipy.minimize(method="L-BFGS-B").

  • max_iter (int) – The maximum number of iterations to perform. This parameter is forwarded as the maxiter argument to scipy.minimize(method="L-BFGS-B").

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

Plot the track coordinates for all tracks in the group.

Parameters

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

  • 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_binding_histogram(kind, bins=10, **kwargs)

Plot histogram of bound events.

Parameters

  • kind ({'binding', 'all'}) – Type of events to count. ‘binding’ counts only the first position of each track whereas ‘all’ counts positions of all time points in each track.

  • bins (int or sequence of scalars) – Definition of the histogram bins; passed to np.histogram(). When an integer is supplied to the bins argument, the full position range is used to calculate the bin edges (this is equivalent to using np.histogram(data, bins=n, range=(0, max_position))). If a sequence of scalars is provided, they directly define the edges of the bins.

  • **kwargs – Keyword arguments forwarded to plt.bar().

remove_lines_in_rect(rect)

Deprecated since version 0.13.0: This method will be removed in a future release. Use remove_tracks_in_rect() instead.

remove_tracks_in_rect(rect)

Removes tracks that fall in a particular region. Note that if any point on a track falls inside the selected region it will be removed.

Parameters

rect (array_like) – Array of 2D coordinates in time and space units (not pixels)

save(filename, delimiter=';', sampling_width=None)

Export kymograph tracks to a csv file.

Parameters

  • filename (str) – Filename to output kymograph tracks to.

  • delimiter (str) – Which delimiter to use in the csv file.

  • sampling_width (int or None) – When supplied, this will sample the source image around the kymograph track and export the summed intensity with the image. The value indicates the number of pixels in either direction to sum over.