| TrackMeasures {celltrackR} | R Documentation |
Track Measures
Description
Statistics that can be used to quantify tracks. All of these functions take a single track as input and give a single number as output.
Usage
trackLength(x)
duration(x)
speed(x)
displacement(x, from = 1, to = nrow(x))
squareDisplacement(x, from = 1, to = nrow(x))
displacementVector(x)
maxDisplacement(x)
displacementRatio(x)
outreachRatio(x)
straightness(x)
overallAngle(x, from = 1, to = nrow(x), xdiff = diff(x), degrees = FALSE)
meanTurningAngle(x, degrees = FALSE)
overallDot(x, from = 1, to = nrow(x), xdiff = diff(x))
overallNormDot(x, from = 1, to = nrow(x), xdiff = diff(x))
asphericity(x)
hurstExponent(x)
fractalDimension(x)
Arguments
x |
a single input track; a matrix whose first column is time and whose remaining columns are a spatial coordinate. |
from |
index, or vector of indices, of the first row of the track. |
to |
index, or vector of indices, of last row of the track. |
xdiff |
row differences of x. |
degrees |
logical; should angles be returned in degrees rather than radians? |
Details
Some track measures consider only the first and last position (or steps) of a track,
and are most useful in conjunction with aggregate.tracks; for instance,
squareDisplacement combined with aggregate.tracks gives a mean
square displacement plot, and overallAngle combined with
aggregate.tracks gives a turning angle plot (see the examples for
aggregate.tracks). To speed up computation of these measures on
subtracks of the same track, the arguments from, to and
possibly xdiff are exploited by aggregate.tracks.
Value
trackLength sums up the distances between subsequent positsion; in other words,
it estimates the length of the underlying track by linear interpolation (usually
an underestimation). The estimation could be improved in some circumstances by using
interpolateTrack. The function returns a single, non-negative number.
duration returns the time elapsed between x's first and last
positions (a single, non-negative number).
speed simply divides trackLength by duration
displacement returns the Euclidean distance between the track endpoints
and squareDisplacement returns the squared Euclidean distance.
displacementVector returns the vector between the track endpoints. This
vector has an element (can be negative) for each (x,y,z) dimension of the coordinates
in the track.
maxDisplacement computes the maximal Euclidean distance of any position
on the track from the first position.
displacementRatio divides the displacement by the maxDisplacement;
outreachRatio divides the maxDisplacement by the trackLength
(Mokhtari et al, 2013). Both measures return
values between 0 and 1, where 1 means a perfectly straight track.
If the track has trackLength 0, then NaN is returned.
straightness divides the displacement by the trackLength.
This gives a number between 0 and 1, with 1 meaning a perfectly straight track.
If the track has trackLength 0, then NaN is returned.
asphericity is a different appraoch to measure straightness
(Mokhtari et al, 2013): it computes the asphericity of the set of positions on the
track _via_ the length of its principal components. Again this gives a number between 0
and 1, with higher values indicating straighter tracks.
Unlike straightness, however, asphericity ignores
back-and-forth motion of the object, so something that bounces between two positions
will have low straightness but high asphericity. We define the
asphericity of every track with two or fewer positions to be 1. For one-dimensional
tracks with one or more positions, NA is returned.
overallAngle Computes the angle (in radians) between the first and the last
segment of the given track. Angles are measured symmetrically, thus the return values
range from 0 to pi; for instance, both a 90 degrees left and right turns yield the
value pi/2. This function is useful to generate autocorrelation plots
(together with aggregate.tracks). Angles can also be returned in degrees,
in that case: set degrees = TRUE.
meanTurningAngle averages the overallAngle over all
adjacent segments of a given track; a low meanTurningAngle indicates high
persistence of orientation, whereas for an uncorrelated random walk we expect
90 degrees. Note that angle measurements will yield NA values for tracks
in which two subsequent positions are identical. By default returns angles in
radians; use degrees = TRUE to return angles in degrees instead.
overallDot computes the dot product between the first and the last
segment of the given track. This function is useful to generate autocovariance plots
(together with aggregate.tracks).
overallNormDot computes the dot product between the unit vectors along
the first and the last segment of the given track. This function is useful to
generate autocorrelation plots (together with
aggregate.tracks).
hurstExponent computes the corrected empirical Hurst exponent of the track.
This uses the function hurstexp from the 'pracma' package.
If the track has less than two positions, NA is returned.
fractalDimension estimates the fractal dimension of a track using the function
fd.estim.boxcount from the
'fractaldim' package. For self-affine processes in n dimensions,
fractal dimension and Hurst exponent
are related by the formula H=n+1-D.
For non-Brownian motion, however, this relationship
need not hold. Intuitively, while the Hurst exponent takes a global approach to the
track's properties, fractal dimension is a local approach to the track's properties
(Gneiting and Schlather, 2004).
References
Zeinab Mokhtari, Franziska Mech, Carolin Zitzmann, Mike Hasenberg, Matthias Gunzer and Marc Thilo Figge (2013), Automated Characterization and Parameter–Free Classification of Cell Tracks Based on Local Migration Behavior. PLoS ONE 8(12), e80808. doi:10.1371/journal.pone.0080808
Tillmann Gneiting and Martin Schlather (2004), Stochastic Models That Separate Fractal Dimension and the Hurst Effect. SIAM Review 46(2), 269–282. doi:10.1137/S0036144501394387
See Also
AngleAnalysis for methods to compute angles and distances
between pairs of tracks, or of tracks to a reference point, direction, or plane.
Examples
## show a turning angle plot with error bars for the T cell data.
with( (aggregate(BCells,overallDot,FUN="mean.se",na.rm=TRUE)),{
plot( mean ~ i, xlab="time step",
ylab="turning angle (rad)", type="l" )
segments( i, lower, y1=upper )
} )