Skip to contents

Relative Trajectory Movement Assessment (RTMA) is a method for testing and qualifying of the relative movements of ecological trajectories (e.g. "convergence", "parallel" etc., see details) as described in Djeghri et al. (in prep). It is implemented in function trajectoryRMA().

Usage

trajectoryRMA(x, alpha = 0.05, nperm = 999, full.output = TRUE, add = TRUE)

Arguments

x

An object of class trajectories.

alpha

The alpha level for the tests performed in RTMA. Defaults to 0.05.

nperm

Passed to function trajectoryCorrespondence. The number of permutations to be used in the dynamic correspondence test. Defaults to 999.

full.output

Flag to indicate that the full output of tests should be computed. Defaults to TRUE. Setting to FALSE will improve computation speed but yield incomplete outputs (see details).

add

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

Value

Function trajectoryRMA returns an object of class list containing:

  • dynamic_relationships: a matrix containing the relative movement relationships attributed to each pair of trajectories.

  • symmetric_convergence: a list containing the results of the symmetric convergence test.

  • asymmetric_convergence: a list containing the results of the two asymmetric convergence tests.

  • correspondence: a matrix containing the results of the the dynamic correspondence tests (partial if full.out = FALSE).

  • parameters: a vector containing the parameters alpha, the Šidák corrected_alpha, and nperm.

In addition to the relationships recognized by RTMA, matrix dynamic_relationships provides the role of each trajectory in asymmetric relationships. The role is provided in parenthesis and applies to the trajectory of the ROW index. For example, "approaching (approacher)" means that the trajectory of the corresponding row is approaching the trajectory of the corresponding column, which will have "approaching (target)". In symmetric relationships, the wording (symmetric) is added to indicate that there is no distinction of roles.

Details

Function trajectoryRMA attributes a dynamic relationship to pairs of ecological trajectories A and B describing their relative movement. It does so by combining four tests:

  • Three convergence tests performed through internal callings of function trajectoryConvergence:

    • The symmetric convergence test between trajectories A and B.

    • The asymmetric convergence test assessing if trajectory A approaches trajectory B.

    • The asymmetric convergence test assessing if trajectory B approaches trajectory A.

  • One dynamic correspondence test performed through internal callings to function trajectoryCorrespondence.

To account for multiple testing, trajectoryRMA performs internally a Šidák (1967) correction on the alpha level provided in parameter alpha.

The results of the four tests (p-values and sign of statistic) are used to assign to each trajectory pair a relationship describing their relative movements. RTMA recognizes a total of 12 relationships, some existing in "weak" variations. The following five dynamic relationships are symmetric, i.e. applying to the two trajectories without distinction of roles:

  • "convergence" - The two trajectories converge. Exists in a weak version.

  • "divergence" - The two trajectories diverge. Exists in a weak version.

  • "parallel" - The two trajectories travel side by side with broadly similar movements.

  • "antiparallel" - As in "parallel" but the two trajectories travel in opposite directions.

  • "neutral" - The two trajectories have no particular movements relative to each other (effectively the null hypothesis for RTMA).

The following seven dynamic relationships are asymmetric (e.g. in "pursuit" there is a leading and a following trajectory). In these asymmetric relationships the output of function trajectoryRMA gives the role of each trajectory (see Value section).

  • "approaching" - One trajectory approaches the other.

  • "approaching-stationary" - As in "approaching" but the trajectory approached is stationary relative to the approaching trajectory.

  • "departing" - One trajectory moves away from the other.

  • "departing-stationary" - As in "departing" but the trajectory departed from is stationary relative to the departing trajectory.

  • "pursuit" - The two trajectories follow each other.

  • "catch-up" - As in "pursuit" but the following trajectory moves faster.

  • "escape" - As in "pursuit" but the leading trajectory is faster.

In rare cases, unlikely relationships (labelled "unknown", with a short description in brackets) may occur. These involve contradictory patterns hard to interpret.

LIMITATIONS: RTMA has some limitations, in particular it uses trend tests not well suited to study trajectories pairs with changing relative movements (e.g. if two trajectories cross each other, they are first converging then diverging). We advise users to not only rely on RTMA but to also visualize trajectories using function trajectoryPCoA for ecological interpretations. See Djeghri et al. (in prep) for more details. Note also that, because RTMA incorporates a correction for multiple testing, it needs somewhat long trajectories to operate (minimum number of survey = 6 at alpha = 0.05).

COMPUTATION TIME: The dynamic correspondence tests performed in RTMA are computationally costly permutation tests only used when all three convergence tests are non-significant. Function trajectoryRMA performs by default all tests but it is possible to only perform the tests useful for RTMA by setting full.output = FALSE. This will reduce computation time but the details of the output of RTMA will not contain the information on all possible dynamic correspondence tests, only on relevant ones.

PLOTTING: Function trajectoryConvergencePlot provides options to plot the results of RTMA.

References

Djeghri et al. (in preparation) Uncovering the relative movements of ecological trajectories.

