Type: Package
Title: Ecological Trajectory Analysis
Version: 1.1.0
Date: 2025-05-05
Description: Analysis of temporal changes (i.e. dynamics) of ecological entities, defined as trajectories on a chosen multivariate space, by providing a set of trajectory metrics and visual representations [De Caceres et al. (2019) <doi:10.1002/ecm.1350>; and Sturbois et al. (2021) <doi:10.1016/j.ecolmodel.2020.109400>]. Includes functions to estimate metrics for individual trajectories (length, directionality, angles, ...) as well as metrics to relate pairs of trajectories (dissimilarity and convergence). Functions are also provided to estimate the ecological quality of ecosystem with respect to reference conditions [Sturbois et al. (2023) <doi:10.1002/ecs2.4726>].
Depends: R (≥ 3.5.0), Rcpp (≥ 0.12.12)
Imports: Kendall, MASS
LinkingTo: Rcpp
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
URL: https://emf-creaf.github.io/ecotraj/
LazyLoad: yes
Encoding: UTF-8
NeedsCompilation: yes
RoxygenNote: 7.3.2
Suggests: ape, vegclust, knitr, rmarkdown, RColorBrewer, smacof, vegan, ggplot2, hrbrthemes, reshape2, scales, tidyr, viridis, testthat (≥ 3.0.0)
LazyData: true
BugReports: https://github.com/emf-creaf/ecotraj/issues
Config/testthat/edition: 3
Packaged: 2025-05-05 12:54:38 UTC; miquel
Author: Miquel De Cáceres ORCID iD [aut, cre], Nicolas Djeghri ORCID iD [aut], Anthony Sturbois ORCID iD [aut], Javier De la Casa [ctb]
Maintainer: Miquel De Cáceres <miquelcaceres@gmail.com>
Repository: CRAN
Date/Publication: 2025-05-05 13:30:02 UTC

ecotraj: Ecological Trajectory Analysis

Description

Analysis of temporal changes (i.e. dynamics) of ecological entities, defined as trajectories on a chosen multivariate space

Author(s)

Maintainer: Miquel De Cáceres miquelcaceres@gmail.com ORCID

Authors:

Contributors:

References

De Caceres et al., 2019 (doi:10.1002/ecm.1350), Sturbois et al., 2021 (doi:10.1016/j.ecolmodel.2020.109400), Sturbois et al., 2023 (doi:10.1002/ecs2.4726).

See Also

Useful links:

Avoca permanent plot dataset

Description

Example dataset with data from 8 permanent forest plots located on slopes of a valley in the New Zealand Alps. The study area is mountainous and centered on the Craigieburn Range (Southern Alps), South Island, New Zealand. Forests plots are almost monospecific, being the mountain beech (Fuscospora cliffortioides) the main dominant tree species. Previously forests consisted of largely mature stands, but some of them were affected by different disturbances during the sampling period (1972-2009) which includes 9 surveys.

Format

Three data items are included:

avoca_strat

An object of class stratifiedvegdata (see function stratifyvegdata from package 'vegclust') with structural and compositional data.

avoca_sites

A vector identifying sampled sites of each element in avoca_strat.

avoca_surveys

A vector identifying surveys of each element in avoca_strat.

Source

