angleToPoint {celltrackR}

Angle with a Reference Point

Description

Compute the angle between a track's overall displacement vector and the vector from it's first coordinate to a reference point. Useful to detect directed movement towards a point (see examples).

Usage

angleToPoint(x, p = c(1, 1, 1), from = 1, degrees = TRUE)

Arguments

x

a single input track; a matrix whose first column is time and whose remaining columns are a spatial coordinate.

p

numeric vector of coordinates of the reference point p to compute angles/distances to.

from

index, or vector of indices, of the first row of the track. If from is a vector, angles are returned for all steps starting at the indices in from.

degrees

logical; should angles be returned in degrees rather than radians? (default = TRUE).

Details

The average angle of steps to a reference point should be 90 degrees if there is no bias towards movement in the direction of the reference point. If there is such a bias, there should be an enrichment of smaller angles. The expected distribution without bias is a uniform distribution in 2D or a sine distribution in 3D (Beltman et al, 2009).

Value

A single angle.

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

See Also

distanceToPoint to compute the distance to the reference point, and AngleAnalysis for other methods to compute angles and distances.

Examples

## Get a distribution of step angles with a reference point
## Use bb to get the corner with highest x,y (,z) value
## The histogram is enriched for low angles, suggesting directed movement:
steps <- subtracks( Neutrophils, 1 )
bb <- boundingBox( Neutrophils )
hist( sapply( steps, angleToPoint, p = bb["max",-1] ) )

## The same does not hold for movement of T cells towards the point (0,0)
steps <- subtracks( TCells, 1 )
hist( sapply( steps, angleToPoint, p = c(0,0) ) )

## Plotting the angle versus the distance to the reference point can also be informative,
## especially when small angles are more frequent at lower distances.
angles <- sapply( steps, angleToPoint, p = bb["max",-1] )
distances <- sapply( steps, distanceToPoint, p = bb["max",-1] )
scatter.smooth( distances, angles )
abline( h = 90, col = "red" )