Ecological trajectory analysis

Introduction

Package ecotraj is a package providing Ecological Trajectory Analysis (ETA), a framework to analyse temporal changes (i.e. dynamics) in ecological entities defined as trajectories on a chosen multivariate space.

ETA is related to the following publications:

Initial presentation of the Ecological Trajectory Analysis (ETA) framework (De Cáceres et al. 2019).
ETA extension of metrics and visualisation modes (Sturbois et al. 2021a).
ETA extension to cyclical trajectory data (Djeghri et al. 2026a).
Interpretation of trajectory relative movements (Djeghri et al. 2026b).
Application to a multivariate space defined by stable isotope data (Sturbois et al. 2021b).
Application to a multivariate space defined by elemental composition data (de la Casa et al. 2025).
Application of ETA framework for the assessment of ecological quality (Sturbois et al. 2023).

Package installation

Package ecotraj can be found at CRAN. In addition, the latest stable ecotraj R package can also be installed from GitHub as follows:

# remotes::install_github("emf-creaf/ecotraj")
install.packages("ecotraj", repos = c('https://emf-creaf.r-universe.dev', 'https://cloud.r-project.org'))

Documentation and training

The package comes with function documentation including examples.
Several articles explaining the different metrics of the framework and how to conduct them using package functions can be found here.
Presentation slides of a course on ecological trajectory analysis can be found here.

Package functions

The following lists the main package functions, grouped by analysis framework:

Functions for Ecological Trajectory Analysis (ETA)

Name	Short description
`defineTrajectories()`	Defines trajectory objects to be analyzed.
`subsetTrajectories()`	Subsets trajectories corresponding to selected set of sites or surveys from a dataset containing multiple trajectories.
`trajectoryLengths()`	Calculates lengths of directed segments and total path length of trajectories.
`trajectoryLengths2D()`	Calculates lengths of directed segments and total path lengths of trajectories from 2D coordinates given as input.
`trajectorySpeeds()`	Calculates speeds of directed segments and total path speed of trajectories.
`trajectorySpeeds2D()`	Calculates speeds of directed segments and total path speed of trajectories from 2D coordinates given as input.
`trajectoryAngles()`	Calculates the angle between consecutive pairs of directed segments or between segments of ordered triplets of points.
`trajectoryDirectionality()`	Assesses the level directionality of each trajectory.
`trajectoryAngles2D()`	Calculates the angle between consecutive pairs of directed segments or between segments of ordered triplets of points from 2D coordinates.
`trajectoryConvergence()`	Performs the Mann-Kendall trend test on (1) the distances between trajectories; (2) the distance between points of one trajectory to the other; or (3) the variance of states among trajectories.
`trajectoryCorrespondence()`	Performs a permutation test of pairwise dynamic correspondence between trajectories sensitive to trajectory shape and movement direction.
`trajectoryRMA()`	Tests and qualifies the relative movements of ecological trajectories.
`trajectoryInternalVariation()`	Assesses the internal variability within each trajectory.
`trajectoryDistances()`	Estimates distances between pairs of ecosystem trajectories.
`trajectoryShifts()`	Calculates trajectory shifts (i.e. advances and delays) between trajectories assumed to follow a similar path but with different speeds or time lags.
`trajectoryPlot()`	Draws trajectories in a 2D-plot corresponding to the input coordinates.
`trajectoryPCoA()`	Performs principal coordinates analysis and draws trajectories in the ordination scatterplot.
`trajectoryMetrics()`	Calculates several (whole path) metrics on trajectories.
`trajectoryWindowMetrics()`	Calculates several metrics on subtrajectories defined using moving windows.
`dynamicVariation()`	Assesses the amount of dynamic variation observed across trajectories and the relative contribution of each of them.
`interpolateTrajectories()`	Relocates trajectory ecological states to those corresponding to input times, via linear interpolation.
`smoothTrajectories()`	Performs multivariate smoothing on trajectory data using a Gaussian kernel.
`centerTrajectories()`	Shifts all trajectories to the center of the multivariate space and returns a modified distance matrix.
`averageTrajectories()`	Creates an “average” trajectory where the position of each observation is the average of the position of the corresponding observations of the input trajectories.