New Zealand National Vegetation Survey (NVS) Databank (https://nvs.landcareresearch.co.nz/).

References

Allen, R. B., P. J. Bellingham, and S. K. Wiser. 1999. Immediate damage by an earthquake to a temperate montane forest. Ecology 80:708–714.

Harcombe, P. A., R. B. Allen, J. A. Wardle, and K. H. Platt. 1998. Spatial and temporal patterns in stand structure, biomass, growth and mortality in a monospecific Nothofagus solandri var. cliffortioides (Hook. f.) Poole forest in New Zealand. Journal of Sustainable Forestry 6:313–343.

Hurst, J. M., R. B. Allen, D. A. Coomes, and R. P. Duncan. 2011. Size-specific tree mortality varies with neighbourhood crowding and disturbance in a montane Nothofagus forest. PLoS ONE 6.

Trajectory definition

Description

Defines data structures for trajectory analysis

Usage

defineTrajectories(d, sites, surveys = NULL, times = NULL)

Arguments

d

A symmetric matrix or an object of class dist containing the distance values between pairs of ecological states..

sites

A character vector indicating the ecological entity (site, individual, community) corresponding to each ecological state (other types are converted to character).

surveys

An integer vector indicating the survey corresponding to each ecological state (only necessary when surveys are not in order).

times

A numeric vector indicating survey times (if missing, survey times are made equal to surveys).

Value

An object (list) of class trajectories with the following elements:

See Also

subsetTrajectories

Examples

#Description of entities (sites) and surveys
entities <- 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

d <- dist(xy)

# Defines trajectories
x <- defineTrajectories(d, entities, surveys)
x

Dynamic variation and variation decomposition

Description

Usage

dynamicVariation(x, ...)

variationDecomposition(x)

Arguments

x

An object of class trajectories (or its children subclasses fd.trajectories or cycles).

...

Additional params to be passed to function trajectoryDistances.

Details

Function variationDecomposition requires trajectories to be synchronous. The SS sum of temporal and interaction components correspond to the SS sum, across trajectories, of function trajectoryInternalVariation.

Value

See Also

defineTrajectories, is.synchronous, trajectoryDistances, trajectoryInternalVariation

Examples

#Description of entities and surveys
entities <- c("1","1","1","1","2","2","2","2","3","3","3","3")
surveys <- c(1,2,3,4,1,2,3,4,1,2,3,4)
  
#Raw data table
xy<-matrix(0, nrow=12, ncol=2)
xy[2,2]<-1
xy[3,2]<-2
xy[4,2]<-3
xy[5:6,2] <- xy[1:2,2]
xy[7,2]<-1.5
xy[8,2]<-2.0
xy[5:6,1] <- 0.25
xy[7,1]<-0.5
xy[8,1]<-1.0
xy[9:10,1] <- xy[5:6,1]+0.25
xy[11,1] <- 1.0
xy[12,1] <-1.5
xy[9:10,2] <- xy[5:6,2]
xy[11:12,2]<-c(1.25,1.0)

d <- dist(xy)

# Defines trajectories
x <- defineTrajectories(d, entities, surveys)

# Assessment of dynamic variation and individual trajectory contributions
dynamicVariation(x)

# Variation decomposition (entity, temporal and interaction) for synchronous 
# trajectories:
variationDecomposition(x)

# check the correspondence with internal variation
sum(variationDecomposition(x)[c("time", "interaction"),"ss"])
sum(trajectoryInternalVariation(x)$internal_ss)

furseals dataset

Description

This is a subset of a data sets from Kernaléguen et al. (2015).

Format

furseals is an object of class data.frame composed of 1414 observations and 8 variables.

ID_SITA

Fur seal ID used by Sturbois et al. (under review), from 1 to 47

ID

Fur seal ID used by Kernaléguen et al. (2015) in the initial data set.

Species

Fur seal species: the Antarctic fur seal Arctocephalus gazella or the subantarctic fur seal A. tropicalis.

Sexe

Fur seal gender, either 'Male' or 'Female'.

Time

Number of the whisker sections from 1 to 30.

Place

Breeding place: Crozet, Amsterdam or Kerguelen

d13C

delta 13C value

d15N

delta 15N value

Details

Briefly, fur seals the Antarctic fur seal Arctocephalus gazella and subantarctic fur seal A. tropicalis whisker SI values yield unique long-term information on individual behaviour which integrates the spatial, trophic and temporal dimensions of the ecological niche. The foraging strategies of this two species of sympatric fur seals were examined in the winter 2001/2002 at Crozet, Amsterdam and Kerguelen Islands (Southern Ocean) using the stable isotope values of serially sampled whiskers. The subset of the initial data set is composed of consecutive whisker sections (3 mm-long) starting from the proximal (facial) end, with the most recently synthesized tissue remaining under the skin. Only individuals (n = 47) with whiskers totalizing at least 30 sections were selected in the initail data, and only those 30 sections were selected.

Author(s)

Kernaléguen, L., Arnould, J.P.Y., Guinet, C., Cherel, Y.

References

Kernaléguen, L., Arnould, J.P.Y., Guinet, C., Cherel, Y., 2015. Determinants of individual foraging specialization inlarge marine vertebrates, the Antarctic and subantarctic fur seals. Journal of Animal Ecology 1081–1091.

Glenan dataset

Description

Maerl bed data set to illustrate Ecological Quality Assessment (EQA)

Format

Glenan is an object of class data.frame composed of 32 observations and 252 variables.

Abundance.x

Abundance (number of individuals) of each taxon x

Surveys

Indicates different Maerl bed surveys.

Treatment

Combinations of fishing dredges and pressure levels. 'CTRL' stands for control. Fishing dredges are:

  • (1) a clam dredge (CD), 70 to 90 kg, 1.5 m wide, 40 teeth of 11 cm each;

  • (2) a queen scallop dredge (QSD), 120 kg,1.8 m wide, with a blade;

  • (3) a king scallop dredge (KSD), 190 kg, 1.8 m wide, 18 teeth of 10 cm each every 9 cm.

Details

Experimental data set built by Tauran et al. (2020) to study the impact of fishing dredges and varying fishing pressures on maerl beds, in the bay of Brest (Brittany, France).

References

Tauran, A., Dubreuil, J., Guyonnet, B., Grall, J., 2020. Impact of fishing gears and fishing intensities on maerl beds: An experimental approach. Journal of Experimental Marine Biology and Ecology 533, 151472. https://doi.org/10.1016/j.jembe.2020.151472

See Also

referenceEnvelopes

Glomel vegetation dataset

Description

Vegetation data set to illustrate Ecological Quality Assessment (EQA)

Format

Glomel is an object of class data.frame composed of 23 observations and 46 variables.

ID

Station ID.

Ref

Logical flag to indicate stations used to define the reference envelope.

Complementary

Comments regarding the quality of the ecosystem.

...

Percent cover values (derived from Braun-Blanquet ordinal scale) for 43 species of vascular plants.

Details

The nature reserve of Landes et Marais de Glomel (Brittany, France) is composed of temperate Atlantic wet heaths whose reference state is commonly considered dominated by plant communities associated to acid, nutrient poor soils that are at least seasonally water logged and dominated by Erica tetralix and E. ciliaris. The data set consists of 23 rows and 46 columns. The first five stations (rows) were used to define the reference envelope, and the next 18 stations (rows) where those for which the conservation status was to be assessed.

Author(s)

Aline Bifolchi, Réserve Naturelle des landes et marais de Glomel

See Also

referenceEnvelopes

heatmapdata dataset

Description

Espinasse et al. (2020) tested the application of isoscapes modelled from satellite data to the description of secondary production in the Northeast pacific. The output model fits in a 0.25° x 0.25° spatial grid covering the region spanning from 46 to 62°N and from 195 to 235°E and supporting delta 13C and delta 15N isoscapes from 1998 to 2017.

Format

heatmapdata is an object of class dataframe composed of 9206 observations of 9 variables.

Latitude

Latitude coordinate of the station, in degrees

Longitude

Longitude coordinate of the station, in degrees

d13C

delta 13C modelled value

d15N

delta 15N modelled value

station

Station ID

Years

Period corresponding to the calculation of trajectory metrics

Angles

Angle alpha (i.e direction) in the stable isotope space

Lengths

Net change values (i.e direction) in the stable isotope space

Angles2

Angle alpha values (i.e direction) in the stable isotope space transformed for a potential use with function geom_spoke

Details

This data sets is composed of trajectory metrics calculated by Sturbois et al. (2021) for all stations within all inter-annual consecutive periods between 1998 and 2017 calculated from the whole data set of Espinasse et al. (2020) for a 1° x 1° spatial grid.

Author(s)

Espinasse, B., Hunt, B.P.V., Batten, S.D., Pakhomov, E.A.

References

Espinasse, B., Hunt, B.P.V., Batten, S.D., Pakhomov, E.A., 2020. Defining isoscapes in the Northeast Pacific as an index of ocean productivity. Global Ecol Biogeogr 29, 246–261.

See Also

isoscape

Metricity

Description

Checks whether the input dissimilarity matrix is metric (i.e. all triplets fulfill the triangle inequality).

Usage

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

Arguments

x

Either an object of class trajectories, a symmetric matrix or an object of class dist containing the distance values between pairs of ecological states.

tol

Tolerance value for metricity

Value

A boolean indicating metric property

Author(s)

Miquel De Cáceres, CREAF

Synchronicity in trajectory observations

Description

Checks whether trajectories are synchronous, meaning that observation times are equal

Usage

is.synchronous(x)

Arguments

x

An object of class trajectories (or its children subclasses fd.trajectories or cycles)

Value

A boolean indicating whether trajectories are synchronous

See Also

defineTrajectories

Examples

#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

#Synchronous trajectories
x1 <- defineTrajectories(dist(xy), sites, surveys)
is.synchronous(x1)

# Non synchronous trajectories
x2 <- defineTrajectories(dist(xy[1:5,]), sites[1:5], surveys[1:5])
is.synchronous(x2)

isoscape dataset

Description

This data sets is a subset from Espinasse et al. (2020).

Format

isoscape is an object of class dataframe composed of 978 observations of 6 variables.

Latitude

Latitude coordinate of the station, in degrees

Longitude

Longitude coordinate of the station, in degrees

d13C

delta 13C modelled value

d15N

delta 15N modelled value

station

station ID

Year

Year corresponding to modelled stable isotope values

Details

Briefly, Espinasse et al. (2020) tested the application of isoscapes modelled from satellite data to the description of secondary production in the Northeast pacific. The output model fits in a 0.25° x 0.25° spatial grid covering the region spanning from 46 to 62°N and from 195 to 235°E and supporting delta 13C and delta 15N isoscapes from 1998 to 2017. The subset is composed of modelled delta 13C and delta 15N values of a 1° x 1° spatial grid from the original modelled dataset for 2013 and 2015.

Author(s)

Espinasse, B., Hunt, B.P.V., Batten, S.D., Pakhomov, E.A.

References

Espinasse, B., Hunt, B.P.V., Batten, S.D., Pakhomov, E.A., 2020. Defining isoscapes in the Northeast Pacific as an index of ocean productivity. Global Ecol Biogeogr 29, 246–261.

See Also

heatmapdata

North Sea zooplankton dataset

Description

A multi-annual (1958-2021), monthly resolved dataset of zooplankton community composition in the Northern and Southern North Sea used to illustrate Cyclical Ecological Trajectory Analysis (CETA)

Format

northseaZoo is an object of class list composed of 3 objects:

Hellinger

a data.frame containing Hellinger-transformed zooplankton taxa abundances.

times

a vector indicating the date (in year) associated to each line in Hellinger.

sites

a vector indicating the site ("NNS" = Northern North Sea, "SNS" = Southern North Sea) associated to each line in Hellinger.

Details

The data describes the zooplankton community in the North Sea sampled by the Continuous Plankton Recorder (CPR) survey. The CPR survey operates through towing of CPR samplers across commercial routes of merchant ships (plankton silk mesh = 270 microm, sampling depth = 5-10 m). When brought back to the laboratory, plankton is counted and identified taxonomically following standardized protocols. The raw data provided by the survey (doi:10.17031/66f12be296d70). was reformated into two monthly-resolved time series of the commonest zooplankton taxa in the Northern North Sea ("NNS") and the Southern North Sea ("SNS"). During data processing, a smoothing was performed by taking a rolling average (for each month, 5 values were averaged: a 3 months window + the corresponding month of the previous and next years). The abundances were finally Hellinger-transformed, making them amenable to ecological diversity study.

Author(s)

Nicolas Djeghri, Université de Bretagne Occidentale, France

Pierre Hélaouët and CPR survey staff, Marine Biological Association, United Kingdom

See Also

trajectoryCyclical

pike dataset

Description

This data sets comes from Cucherousset et al. (2013).

Format

pike is an object of class dataframe composed of 58 observations of 10 variables.

trophic_status_initial

Initial trophic status at release

ID

ID used for each individual by Cucherousset et al. (2013)

Time

Time of the stable isotope measurement: 1 (Release) or 2 (Departure)

Time_L

Time of the stable isotope measurement as string, either 'Release' or 'Departure'

Date

Date of release (common for all individuals) or recapture (variable dependind of the date of departure)

Size_mm

Size (length) of juvenile pike, in mm

d13C

delta 13C values

d15N

delta 15N values

Residence_time

Number of days between the release and the recapture

Trophic_status_final

Trophic status at the end of the study

Details

Briefly, Cucherousset et al. (2013) released 192 individually tagged, hatchery-raised, juvenile pike (Esox lucius L.) with variable initial trophic position (fin delta 13C/delta 15N values). Based on delta values, individuals were classified into zooplanktivorous (delta 15N < 10 ‰) and piscivorous (delta 15N > 10 ‰) as cannibalism is commonly observed in this species. Individuals were released in a temporarily flooded grassland where pike eggs usually hatch of the Brière marsh (France) to identify the determinants of juvenile natal departure. The release site was connected through a unique point to an adjacent pond used as a nursery habitat. Fish were continuously recaptured when migrating from flooded grassland to adjacent pond. Recaptured individuals (n = 29) were anaesthetized, checked for tags, measured for fork length, fin-clipped to quantify changes in delta 13C and delta 15N values, and released.

Author(s)

Cucherousset, J., Paillisson, J.-M., Roussel, J.-M.

References

Cucherousset, J., Paillisson, J.-M., Roussel, J.-M., 2013. Natal departure timing from spatially varying environments is dependent of individual ontogenetic status. Naturwissenschaften 100, 761–768.

Ecological quality assessment

Description

Functions to assess the variability of ecological reference envelopes and to assess the ecological quality of target stations/observations with respect to reference envelopes (Sturbois et al., under review).

Usage

trajectoryEnvelopeVariability(
  d,
  sites,
  surveys = NULL,
  envelope = NULL,
  nboot.ci = NULL,
  alpha.ci = 0.05,
  ...
)

stateEnvelopeVariability(d, envelope = NULL, nboot.ci = NULL, alpha.ci = 0.05)

compareToTrajectoryEnvelope(
  d,
  sites,
  envelope,
  surveys = NULL,
  m = 1.5,
  comparison_target = "trajectories",
  distances_to_envelope = FALSE,
  distance_percentiles = FALSE,
  ...
)

compareToStateEnvelope(
  d,
  envelope,
  m = 1.5,
  nboot.ci = NULL,
  alpha.ci = 0.05,
  distances_to_envelope = FALSE,
  distance_percentiles = FALSE,
  ...
)

Arguments

d

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

sites

A vector indicating the site corresponding to each ecological state.

surveys

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

envelope

A vector indicating the set of sites that conform the reference envelope (other sites will be compared to the envelope)

nboot.ci

Number of bootstrap samples for confidence intervals. If nboot.ci = NULL then confidence intervals are not estimated.

alpha.ci

Error in confidence intervals.

...

Additional parameters for function trajectoryDistances

m

Fuzziness exponent for quality value assessment

comparison_target

String indicating the component to be compared to the reference envelope. Either 'trajectories' (to compare complete trajectories) or 'states' (to compare individual trajectory states).

distances_to_envelope

Flag to indicate that distances to envelope should be included in the result

distance_percentiles

Flag to include the percentage of distances to the envelope (among sites corresponding to the reference) that are smaller than that of the site.

Details

Functions stateEnvelopeVariability and trajectoryEnvelopeVariability are used to assess the variability of reference envelopes. Functions compareToStateEnvelope and compareToTrajectoryEnvelope are used to evaluate the ecological quality of stations/observations with respect to a predefined reference envelope.

Value

Author(s)

Miquel De Cáceres, CREAF

Anthony Sturbois, Vivarmor nature, Réserve Naturelle nationale de la Baie de Saint-Brieuc

References

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.

See Also

trajectoryMetrics, glomel

Examples

data(glomel)
 
# Extract compositional data matrix
glomel_comp <- as.matrix(glomel[,!(names(glomel) %in% c("ID", "Ref", "Complementary"))])
rownames(glomel_comp) <- glomel$ID
 
# Calculate Bray-Curtis distance matrix 
glomel_bc <- vegan::vegdist(glomel_comp, method = "bray")
 
# Define reference envelope (5 stations) by observation ID
glomel_env <- glomel$ID[glomel$Ref]
 
# Assess quality with respect to reference envelope
compareToStateEnvelope(glomel_bc, glomel_env)

Trajectory subsetting

Description

Subsets data structures for trajectory analysis

Usage

subsetTrajectories(
  x,
  site_selection = NULL,
  subtrajectory_selection = NULL,
  survey_selection = NULL
)

Arguments

x

An object of class trajectories (or its children subclasses fd.trajectories or cycles)

site_selection

A character vector indicating the subset of entity (site) trajectories to be selected (if NULL, all sites are included).

subtrajectory_selection

A character vector indicating the subset of cycles or fixed date trajectories to be selected (only used when x is of class fd.trajectories or cycles).

survey_selection

An integer vector indicating the subset of surveys to be included (if NULL, all surveys are included).

Details

When using function subsetTrajectories on cycles or fixed-date trajectories then the parameter site_selection applies to sites (hence allows selecting multiple cycles or fixed-date trajectories). Specific cycles or fixed-date trajectories can be selected using trajectory_selection.

Value

An object (list) of class trajectories (or its children subclasses fd.trajectories or cycles), depending on the input.

See Also

defineTrajectories, trajectoryCyclical

Examples

#Description of entities (sites) and surveys
entities <- 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

d <- dist(xy)

# Defines trajectories
x <- defineTrajectories(d, entities, surveys)
x

# Extracts (subset) second trajectory
x_2 <- subsetTrajectories(x, "2")
x_2

Trajectory comparison

Description

Functions to compare pairs of trajectories or trajectory segments.

Usage

segmentDistances(x, distance.type = "directed-segment", add = TRUE)

trajectoryDistances(
  x,
  distance.type = "DSPD",
  symmetrization = "mean",
  add = TRUE
)

trajectoryConvergence(x, type = "pairwise.asymmetric", add = TRUE)

trajectoryShifts(x, add = TRUE)

Arguments

x

An object of class trajectories.

distance.type

The type of distance index to be calculated (see section Details).

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.

symmetrization

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

type

A string indicating the convergence test, either "pairwise.asymmetric", "pairwise.symmetric" or "multiple" (see details).

Details

Ecological Trajectory Analysis (ETA) is a framework to analyze dynamics of ecological entities described as trajectories in a chosen space of multivariate resemblance (De Cáceres et al. 2019). ETA takes trajectories as objects to be analyzed and compared geometrically.

The input distance matrix d should ideally be metric. That is, all subsets of distance triplets should fulfill the triangle inequality (see utility function is.metric). All ETA 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 vignette 'Introduction to Ecological Trajectory Analysis'). If parameter 'add' is set to FALSE and problems of triangle inequality exist, ETA 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).

