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 ofKymoTrack
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 asnp.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 asnp.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
References
- 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 ifmethod == "cve"
or 5 points ifmethod == "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 asnp.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
orKymoTrackGroup
) –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, 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 toscipy.minimize(method="L-BFGS-B")
.max_iter (int) – The maximum number of iterations to perform. This parameter is forwarded as the
maxiter
argument toscipy.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, specifydiscrete_model=True
. Currently, this argument is set toFalse
by default for backward compatibility, but in the next major version of Pylake (v2.0.0
), it will default toTrue
.
- 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 thebins
argument, the full position range is used to calculate the bin edges (this is equivalent to usingnp.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
- 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: 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, *, 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 toNone
which reproduces the old behavior and results in a warning, whileFalse
reproduces the old behavior without a warning.