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:

• ValueError – If the KymoTrack instances weren’t tracked on the same source kymograph.

• ValueError – If the KymoTrack instances provided in the list are not unique.

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

Raises:

ValueError – if method == "ols" and the source kymographs do not have the same line times or pixel sizes.

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.

• RuntimeWarning – if method == "cve" and the source kymographs do not have the same line times or pixel sizes. As a result, the localization variance and variance of the localization variance are not 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) → 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.

filter(*, minimum_length=1, minimum_duration=0)

Remove tracks shorter than specified criteria from the list.

Parameters:

• minimum_length (int, optional) – Minimum number of tracked points for the track to be accepted (default: 1).

• minimum_duration (seconds, optional) – Minimum duration in seconds for a track to be accepted (default: 0).

fit_binding_times(n_components, *, exclude_ambiguous_dwells=True, tol=None, max_iter=None, observed_minimum=None, discrete_model=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").

• observed_minimum (bool) – Use duration of shortest track as minimum observable time. This is a legacy mode that can lead to biases when performing global analysis on data with very few events per kymograph. This behavior is currently the default to preserve backward compatibility, but will be removed in the next major release. Set to False to specifically enable the proper behavior.

• discrete_model (bool, optional) – Take into account discretization when fitting dwell times. Prior to Pylake v1.2.0, dwell times were fitted using a continuous model. In reality, the observed dwell times are discretized by the time difference between successive frames. To take into account the temporal discretization of the data, specify discrete_model=True. Currently, this argument is set to False by default for backward compatibility, but in the next major version of Pylake (v2.0.0), it will default to True.

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

plot_fit(frame_idx, *, fit_kwargs=None, data_kwargs=None, show_track_index=True)

Plot the localization model fits for a particular kymograph frame.

Note that currently, this fit is only available for Gaussian refinement.

Parameters:

• frame_idx (int) – Index of the kymograph frame to plot.

• fit_kwargs (dict) – Dictionary containing arguments to be passed to the fit plot.

• data_kwargs (dict) – Dictionary containing arguments to be passed to the data plot.

• show_track_index (bool) – Display track index in the plot.

Raises:

• ValueError – If the group is empty.

• NotImplementedError – If this group has multiple kymographs associated with it.

• NotImplementedError – If localization was not performed using Gaussian localization.

• IndexError – If requesting a fit for a frame index out of bounds of the KymoTrack.

Examples

import lumicks.pylake as lk

tracks = lk.track_greedy(kymo, channel="red", pixel_threshold=5)
refined = lk.refine_tracks_gaussian(tracks, window=10, refine_missing_frames=True, overlap_strategy="multiple")

# Plot the localization fits for kymograph frame 5
refined.plot_fit(5)

# Using ipywidgets and jupyter, it is easy to make an interactive version of this plot.
import ipywidgets as widgets

plt.figure()
def plot_fit(frame):
    plt.cla()  # Clear the current axis
    refined.plot_fit(frame, show_track_index=True)

widgets.interact(plot_fit, frame=widgets.IntSlider(0, max=kymo.shape[1] - 1));

remove(track: 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, *, correct_origin=None)

Export kymograph tracks to a csv file.

Parameters:

• filename (str | os.PathLike) – 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.

• correct_origin (bool, optional) – Use the correct pixel origin when sampling from image. Kymotracks are defined with the origin of each image pixel defined at the center. Earlier versions of the method that samples photon counts around the track had a bug which assumed the origin at the edge of the pixel. Setting this flag to True produces the correct behavior. The default is set to None which reproduces the old behavior and results in a warning, while False reproduces the old behavior without a warning.