Parameter distance.type is the type of distance index to be calculated which for function segmentDistances has the following options (Besse et al. 2016, De Cáceres et al. 2019:

In the case of function trajectoryDistances the following values are possible (De Cáceres et al. 2019):

Function trajectoryConvergence is used to study convergence/divergence between trajectories. There are three possible tests, the first two concerning pairwise comparisons between trajectories.

  1. If type = "pairwise.asymmetric" then all pairwise comparisons are considered and the test is asymmetric, meaning that we test for trajectory A approaching trajectory B along time. This test uses distances of orthogonal projections (i.e. rejections) of states of one trajectory onto the other.

  2. If type = "pairwise.symmetric" then all pairwise comparisons are considered but we test whether the two trajectories become closer along surveys. This test requires the same number of surveys for all trajectories and uses the sequence of distances between states of the two trajectories corresponding to the same survey.

  3. If type = "multiple" then the function performs a single test of convergence among all trajectories. This test needs trajectories to be synchronous. In this case, the test uses the sequence of variability between states corresponding to the same time.

In all cases, a Mann-Kendall test (see MannKendall) is used to determine if the sequence of values is monotonously increasing or decreasing.

Function trajectoryShifts is intended to be used to compare trajectories that are assumed to follow a similar pathway. The function evaluates shifts (advances or delays) due to different trajectory speeds or the existence of time lags between them. This is done using calls to trajectoryProjection. Whenever the projection of a given target state on the reference trajectory does not exist the shift cannot be evaluated (missing values are returned).

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 segmentDistances list with the following elements:

Function trajectoryConvergence returns a list with two elements:

Function trajectoryShifts returns an object of class data.frame describing trajectory shifts (i.e. advances and delays). The columns of the data.frame are:

Author(s)

Miquel De Cáceres, CREAF

Nicolas Djeghri, UBO

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 89, e01350.

See Also

trajectoryMetrics, trajectoryPlot, transformTrajectories, trajectoryProjection, MannKendall

Examples

#Description of entities (sites) and surveys
entities <- c("1","1","1","1","2","2","2","2","3","3","3","3")
surveys <- c(1,2,3,4,1,2,3,4,1,2,3,4)
  
#Raw data table
xy<-matrix(0, nrow=12, ncol=2)
xy[2,2]<-1
xy[3,2]<-2
xy[4,2]<-3
xy[5:6,2] <- xy[1:2,2]
xy[7,2]<-1.5
xy[8,2]<-2.0
xy[5:6,1] <- 0.25
xy[7,1]<-0.5
xy[8,1]<-1.0
xy[9:10,1] <- xy[5:6,1]+0.25
xy[11,1] <- 1.0
xy[12,1] <-1.5
xy[9:10,2] <- xy[5:6,2]
xy[11:12,2]<-c(1.25,1.0)
  
#Draw trajectories
trajectoryPlot(xy, entities, surveys,  
               traj.colors = c("black","red", "blue"), lwd = 2)

#Distance matrix
d <- dist(xy)
d
  
#Trajectory data
x <- defineTrajectories(d, entities, surveys)

#Distances between trajectory segments
segmentDistances(x, distance.type = "Hausdorff")
segmentDistances(x, distance.type = "directed-segment")

#Distances between trajectories
trajectoryDistances(x, distance.type = "Hausdorff")
trajectoryDistances(x, distance.type = "DSPD")
  
#Trajectory convergence/divergence
trajectoryConvergence(x)

#### Example of trajectory shifts
#Description of entities (sites) and surveys
entities2 <- c("1","1","1","1","2","2","2","2","3","3","3","3")
times2 <- c(1,2,3,4,1,2,3,4,1,2,3,4)
  
#Raw data table
xy2<-matrix(0, nrow=12, ncol=2)
xy2[2,2]<-1
xy2[3,2]<-2
xy2[4,2]<-3
xy2[5:8,1] <- 0.25
xy2[5:8,2] <- xy2[1:4,2] + 0.5 # States are all shifted with respect to site "1"
xy2[9:12,1] <- 0.5
xy2[9:12,2] <- xy2[1:4,2]*1.25  # 1.25 times faster than site "1"
  
#Draw trajectories
trajectoryPlot(xy2, entities2,  
               traj.colors = c("black","red", "blue"), lwd = 2)

#Trajectory data
x2 <- defineTrajectories(dist(xy2), entities2, times = times2)

#Check that the third trajectory is faster
trajectorySpeeds(x2)

#Trajectory shifts
trajectoryShifts(x2)

Functions for Cyclical Ecological Trajectory Analysis

Description

The Cyclical extension of Ecological Trajectory Analysis (CETA) aims at allowing ETA to describe ecological trajectories presenting cyclical dynamics such as seasonal or day/night cycles. We call such trajectories "cyclical". CETA operates by subdividing cyclical trajectories into two types of sub-trajectories of interest: cycles and fixed-date trajectories.

We recommend reading the vignette on CETA prior to use it.The CETA functions provided here achieve one of two goals:

  1. Reformatting data to analyze either cycles or fixed-date trajectories. The reformatted data can then be fed into existing ETA functions to obtain desired metrics (although special care need to be taken with cycles, see details).

  2. Providing new metrics relevant to cycles complementing other ETA functions.

Usage

extractCycles(
  x,
  cycleDuration,
  dates = NULL,
  startdate = NA,
  externalBoundary = "end",
  minEcolStates = 3
)

extractFixedDateTrajectories(
  x,
  cycleDuration,
  dates = NULL,
  fixedDate = NULL,
  namesFixedDate = NULL,
  minEcolStates = 2
)

cycleConvexity(
  x,
  cycleDuration,
  dates = NULL,
  startdate = NA,
  externalBoundary = "end",
  minEcolStates = 3,
  add = TRUE
)

cycleShifts(
  x,
  cycleDuration,
  dates = NULL,
  datesCS = NULL,
  centering = TRUE,
  minEcolStates = 3,
  add = TRUE
)

cycleMetrics(
  x,
  cycleDuration,
  dates = NULL,
  startdate = NA,
  externalBoundary = "end",
  minEcolStates = 3,
  add = TRUE
)

Arguments

x

An object of class trajectories describing a cyclical trajectory.

cycleDuration

A value indicating the duration of a cycle. Must be in the same units as times.

dates

An optional vector indicating the dates (< cycleDuration) corresponding to each ecosystem state. Must be in the same units as times. Defaults to times modulo cycleDuration (see details).

startdate

An optional value indicating at which date the cycles must begin. Must be in the same units as times. Defaults to min(dates).

externalBoundary

An optional string, either "end" or "start", indicating whether the start or end of the cycles must be considered "external". Defaults to "end".

minEcolStates

An optional integer indicating the minimum number of ecological states to return a fixed-date trajectory. Fixed-date trajectories comprising less ecological states than minEcolStates are discarded and do not appear in the output of the function. Defaults to 2.

fixedDate

An optional vector of dates for which fixed-date trajectories must be computed. Defaults to unique(dates), resulting in returning all possible fixed-date trajectories.

namesFixedDate

An optional vector of names associated to each fixedDate. Defaults to round(fixedDate,2).

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.

datesCS

An optional vector indicating the dates for which a cyclical shift must be computed. Default to unique(dates) resulting in the computation of all possible cyclical shifts.

centering

An optional boolean. Should the cycles be centered before computing cyclical shifts? Defaults to TRUE.

Details

CETA functions:

CETA is a little more time-explicit than the rest of ETA. Hence the parameter times is needed to initiate the CETA approach (classical ETA functions can work from surveys which is only ordinal). CETA also distinguishes between times and dates. Times represent linear time whereas dates represent circular time (e.g. the month of year). Dates are circular variables, coming back to zero when reaching their maximum value cycleDuration corresponding to the duration of a cycle. In CETA, dates are by default assumed to be times modulo cycleDuration. This should fit many applications but if this is not the case (i.e. if there is an offset between times and dates), dates can be specified. dates however need to remain compatible with times and cycleDuration (i.e. (times modulo cycleDuration) - (dates modulo cycleDuration) needs to be a constant).

IMPORTANT: Cycles within CETA comprises both "internal" and "external" ecological states (see the output of function extractCycles). This distinction is a solution to what we call the "December-to-January segment problem". Taking the example of a monthly resolved multi-annual time series, a way to make cycles would be to take the set of ecological states representing months from January to December of each year. However, this omits the segment linking December of year Y to January of year Y+1. However, including this segments means having two January months in the same cycle. The proposed solution in CETA (in the case of this specific example) is to set the January month of year Y+1 as "external". "external" ecological states need a specific handling for some operation in ETA, namely:

As a general rule the outputs of extractCycles should be used as inputs in other, non-CETA function (e.g. trajectoryDistances). There is three important exceptions to that rule: the functions cycleConvexity, cycleShifts and cycleMetrics. Instead, the inputs of these three functions should parallel the inputs of extractCycles in a given analysis. For cycleConvexity, this is because convexity uses angles obtained from the whole cyclical trajectory, and not only the cycles. For cycleShifts, this is because cyclical shifts are not obtained with respect to a particular set of cycles. For cycleMetrics, this is because it calls cycleConvexity. The function instead compute the most adapted set of cycles to obtain the metric.

Note: Function cycleShifts is computation intensive for large data sets, it may not execute immediately.

Further information and detailed examples of the use of CETA functions can be found in the associated vignette.

Value

Function extractCycles returns the base information needed to describe cycles. Its outputs are meant to be used as input for other ETA functions. Importantly, within cycles, ecological states can be considered "internal" or "external". Some operations and metrics within ETA use all ecological states whereas others use only "internal" ones (see details). Function extractCycles returns an object of class cycles containing:

Function extractFixedDateTrajectories returns the base information needed to describe fixed-date trajectories. Its outputs are meant to be used as inputs for other ETA functions in order to obtain desired metrics. Function extractFixedDateTrajectories returns an object of class fd.trajectories containing:

Function cycleConvexity returns the a vector containing values between 0 and 1 describing the convexity of cycles. Importantly, outputs of extractCycles should not be used as inputs for cycleConvexity (see details).

Function cycleShifts returns an object of class data.frame describing cyclical shifts (i.e. advances and delays). Importantly, outputs of extractCycles should not be used as inputs for cycleShifts (see details). The columns of the data.frame are:

Function cycleMetrics returns a data frame where rows are cycles and columns are different cycle metrics.

Author(s)

Nicolas Djeghri, UBO

Miquel De Cáceres, CREAF

References

Djeghri et al. (in preparation) Going round in cycles, but going somewhere: Ecological Trajectory Analysis as a tool to decipher seasonality and other cyclical dynamics.

See Also

trajectoryCyclicalPlots, trajectoryMetrics, trajectoryComparison

Examples

#First build a toy dataset with:
#The sampling times of the time series
timesToy <- 0:30 

#The duration of the cycles (i.e. the periodicity of the time series)
cycleDurationToy <- 10 

#The sites sampled (only one named "A")
sitesToy <- rep(c("A"),length(timesToy)) 

#And prepare a trend term
trend <- 0.05

#Build cyclical data (note that we apply the trend only to x):
x <- sin((timesToy*2*pi)/cycleDurationToy)+trend*timesToy
y <- cos((timesToy*2*pi)/cycleDurationToy)
matToy <- cbind(x,y)

#And express it as distances:
dToy <- dist(matToy)

#Make it an object of class trajectory:
cyclicalTrajToy <- defineTrajectories(d = dToy,
                                      sites = sitesToy,
                                      times = timesToy)

#At this stage, cycles and / or fixed date trajectories are not isolated.
#This done with the two CETA "extract" functions:
cyclesToy <- extractCycles(x = cyclicalTrajToy,
                           cycleDuration = cycleDurationToy)
fdTrajToy <- extractFixedDateTrajectories(x = cyclicalTrajToy,
                                          cycleDuration = cycleDurationToy)

#The output of these functions can be used as input
#for other ETA functions to get metrics of interest
#such as trajectory length:
trajectoryLengths(x = cyclesToy)
trajectoryLengths(x = fdTrajToy)

#or distances between trajectories:
trajectoryDistances(x = cyclesToy)
trajectoryDistances(x = fdTrajToy)

#In addition CETA adds two additional specific metrics.
#that require the same inputs as function extractCycles():
cycleConvexity(x = cyclicalTrajToy,
               cycleDuration = cycleDurationToy)
#The NA with the first cycle, is expected:
#Cycle convexity cannot be computed right at the boundary of the time series
cycleShifts(x = cyclicalTrajToy,
            cycleDuration = cycleDurationToy)
#Note that because our cycles are perfectly regular here, the cyclicalShift
#computed are all 0 (or close because of R's computing approximations)

#Subsetting cycles and fixed date trajectories:
subsetTrajectories(cyclesToy,
                   subtrajectory_selection = "A_C1") 
subsetTrajectories(fdTrajToy,
                   subtrajectory_selection = c("A_fdT_2","A_fdT_4"))
                
#General metrics describing the geometry of cycles:
cycleMetrics(x = cyclicalTrajToy,
             cycleDuration = cycleDurationToy)

Cyclical trajectory plots

Description

Plotting functions for Cyclical Ecological Trajectory Analysis:

Usage

cyclePCoA(
  x,
  centered = FALSE,
  sites.colors = NULL,
  cycles.colors = NULL,
  print.names = FALSE,
  print.init.points = FALSE,
  cex.init.points = 1,
  axes = c(1, 2),
  ...
)

fixedDateTrajectoryPCoA(
  x,
  fixedDates.colors = NULL,
  sites.lty = NULL,
  print.names = FALSE,
  add.cyclicalTrajectory = TRUE,
  axes = c(1, 2),
  ...
)

Arguments

x

The full output of function extractCycles or extractFixedDateTrajectories as appropriate, an object of class cycles or fd.trajectories.

centered

Boolean. Have the cycles been centered? Default to FALSE.

sites.colors

The colors applied to the different sites. The cycles will be distinguished (old to recent) by increasingly lighter tones of the provided colors.

cycles.colors

The colors applied to the different cycles. Not compatible with sites.colors.

print.names

A boolean flag to indicate whether the names of cycles or fixed-date trajectories should be printed.

print.init.points

A boolean flag to indicate whether an initial point at the start of cycles should be printed (useful to spot the start of cycles in graphs containing many trajectories).

cex.init.points

The size of initial points.

axes

The pair of principal coordinates to be plotted.

...

Additional parameters for function arrows.

fixedDates.colors

The colors applied to the different fixed dates trajectories. Defaults to a simple RGB circular color palette.

sites.lty

The line type for the different sites (see par, "lty").

add.cyclicalTrajectory

A boolean flag to indicate whether the original cyclical trajectory should also be drawn as background.

Details

The functions cyclePCoA and fixedDateTrajectoryPCoA give adapted graphical representation of cycles and fixed-date trajectories using principal coordinate analysis (PCoA, see cmdscale). Function cyclePCoA handles external and potential interpolated ecological states so that they are correctly taken in account in PCoA (i.e. avoiding duplication, and reducing the influence of interpolated ecological states as much as possible). In case of centered cycles, the influence of these ecological states will grow as they will not correspond to duplications anymore. In case of centered cycles, the intended use is to set the parameter centered to TRUE.

Value

Functions cyclePCoA and fixedDateTrajectoryPCoA return the results of calling of cmdscale.

Author(s)

Nicolas Djeghri, UBO

Miquel De Cáceres, CREAF

References

Djeghri et al. (in preparation) Going round in cycles, but going somewhere: Ecological Trajectory Analysis as a tool to decipher seasonality and other cyclical dynamics.

See Also

trajectoryCyclical, cmdscale

Examples

#First build a toy dataset with:
#The sampling times of the time series
timesToy <- 0:30 

#The duration of the cycles (i.e. the periodicity of the time series)
cycleDurationToy <- 10 

#The sites sampled (only one named "A")
sitesToy <- rep(c("A"),length(timesToy)) 

#And prepare a trend term
trend <- 0.05

#Build cyclical data (note that we apply the trend only to x):
x <- sin((timesToy*2*pi)/cycleDurationToy)+trend*timesToy
y <- cos((timesToy*2*pi)/cycleDurationToy)
matToy <- cbind(x,y)

#And express it as distances:
dToy <- dist(matToy)

#Make it an object of class trajectory:
cyclicalTrajToy <- defineTrajectories(d = dToy,
                                      sites = sitesToy,
                                      times = timesToy)

#And extract the cycles and fixed date trajectories:
cyclesToy <- extractCycles(x = cyclicalTrajToy,
                           cycleDuration = cycleDurationToy)
fdTrajToy <- extractFixedDateTrajectories(x = cyclicalTrajToy,
                                          cycleDuration = cycleDurationToy)

#CETA plotting functions:
cyclePCoA(cyclesToy)
fixedDateTrajectoryPCoA(fdTrajToy)

#After centering of cycles, set  parameter centered to TRUE in cyclePCoA():
cent_cyclesToy <- centerTrajectories(cyclesToy)
cyclePCoA(cent_cyclesToy, centered = TRUE)

Trajectory metrics

Description

Set of functions to estimate metrics describing individual trajectories. Given input trajectory data, the set of functions that provide ETA metrics are:

Usage

trajectoryLengths(x, relativeToInitial = FALSE, all = FALSE)

trajectoryLengths2D(
  xy,
  sites,
  surveys = NULL,
  relativeToInitial = FALSE,
  all = FALSE
)

trajectorySpeeds(x)

trajectorySpeeds2D(xy, sites, surveys = NULL, times = NULL)

trajectoryAngles(
  x,
  all = FALSE,
  relativeToInitial = FALSE,
  stats = TRUE,
  add = TRUE
)

trajectoryAngles2D(
  xy,
  sites,
  surveys,
  relativeToInitial = FALSE,
  betweenSegments = TRUE
)

trajectoryDirectionality(x, add = TRUE, nperm = NA)

trajectoryInternalVariation(x, relativeContributions = FALSE)

trajectoryMetrics(x, add = TRUE)

trajectoryWindowMetrics(x, bandwidth, type = "surveys", add = TRUE)

Arguments

x

An object of class trajectories.

relativeToInitial

Flag to indicate that lengths or angles should be calculated with respect to initial survey.

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.

xy

Matrix with 2D coordinates in a Cartesian space (typically an ordination of ecological states).

sites

A vector indicating the site corresponding to each ecological state.

surveys

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

times

A numeric vector indicating the time corresponding to each ecosystem state.

stats

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

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.

betweenSegments

Flag to indicate that angles should be calculated between trajectory segments or with respect to X axis.

nperm

The number of permutations to be used in the directionality test.

relativeContributions

A logical flag to indicate that contributions of individual observations to temporal variability should be expressed in relative terms, i.e. as the ratio of the sum of squares of the observation divided by the overall sum of squares (otherwise, absolute sum of squares are returned).

bandwidth

Bandwidth of the moving windows (in units of surveys or times, depending on type)

type

A string, either "surveys" or "times", indicating how windows are defined.

Details

Ecological Trajectory Analysis (ETA) is a framework to analyze dynamics of ecological entities described as trajectories in a chosen space of multivariate resemblance (De Cáceres et al. 2019). ETA takes trajectories as objects to be analyzed and compared geometrically.

The input distance matrix d should ideally be metric. That is, all subsets of distance triplets should fulfill the triangle inequality (see utility function is.metric). All ETA 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 vignette 'Introduction to Ecological Trajectory Analysis'). If parameter 'add' is set to FALSE and problems of triangle inequality exist, ETA functions may provide missing values in some cases where they should not.

