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).
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).
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"}) –
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 theKymoTrack
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 asnp.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
- 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.
- 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
- sample_from_image(num_pixels, reduce=<function sum>, *, correct_origin=None)¶
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).
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.
- with_offset(time_offset, coordinate_offset)¶
Returns an offset version of the KymoTrack
- property coordinate_idx¶
Return spatial coordinates in units of pixels.
Coordinates are defined w.r.t. pixel centers (i.e. 0, 0 is the center of the first pixel).
- 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.