Functions specific for Cyclical Ecological Trajectory Analysis (CETA)

Name	Short description
`extractCycles()`	Extracts (i.e. subsets) cycles from cyclical trajectories.
`extractFixedDateTrajectories()`	Extracts fixed-date trajectories from cyclical trajectories.
`cycleShifts()`	Estimates cyclical shifts (i.e. advances or delays).
`cycleConvexity()`	Estimates the degree of convexity of cycles.
`cycleMetrics()`	Calculates several (whole path) metrics on cycles.
`cyclePCoA()`	Performs Principal Coordinates Analysis and draws cycles in the ordination scatter plot.
`fixedDateTrajectoryPCoA()`	Performs Principal Coordinates Analysis and draws fixed date trajectories in the ordination scatter plot.

Functions for Ecological Quality Assessment (EQA)

Name	Short description
`stateEnvelopeVariability()`	Assess the variability of a set of states taken as reference envelope.
`trajectoryEnvelopeVariability()`	Assess the variability of a set of trajectories taken as reference envelope.
`compareToStateEnvelope()`	Evaluate the ecological quality of stations/observations with respect to a set of states taken as reference envelope.
`compareToTrajectoryEnvelope()`	Evaluate the ecological quality of stations/observations with respect to a set of trajectories taken as reference envelope.

Related package

The R package ecoregime, by Martina Sánchez-Pinillos, implements the Ecological Dynamic Regimes (EDR) framework to characterize and compare groups of ecological trajectories in multidimensional spaces defined by ecosystem state variables.

References

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 89, e01350 (https://doi.org/10.1002/ecm.1350).
de la Casa J, Nogué S, De Cáceres M, Pla-Rabés S, Sardans J, Benavente M, Giralt S, Hernandez A, Raposeiro PM & Peñuelas J (2025) Understanding two millenia ecosystem perturbations on the Azores archipelago through elementome trajectories. Ecological Indicators, 176, 113630 (https://doi.org/10.1016/j.ecolind.2025.113630).
Djeghri N, Sturbois A, Hélaouët P, Geissmann Q, Rimmelin-Maury P, Boyé A, Gauthier O, De Cáceres M (2026a). Going round in cycles but going somewhere: Deciphering cyclical dynamics using Ecological Trajectory Analysis. Ecological Monographs, 96(2), e70058 (https://doi.org/10.1002/ecm.70058).
Djeghri N, Gauthier O, Sturbois A, Meiners SJ, Allen R, De Cáceres M (2026b) Uncovering the relative movements of ecological trajectories. Peer Community Journal 6: e54 (https://doi.org/10.24072/pcjournal.736).
Sturbois A, De Cáceres M, Sánchez-Pinillos M, Schaal G, Gauthier O, Le Mao P, Ponsero A, & Desroy N (2021a). Extending community trajectory analysis : New metrics and representation. Ecological Modelling, 440, 109400 (https://doi.org/10.1016/j.ecolmodel.2020.109400).
Sturbois A, Cucherousset J, De Cáceres M, Desroy N, Riera P, Carpentier A, Quillien N, Grall J, Espinasse B, Cherel Y & Schaal G (2021). Stable Isotope Trajectory Analysis (SITA) : A new approach to quantify and visualize dynamics in stable isotope studies. Ecological Monographs, 92, e1501 (https://doi.org/10.1002/ecm.1501).
Sturbois A, De Cáceres M, Bifolchi A, Bioret F, Boyé A, Gauthier O, Grall J, Grémare A, Labrune C, Robert A, Schaal G & Desroy N (2023). Ecological Quality Assessment: a general multivariate framework to report the quality of ecosystems and their dynamics with respect to reference conditions. Ecosphere 14, e4726 (https://doi.org/10.1002/ecs2.4726).