KymoTrackGroup

lumicks.pylake.kymotracker.kymotrack.KymoTrackGroup

class KymoTrackGroup(kymo_tracks)

Tracks on a kymograph.

KymoTrackGroup instances are typically returned from tracking or refinement algorithms. They contain a number of KymoTrack instances.

Parameters

kymo_tracks (list of KymoTrack) – Kymograph tracks.

Raises

Examples

from lumicks import pylake

tracks = lk.track_greedy(kymo, channel="red", pixel_threshold=5)

tracks[1]  # Extract the second `KymoTrack` from the group.
tracks[-1]  # Extract the last `KymoTrack` from the group.
tracks[1:3]  # Extract a `KymoTrackGroup` with the second and third kymotrack in the group.

# You can also perform boolean array indexing. For example, one can extract a
# `KymoTrackGroup` containing all tracks with more than 3 points.
tracks[[len(track) > 3 for track in tracks]]

# Or index by a list or numpy array
tracks[[1, 3]]  # Extract the second and fourth track.
tracks[np.asarray([1, 3])]  # Same as above.
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).

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. If only one track is available, the standard error on the diffusion constant will also not be available. Estimates that are unavailable are returned as np.nan.

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()

Raises

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

  • RuntimeWarning – if some tracks were discarded because they were shorter than the specified min_length.

extend(other)

Extend this group with additional KymoTrack instances.

Parameters

other (KymoTrack or KymoTrackGroup) – Kymograph tracks to extend this group with.

Raises

  • TypeError – If the data to extend this group with isn’t a KymoTrack or a KymoTrackGroup

  • ValueError – If the KymoTrack instances that we want to extend this one with weren’t tracked on the same source kymograph.

  • ValueError – If any of the KymoTrack instaces we are trying to extend this group with are already part of this group.

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(track: lumicks.pylake.kymotracker.kymotrack.KymoTrack)

Remove a KymoTrack from the KymoTrackGroup

Parameters

track (KymoTrack) – track to remove from the group

remove_tracks_in_rect(rect, all_points=False)

Removes tracks that fall in a particular region.

Parameters

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

  • all_points (bool) – Only remove tracks that are completely inside the rectangle.

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.