trajectoryCyclical {ecotraj}R Documentation

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)
             


[Package ecotraj version 1.1.0 Index]