trajectories: Community trajectory analysis

Description Usage Arguments Details Value Author(s) References See Also Examples

Description

Community trajectory analysis (CTA) is a framework to analyze community dynamics described as trajectories in a chosen space of community resemblance (De Cáceres et al. 2019). CTA takes trajectories as objects to be analyzed and compared geometrically. Given a distance matrix between community states, the set of functions for CTA are:

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
segmentDistances(d, sites, surveys = NULL,
  distance.type = "directed-segment", add = TRUE, verbose = FALSE)

trajectoryDistances(d, sites, surveys = NULL, distance.type = "DSPD",
  symmetrization = "mean", add = TRUE, verbose = FALSE)

trajectoryLengths(d, sites, surveys = NULL, verbose = FALSE)

trajectoryAngles(d, sites, surveys = NULL, all = FALSE, stats = TRUE,
  add = TRUE, verbose = FALSE)

trajectorySelection(d, sites, selection)

trajectoryPCoA(d, sites, surveys = NULL, selection = NULL,
  traj.colors = NULL, axes = c(1, 2), ...)

trajectoryPlot(x, sites, surveys = NULL, selection = NULL,
  traj.colors = NULL, axes = c(1, 2), ...)

trajectoryProjection(d, target, trajectory, tol = 1e-06, add = TRUE)

trajectoryConvergence(d, sites, surveys = NULL, symmetric = FALSE,
  add = TRUE, verbose = FALSE)

trajectoryDirectionality(d, sites, surveys = NULL, add = TRUE,
  verbose = FALSE)

centerTrajectories(d, sites, verbose = FALSE)

is.metric(d, tol = 1e-04)

Arguments

d

A symmetric matrix or an object of class dist containing the distance values between pairs of community states (see details).

sites

A vector indicating the site corresponding to each community state.

surveys

A vector indicating the survey corresponding to each community state (only necessary when surveys are not in order).

distance.type

The type of distance index to be calculated (Besse et al. 2016; De Cáceres et al. submitted). For segmentDistances the available indices are:

  • Hausdorff: Hausdorff distance between two segments.

  • directed-segment: Directed segment distance (default).

  • PPA: Perpendicular-parallel-angle distance.

whereas for trajectoryDistances the available indices are:

  • Hausdorff: Hausdorff distance between two trajectories.

  • SPD: Segment path distance.

  • DSPD: Directed segment path distance (default).

add

Flag to indicate that constant values should be added (local transformation) to correct triplets of distance values that do not fulfill the triangle inequality.

verbose

Provides console output informing about process (useful for large dataset).

symmetrization

Function used to obtain a symmetric distance, so that DSPD(T1,T2) = DSPD(T2,T1) (e.g., mean or min). If symmetrization = NULL then the symmetrization is not conducted and the output dissimilarity matrix is not symmetric.

all

A flag to indicate that angles are desired for all triangles (i.e. all pairs of segments) in the trajectory. If FALSE, angles are calculated for consecutive segments only.

stats

A flag to indicate that circular statistics are desired (mean, standard deviation and mean resultant length, i.e. rho)

selection

A character vector of sites, a numeric vector of site indices or logical vector of the same length as sites, indicating a subset of site trajectories to be selected.

traj.colors

A vector of colors (one per site). If selection != NULL the length of the color vector should be equal to the number of sites selected.

axes

The pair of principal coordinates to be plotted.

...

Additional parameters for function arrows.

x

A data.frame or matrix where rows are community states and columns are coordinates in an arbitrary space

target

An integer vector of the community states to be projected.

trajectory

An integer vector of the trajectory onto which target states are to be projected.

tol

Numerical tolerance value to determine that projection of a point lies within the trajectory.

symmetric

A logical flag to indicate a symmetric convergence comparison of trajectories.

Details