Šidák, Z. (1967) Rectangular confidence regions for the means of multivariate normal distributions. Journal of the American Statistical Association 62:648-633.

Author

Nicolas Djeghri, UBO

Miquel De Cáceres, CREAF

Examples

#Obtain and format some trajectories
data("avoca")
avoca_D_man <- vegclust::vegdiststruct(avoca_strat, 
                                       method ="manhattan", 
                                       transform = function(x){log(x+1)})
years <- c(1971, 1974, 1978, 1983, 1987, 1993, 1999, 2004, 2009)
avoca_times <- years[avoca_surveys]
avoca_x <- defineTrajectories(d = avoca_D_man,  
                              sites = avoca_sites, 
                              times = avoca_times)
                              
#Visualize the trajectories
trajectoryPCoA(avoca_x,traj.colors = RColorBrewer::brewer.pal(8,"Accent"),length=0.1,lwd=2)
legend("bottomleft",bty="n",legend=1:8,col=RColorBrewer::brewer.pal(8,"Accent"),lwd=2,ncol=2)


#Perform RTMA
trajectoryRMA(avoca_x)
#> $dynamic_relationships
#>   1                                           
#> 1 NA                                          
#> 2 "parallel (symmetric)"                      
#> 3 "approaching (target)"                      
#> 4 "pursuit (leader)"                          
#> 5 "parallel (symmetric)"                      
#> 6 "approaching (target)"                      
#> 7 "departing (departer)"                      
#> 8 "approaching-stationary (stationary target)"
#>   2                                            3                             
#> 1 "parallel (symmetric)"                       "approaching (approacher)"    
#> 2 NA                                           "approaching (approacher)"    
#> 3 "approaching (target)"                       NA                            
#> 4 "pursuit (leader)"                           "approaching (target)"        
#> 5 "parallel (symmetric)"                       "approaching (approacher)"    
#> 6 "approaching (target)"                       "weak convergence (symmetric)"
#> 7 "approaching (target)"                       "parallel (symmetric)"        
#> 8 "approaching-stationary (stationary target)" "approaching (target)"        
#>   4                          5                     
#> 1 "pursuit (follower)"       "parallel (symmetric)"
#> 2 "pursuit (follower)"       "parallel (symmetric)"
#> 3 "approaching (approacher)" "approaching (target)"
#> 4 NA                         "departing (departer)"
#> 5 "departing (origin)"       NA                    
#> 6 "approaching (approacher)" "approaching (target)"
#> 7 "neutral (symmetric)"      "departing (departer)"
#> 8 "neutral (symmetric)"      "neutral (symmetric)" 
#>   6                                           
#> 1 "approaching (approacher)"                  
#> 2 "approaching (approacher)"                  
#> 3 "weak convergence (symmetric)"              
#> 4 "approaching (target)"                      
#> 5 "approaching (approacher)"                  
#> 6 NA                                          
#> 7 "approaching-stationary (stationary target)"
#> 8 "approaching (target)"                      
#>   7                                     8                                    
#> 1 "departing (origin)"                  "approaching-stationary (approacher)"
#> 2 "approaching (approacher)"            "approaching-stationary (approacher)"
#> 3 "parallel (symmetric)"                "approaching (approacher)"           
#> 4 "neutral (symmetric)"                 "neutral (symmetric)"                
#> 5 "departing (origin)"                  "neutral (symmetric)"                
#> 6 "approaching-stationary (approacher)" "approaching (approacher)"           
#> 7 NA                                    "approaching (approacher)"           
#> 8 "approaching (target)"                NA                                   
#> 
#> $symmetric_convergence
#> $symmetric_convergence$tau
#>             1           2          3          4          5          6
#> 1          NA -0.05555556 -0.4444444 -0.4444444 -0.4444444 -0.4444444
#> 2 -0.05555556          NA -0.3888889  0.1111111 -0.3333333 -0.3888889
#> 3 -0.44444445 -0.38888890         NA  0.4444444 -0.1111111 -0.6666667
#> 4 -0.44444445  0.11111111  0.4444444         NA  0.6111111  0.2777778
#> 5 -0.44444445 -0.33333334 -0.1111111  0.6111111         NA  0.4444444
#> 6 -0.44444445 -0.38888890 -0.6666667  0.2777778  0.4444444         NA
#> 7 -0.05555556 -0.33333334 -0.3888889  0.4444444  0.1666667 -0.7777778
#> 8 -0.94444442 -0.83333331 -0.6666667 -0.4444444 -0.5555556 -0.5555556
#>             7          8
#> 1 -0.05555556 -0.9444444
#> 2 -0.33333334 -0.8333333
#> 3 -0.38888890 -0.6666667
#> 4  0.44444445 -0.4444444
#> 5  0.16666667 -0.5555556
#> 6 -0.77777779 -0.5555556
#> 7          NA -0.5000000
#> 8 -0.50000000         NA
#> 
#> $symmetric_convergence$p.value
#>             1           2          3          4          5           6
#> 1          NA 0.916965246 0.11785091 0.11785091 0.11785091 0.117850907
#> 2 0.916965246          NA 0.17530808 0.75445414 0.25145215 0.175308079
#> 3 0.117850907 0.175308079         NA 0.11785090 0.75445420 0.016488666
#> 4 0.117850907 0.754454136 0.11785090         NA 0.02856767 0.348082542
#> 5 0.117850907 0.251452148 0.75445420 0.02856767         NA 0.117850900
#> 6 0.117850907 0.175308079 0.01648867 0.34808254 0.11785090          NA
#> 7 0.916965246 0.251452148 0.17530808 0.11785090 0.60216761 0.004878566
#> 8 0.000580667 0.002499029 0.01648867 0.11785091 0.04760397 0.047603969
#>             7           8
#> 1 0.916965246 0.000580667
#> 2 0.251452148 0.002499029
#> 3 0.175308079 0.016488666
#> 4 0.117850900 0.117850907
#> 5 0.602167606 0.047603969
#> 6 0.004878566 0.047603969
#> 7          NA 0.076332748
#> 8 0.076332748          NA
#> 
#> 
#> $asymmetric_convergence
#> $asymmetric_convergence$tau
#>             1          2          3          4          5          6          7
#> 1          NA -0.1111111 -0.7222222 -0.7777778 -0.5000000 -0.8333333 -0.5555556
#> 2 -0.11111111         NA -0.8333333 -0.7222222 -0.3888889 -0.8333333 -0.8333333
#> 3  0.05555556  0.2222222         NA -0.7777778  0.2777778 -1.0000000 -0.6111111
#> 4  0.77777779  0.7222222  0.5000000         NA  0.7222222  0.2777778  0.0000000
#> 5 -0.50000000 -0.4444444 -0.8333333 -0.6666667         NA -0.7222222 -0.2777778
#> 6  0.11111111  0.0000000 -0.7777778 -0.8888889  0.5555556         NA -0.7777778
#> 7  0.83333331  0.5555556 -0.5000000  0.3333333  0.7777778 -0.5000000         NA
#> 8 -0.27777779 -0.1111111  0.5000000 -0.3888889 -0.1111111  0.0000000  0.1111111
#>            8
#> 1 -0.8888889
#> 2 -0.7222222
#> 3 -0.8333333
#> 4 -0.3888889
#> 5 -0.6666667
#> 6 -0.8333333
#> 7 -0.7222222
#> 8         NA
#> 
#> $asymmetric_convergence$p.value
#>             1           2           3           4           5           6
#> 1          NA 0.754454195 0.009149152 0.004878566 0.076332748 0.002499029
#> 2 0.754454195          NA 0.002499029 0.009149152 0.175308079 0.002499029
#> 3 0.916965246 0.465512276          NA 0.004878566 0.348082542 0.000263261
#> 4 0.004878521 0.009149194 0.076332808          NA 0.009149194 0.348082542
#> 5 0.076332748 0.117850907 0.002499029 0.016488666          NA 0.009149152
#> 6 0.754454136 1.000000000 0.004878566 0.001229385 0.047603965          NA
#> 7 0.002498984 0.047603965 0.076332748 0.251452208 0.004878521 0.076332748
#> 8 0.348082602 0.754454195 0.076332808 0.175308079 0.754454195 1.000000000
#>             7           8
#> 1 0.047603969 0.001229385
#> 2 0.002499029 0.009149152
#> 3 0.028567679 0.002499029
#> 4 1.000000000 0.175308079
#> 5 0.348082602 0.016488666
#> 6 0.004878566 0.002499029
#> 7          NA 0.009149152
#> 8 0.754454136          NA
#> 
#> 
#> $correspondence
#>       1        2        3          4          5         6         7         8
#> 1    NA 19.03032 8.458292 -0.3849957  6.9727634  8.870780  4.659245 -4.843623
#> 2 0.001       NA 7.404500 -1.7352106  8.8138162  7.670095  4.378526 -5.364705
#> 3 0.001  0.00100       NA  3.2384825  7.3954199 15.518213 15.765570 -7.467005
#> 4 0.732  0.23500 0.302000         NA -0.4031831  8.449945  5.965950  3.857741
#> 5 0.001  0.00100 0.001000  0.8080000         NA  6.455380  3.822771 -3.049777
#> 6 0.001  0.00200 0.001000  0.0310000  0.0020000        NA 16.816550 -2.728982
#> 7 0.002  0.00700 0.001000  0.0500000  0.0010000  0.001000        NA -3.957437
#> 8 0.001  0.00100 0.001000  0.2830000  0.0540000  0.358000  0.023000        NA
#> 
#> $parameters
#>           alpha corrected_alpha           nperm 
#>      0.05000000      0.01274146    999.00000000 
#> 
#> attr(,"class")
#> [1] "RTMA" "list"