Function trajectoryAngles calculates angles between consecutive segments 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. If all = TRUE angles are calculated between the segments corresponding to all ordered triplets. Alternatively, if relativeToInitial = TRUE angles are calculated for each segment with respect to the initial survey.

Function trajectoryAngles2D calculates angles between consecutive segments in degrees from 2D coordinates given as input. 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 (O to 360), with zero values indicating segments that are in a straight line, and values equal to 180 degrees for segments that are in opposite directions. If all = TRUE angles are calculated between the segments corresponding to all ordered triplets. Alternatively, if relativeToInitial = TRUE angles are calculated for each segment with respect to the initial survey. If betweenSegments = TRUE angles are calculated between segments of trajectory, otherwise, If betweenSegments = FALSE, angles are calculated considering Y axis as the North (0°).

Function trajectoryDirectionality evaluates the directionality metric proposed in De Cáceres et al (2019). If nperm is supplied, then the function performs a permutational test to evaluate the significance of directionality, where the null hypothesis entails a random order of surveys within each trajectory. The p-value corresponds to the proportion of permutations with a directional value equal or larger than the observed.

Value

Functions trajectoryLengths and trajectoryLengths2D return a data frame with the length of each segment on each trajectory and the total length of all trajectories. If relativeToInitial = TRUE lengths are calculated between the initial survey and all the other surveys. If all = TRUE lengths are calculated for all segments.

