aggregate.tracks | R Documentation |
Computes a given measure on subtracks of a given track set, applies a summary statistic for each subtrack length, and returns the results in a convenient form. This important workhorse function facilitates many common motility analyses such as mean square displacement, turning angle, and autocorrelation plots.
## S3 method for class 'tracks' aggregate( x, measure, by = "subtracks", FUN = mean, subtrack.length = seq(1, (maxTrackLength(x) - 1)), max.overlap = max(subtrack.length), na.rm = FALSE, filter.subtracks = NULL, count.subtracks = FALSE, ... )
x |
the tracks object whose subtracks are to be considered.
If a single track is given, it will be coerced to a tracks object
using |
measure |
the measure that is to be computed on the subtracks. |
by |
a string that indicates how grouping is performed. Currently, two kinds of grouping are supported:
|
FUN |
a summary statistic to be computed on the measures of subtracks with the same length. Can be a function or a string. If a string is given, it is first matched to the following builtin values:
If the string is not equal to any of these, it is passed on to
|
subtrack.length |
an integer or a vector of integers defining which subtrack
lengths are considered. In particular, |
max.overlap |
an integer controlling what to do with overlapping subtracks.
A maximum overlap of |
na.rm |
logical. If |
filter.subtracks |
a function that can be supplied to exclude certain subtracks from an analysis. For instance, one may wish to compute angles only between steps of a certain minimum length (see Examples). |
count.subtracks |
logical. If |
... |
further arguments passed to or used by methods. |
For every number of segments i in the set defined by
subtrack.length
, all subtracks of any track in the input
tracks
object that consist of exactly i segments are
considered. The input measure
is applied to the subtracks individually,
and the statistic
is applied to the resulting values.
A data frame with one row for every i
specified by subtrack.length
. The first column contains the values
of i and the remaining columns contain the values of the summary statistic
of the measure values of tracks having exactly i segments.
Joost B. Beltman, Athanasius F.M. Maree and Rob. J. de Boer (2009), Analysing immune cell migration. Nature Reviews Immunology 9, 789–798. doi:10.1038/nri2638
## A mean square displacement plot with error bars. dat <- aggregate(TCells, squareDisplacement, FUN="mean.se") with( dat ,{ plot( mean ~ i, xlab="time step", ylab="mean square displacement", type="l" ) segments( i, lower, y1=upper ) } ) ## Note that the values at high i are often based on very few subtracks: msd <- aggregate( TCells, squareDisplacement, count.subtracks = TRUE ) tail( msd ) ## Compute a turning angle plot for the B cell data, taking only steps of at least ## 1 micrometer length into account check <- function(x) all( sapply( list(head(x,2),tail(x,2)), trackLength ) >= 1.0 ) plot( aggregate( BCells, overallAngle, subtrack.length=1:10, filter.subtracks=check )[,2], type='l' ) ## Compare 3 different variants of a mean displacement plot # 1. average over all subtracks plot( aggregate( TCells, displacement ), type='l' ) # 2. average over all non-overlapping subtracks lines( aggregate( TCells, displacement, max.overlap=0 ), col=2 ) # 3. average over all subtracks starting at 1st position lines( aggregate( TCells, displacement, by="prefixes" ), col=3 )
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.