aggregate.tracks {celltrackR}

Compute Summary Statistics of Subtracks

Description

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.

Usage

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

Arguments

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 interval.

• "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=1 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).

count.subtracks

logical. If TRUE, the returned dataframe contains an extra column ntracks showing the number of subtracks of each length. This is useful to keep track of since the returned value estimates for high i are often based on very few subtracks.

...

further arguments passed to or used by methods.

Details

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.

Value

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.

References

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

Examples

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