Functions trajectorySpeeds and trajectorySpeeds2D return a data frame with the speed of each segment on each trajectory and the total speeds of all trajectories. Units depend on the units of distance matrix and the units of times of the input trajectory data.

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 trajectoryAngles2D returns a data frame with angle values on each trajectory. If betweenSegments=TRUE, then angles are calculated between trajectory segments, alternatively, If betweenSegments=FALSE, angles are calculated considering Y axis as the North (0°).

Function trajectoryDirectionality returns a vector with directionality values (one per trajectory). If nperm is not missing, the function returns a data frame with a column of directional values and a column of p-values corresponding to the result of the permutational test.

Function trajectoryInternalVariation returns data.frame with as many rows as trajectories, and different columns: (1) the contribution of each individual state to the internal sum of squares (in absolute or relative terms); (2) the overall sum of squares of internal variability; (3) an unbiased estimator of overall internal variance.

Function trajectoryMetrics returns a data frame where rows are trajectories and columns are different trajectory metrics.

Function trajectoryWindowMetrics returns a data frame where rows are midpoints over trajectories and columns correspond to different trajectory metrics.

Author(s)

Miquel De Cáceres, CREAF

Anthony Sturbois, Vivarmor nature, Réserve Naturelle nationale de la Baie de Saint-Brieuc