Details of calculations are given in De Cáceres et al (submitted). The input distance matrix d should ideally be metric. That is, all subsets of distance triplets should fulfill the triangle inequality (see function is.metric). All CTA functions that require metricity include a parameter 'add', which by default is TRUE, meaning that whenever the triangle inequality is broken the minimum constant required to fulfill it is added to the three distances. If such local (an hence, inconsistent across triplets) corrections are not desired, users should find another way modify d to achieve metricity, such as PCoA, metric MDS or non-metric MDS (see CTA vignette). If parameter 'add' is set to FALSE and problems of triangle inequality exist, CTA functions may provide missing values in some cases where they should not.

The resemblance between trajectories is done by adapting concepts and procedures used for the analysis of trajectories in space (i.e. movement data) (Besse et al. 2016).

Function trajectoryAngles calculates angles between consecutive segments (or between the segments corresponding to all ordered triplets) in degrees. For each pair of segments, the angle between the two is defined on the plane that contains the two segments, and measures the change in direction (in degrees) from one segment to the other. Angles are always positive, with zero values indicating segments that are in a straight line, and values equal to 180 degrees for segments that are in opposite directions.

Function centerTrajectories performs centering of trajectories using matrix algebra as explained in Anderson (2017).

Value

Function trajectoryDistances returns an object of class dist containing the distances between trajectories (if symmetrization = NULL then the object returned is of class matrix).

Function trajectorySegments returns a list with the following elements:

Function trajectoryLengths returns a data frame with the length of each segment on each trajectory and the total length of all trajectories. Function trajectoryPCoA returns the result of calling cmdscale.

Function trajectoryAngles returns a data frame with angle values on each trajectory. If stats=TRUE, then the mean, standard deviation and mean resultant length of those angles are also returned.

Function trajectoryPCoA returns the result of calling cmdscale.

Function trajectoryProjection returns a data frame with the following columns:

Function trajectoryConvergence returns a list with two elements:

Function trajectoryDirectionality returns a vector with directionality values (one per trajectory).

Function centerTrajectory returns an object of class dist.

Author(s)

Miquel De Cáceres, Forest Sciences Center of Catalonia

References

Besse, P., Guillouet, B., Loubes, J.-M. & François, R. (2016). Review and perspective for distance based trajectory clustering. IEEE Trans. Intell. Transp. Syst., 17, 3306–3317.

De Cáceres M, Coll L, Legendre P, Allen RB, Wiser SK, Fortin MJ, Condit R & Hubbell S. (2019). Trajectory analysis in community ecology. Ecological Monographs.

Anderson (2017). Permutational Multivariate Analysis of Variance (PERMANOVA). Wiley StatsRef: Statistics Reference Online. 1-15. Article ID: stat07841.

See Also

cmdscale

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
  #Description of sites and surveys
  sites = c(1,1,1,2,2,2)
  surveys=c(1,2,3,1,2,3)
  
  #Raw data table
  xy<-matrix(0, nrow=6, ncol=2)
  xy[2,2]<-1
  xy[3,2]<-2
  xy[4:6,1] <- 0.5
  xy[4:6,2] <- xy[1:3,2]
  xy[6,1]<-1
  
  #Distance matrix
  d = dist(xy)
  d
  
  trajectoryLengths(d, sites, surveys)
  trajectoryAngles(d, sites, surveys)
  segmentDistances(d, sites, surveys)$Dseg
  trajectoryDistances(d, sites, surveys, distance.type = "Hausdorff")
  trajectoryDistances(d, sites, surveys, distance.type = "DSPD")
  
  #Draw trajectories
  trajectoryPCoA(d, sites, traj.colors = c("black","red"), lwd = 2)
  
  
  #Should give the same results if surveys are not in order 
  #(here we switch surveys for site 2)
  temp = xy[5,]
  xy[5,] = xy[6,]
  xy[6,] = temp
  surveys[5] = 3
  surveys[6] = 2
  trajectoryLengths(dist(xy), sites, surveys)
  segmentDistances(dist(xy), sites, surveys)$Dseg
  trajectoryDistances(dist(xy), sites, surveys, distance.type = "Hausdorff")
  trajectoryDistances(dist(xy), sites, surveys, distance.type = "DSPD")
 

miquelcaceres/vegclust documentation built on May 29, 2019, 2:57 p.m.