aggregate.tracks: Compute Summary Statistics of Subtracks
In MotilityLab: Quantitative Analysis of Motion

Description Usage Arguments Details Value References Examples

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

`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 `wrapTrack` (but note that this requires an explicit call `aggregate.tracks`).
`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: "subtracks" Apply `measure` to all subtracks according to the parameters `subtrack.length` and `max.overlap`. "prefixes" Apply `measure` to all prefixes (i.e., subtracks starting from a track's initial position) according to the parameter `subtrack.length`.
`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: "mean.sd" Outputs the mean and mean - sd as lower and mean + sd as upper bound "mean.se" Outputs the mean and mean - se as lower and mean + se as upper bound "mean.ci.95" Outputs the mean and upper and lower bound of a parametric 95 percent confidence intervall. "mean.ci.99" Outputs the mean and upper and lower bound of a parametric 95 percent confidence intervall. "iqr" Outputs the interquartile range, that is, the median, and the 25-percent-quartile as a lower and and the 75-percent-quartile as an upper bound If the string is not equal to any of these, it is passed on to `match.fun`.
`subtrack.length`	an integer or a vector of integers defining which subtrack lengths are considered. In particular, `subtrack.length=2` corresponds to a "step-based analysis" (Beltman et al, 2009).
`max.overlap`	an integer controlling what to do with overlapping subtracks. A maximum overlap of `max(subtrack.length)` will imply that all subtracks are considered. For a maximum overlap of 0, only non-overlapping subtracks are considered. A negative overlap can be used to ensure that only subtracks a certain distance apart are considered. In general, for non-Brownian motion there will be correlations between subsequent steps, such that a negative overlap may be necessary to get a proper error estimate.
`na.rm`	logical. If `TRUE`, then `NA`'s and `NaN`'s are removed prior to computing the summary statistic.
`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).
`...`	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 )
} )

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