Nicolas Djeghri, UBO

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.

See Also

trajectoryComparison, trajectoryPlot, transformTrajectories, cycleMetrics

Examples

#Description of entities (sites) and surveys
entities <- c("1","1","1","2","2","2")
surveys <- c(1, 2, 3, 1, 2, 3)
times <- c(0, 1.5, 3, 0, 1.5, 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
  
#Draw trajectories
trajectoryPlot(xy, entities, surveys,  
               traj.colors = c("black","red"), lwd = 2)

#Distance matrix
d <- dist(xy)
d
  
#Trajectory data
x <- defineTrajectories(d, entities, surveys, times)

#Trajectory lengths
trajectoryLengths(x)
trajectoryLengths2D(xy, entities, surveys)

#Trajectory speeds
trajectorySpeeds(x)
trajectorySpeeds2D(xy, entities, surveys, times)

#Trajectory angles
trajectoryAngles(x)
trajectoryAngles2D(xy, entities, surveys, betweenSegments = TRUE)
trajectoryAngles2D(xy, entities, surveys, betweenSegments = FALSE)

#Several metrics at once
trajectoryMetrics(x)

Trajectory plots

Description

Set of plotting functions for Ecological Trajectory Analysis:

Usage

trajectoryPCoA(
  x,
  traj.colors = NULL,
  axes = c(1, 2),
  survey.labels = FALSE,
  time.labels = FALSE,
  ...
)

trajectoryPlot(
  coords,
  sites,
  surveys = NULL,
  times = NULL,
  traj.colors = NULL,
  axes = c(1, 2),
  survey.labels = FALSE,
  time.labels = FALSE,
  ...
)

Arguments

x

An object of class trajectories.

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.

survey.labels

A boolean flag to indicate whether surveys should be added as text next to arrow endpoints

time.labels

A boolean flag to indicate whether times should be added as text next to arrow endpoints

...

Additional parameters for function arrows.

coords

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

sites

A vector indicating the site corresponding to each ecological state.

surveys

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

times

A numeric vector indicating survey times.

Details

Value

Function trajectoryPCoA returns the result of calling cmdscale.

Author(s)

Miquel De Cáceres, CREAF

Anthony Sturbois, Vivarmor nature, Réserve Naturelle nationale de la Baie de Saint-Brieuc

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.

See Also

trajectoryMetrics, transformTrajectories, cmdscale, cyclePCoA

Examples

#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

#Define trajectory data
x <- defineTrajectories(dist(xy), sites, surveys)
  
#Draw trajectories using original coordinates
trajectoryPlot(xy, sites, surveys, 
               traj.colors = c("black","red"), lwd = 2)

#Draw trajectories in a PCoA
trajectoryPCoA(x, 
               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
  
trajectoryPlot(xy, sites, surveys, 
               traj.colors = c("black","red"), lwd = 2)   
 
x <- defineTrajectories(dist(xy), sites, surveys)
trajectoryPCoA(x, 
               traj.colors = c("black","red"), lwd = 2)

Trajectory projection

Description

Performs an projection of a set of target points onto a specified trajectory and returns the distance to the trajectory (i.e. rejection) and the relative position of the projection point within the trajectory.

Usage

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

Arguments

d

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

target

An integer vector of the ecological states to be projected.

trajectory

An integer vector of the ecological states conforming 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.

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.

force

Flag to indicate that when projection falls out of the reference trajectory for a given, the closest point in the trajectory will be used.

Value

A data frame with the following columns:

Author(s)

Miquel De Cáceres, CREAF

Functions for building Trajectory Sections

Description

Trajectory sections are flexible way to cut longer trajectories. They are presently used chiefly in building cycles for cyclical ecological trajectory analysis (CETA) but might have other applications.

Usage

extractTrajectorySections(
  x,
  Traj,
  tstart,
  tend,
  BCstart,
  BCend,
  namesTS = 1:length(Traj)
)

Arguments

x

An object of class trajectories describing a cyclical trajectory.

Traj

A vector of length equal to the number of desired trajectory sections indicating the trajectories from which trajectory sections must be build (see details).

tstart

A vector of start times for each of the desired trajectory sections (see details).

tend

A vector of end times for each of the desired trajectory sections (see details).

BCstart

A vector of start boundary conditions (either "internal" or "external") for each of the desired trajectory sections (see details).

BCend

A vector of end boundary conditions (either "internal" or "external") for each of the desired trajectory sections (see details).

namesTS

An optional vector giving a name for each of the desired trajectory sections (by default trajectory sections are simply numbered).

Details

Trajectory sections functions:

Trajectory sections can be obtained using extractTrajectorySections. Trajectory sections allow to cut a longer trajectory into parts for further analyses. Cycles are specical case of trajectory sections. A trajectory section TS(Traj,(tstart, BCstart),(tend, BCend)) is defined by the trajectory (Traj) it is obtained from, by an start and end times (tstart and tend) and start and end boundary conditions (BCstart, BCend). The function extractTrajectorySections builds trajectory sections as a function of its arguments Traj, tstart, tend, BCstart, BCend.

Function interpolateEcolStates is called within extractTrajectorySections to interpolate ecological states when tstart and or tend do not have an associated measured ecological state within matrix d.

IMPORTANT: Trajectory sections comprises both "internal" and "external" ecological states (indicated in vector internal, see the output of function extractTrajectorySections). "external" ecological states need a specific treatment in some calculations and for some operations within ETA, namely:

Special care must also be taken when processing the data through principal coordinate analysis as external ecological states are effectively duplicated or interpolated in the output of extractTrajectorySections.

Value

Function extractTrajectorySections returns the base information needed to describe trajectory sections. Its outputs are meant to be used as inputs for other ETA functions in order to obtain desired metrics. Importantly, within trajectory sections, ecological states can be considered "internal" or "external" and may necessitate special treatment (see details). Function extractTrajectorySections returns an object of class sections containing:

Function interpolateEcolStates returns an object of class dist including the desired interpolated ecological states.

Author(s)

Nicolas Djeghri, UBO

Miquel De Cáceres, CREAF

Examples

#Description of sites and surveys
sites <- c("1","1","1","2","2","2")
surveys <- c(1, 2, 3, 1, 2, 3)
times <- c(0, 1.5, 3, 0, 1.5, 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

#Draw trajectories
trajectoryPlot(xy, sites, surveys,  
               traj.colors = c("black","red"), lwd = 2)
               
#Distance matrix
d <- dist(xy)
d
  
#Trajectory data
x <- defineTrajectories(d, sites, surveys, times)

#Cutting some trajectory sections in those trajectories
TrajSec <- extractTrajectorySections(x,
                                     Traj = c("1","1","2"),
                                     tstart = c(0,1,0.7),
                                     tend = c(1.2,2.5,2),
                                     BCstart = rep("internal",3),
                                     BCend = rep("internal",3))
#extractTrajectorySections() works from distances, 
#so for representation using trajectoryPlot(),we must first perform a PCoA:
Newxy <- cmdscale(TrajSec$d)
trajectoryPlot(Newxy,
               sites = TrajSec$metadata$sections,
               surveys = TrajSec$metadata$surveys,
               traj.colors = c("black","grey","red"),lwd = 2)

Transform trajectories

Description

The following functions are provided to transform trajectories:

Usage

smoothTrajectories(
  x,
  survey_times = NULL,
  kernel_scale = 1,
  fixed_endpoints = TRUE
)

centerTrajectories(x, exclude = integer(0))

interpolateTrajectories(x, times)

Arguments

x

An object of class trajectories.

survey_times

A vector indicating the survey time for all surveys (if NULL, time between consecutive surveys is considered to be one)

kernel_scale

Scale of the Gaussian kernel, related to survey times

fixed_endpoints

A logical flag to force keeping the location of trajectory endpoints unmodified

exclude

An integer vector indicating sites that are excluded from trajectory centroid computation. Note: for objects of class cycles, external are excluded by default.

times

A numeric vector indicating new observation times for trajectories. Values should be comprised between time limits of the original trajectories.

Details

Details of calculations are given in De Cáceres et al (2019). Function centerTrajectories performs centering of trajectories using matrix algebra as explained in Anderson (2017).

Value

A modified object of class trajectories, where distance matrix has been transformed. When calling interpolateTrajectories, also the number of observations and metadata is likely to be affected.

Author(s)

Miquel De Cáceres, CREAF

Nicolas Djeghri, UBO

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.

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

See Also

trajectoryPlot trajectoryMetrics