Merge pull request #681 from gavinsimpson/issue-677

Change default test from sequential to omnibus in `adonis2()` Issue 677

R/adonis.R

@@ -1,6 +1,6 @@
 `adonis2` <-
     function(formula, data, permutations = 999, method = "bray",
-             sqrt.dist = FALSE, add = FALSE, by = "terms",
+             sqrt.dist = FALSE, add = FALSE, by = NULL,
              parallel = getOption("mc.cores"), na.action = na.fail,
              strata = NULL, ...)
 {

man/adonis.Rd

@@ -12,7 +12,7 @@
 
 \usage{
 adonis2(formula, data, permutations = 999, method = "bray",
-    sqrt.dist = FALSE, add = FALSE, by = "terms",
+    sqrt.dist = FALSE, add = FALSE, by = NULL,
     parallel = getOption("mc.cores"), na.action = na.fail,
     strata = NULL, ...)
 }
@@ -45,13 +45,13 @@ adonis2(formula, data, permutations = 999, method = "bray",
     details). Choice \code{"lingoes"} (or \code{TRUE}) use the
     recommended method of Legendre & Anderson (1999: \dQuote{method
     1}) and \code{"cailliez"} uses their \dQuote{method 2}.}
-  \item{by}{\code{by = "terms"} will assess significance for each term
-    (sequentially from first to last), setting \code{by = "margin"}
+  \item{by}{\code{by = NULL} will assess the overall significance of all
+    terms together, \code{by = "terms"} will assess significance for each
+    term (sequentially from first to last), setting \code{by = "margin"}
     will assess the marginal effects of the terms (each marginal term
     analysed in a model with all other variables), \code{by = "onedf"}
-    will analyse one-degree-of-freedom contrasts sequentially, \code{by =
-    NULL} will assess the overall significance of all terms
-    together. The arguments is passed on to \code{\link{anova.cca}}.}
+    will analyse one-degree-of-freedom contrasts sequentially. The
+    argument is passed on to \code{\link{anova.cca}}.}
   \item{parallel}{Number of parallel processes or a predefined socket
     cluster.  With \code{parallel = 1} uses ordinary, non-parallel
     processing. The parallel processing is done with \pkg{parallel}
@@ -149,10 +149,10 @@ Ecology and Evolution}, 3, 89--101.
 \examples{
 data(dune)
 data(dune.env)
-## default test by terms
+## default is overall (omnibus) test
 adonis2(dune ~ Management*A1, data = dune.env)
-## overall tests
-adonis2(dune ~ Management*A1, data = dune.env, by = NULL)
+## sequential tests
+adonis2(dune ~ Management*A1, data = dune.env, by = "terms")
 
 ### Example of use with strata, for nested (e.g., block) designs.
 dat <- expand.grid(rep=gl(2,1), NO3=factor(c(0,10)),field=gl(3,1) )

tests/vegan-tests.R

@@ -42,7 +42,7 @@ anova(m, by="term", permutations=99) # failed before 2.5-0
 anova(m, by="margin", permutations=99) # works since 2.5-0
 anova(m, by="axis", permutations=99)
 ## adonis
-adonis2(fla, data = dune.env)
+adonis2(fla, data = dune.env, by = "terms")
 ## capscale
 p <- capscale(fla, data=df, na.action=na.exclude, subset = Use != "Pasture" & spno > 7)
 anova(p, permutations=99)
@@ -80,10 +80,10 @@ foo("capscale", dune, Management, na.action = na.omit) # fails in 2.2-1
 ## adonis must be done with detached 'df' or it will be used instead
 ## of with(dune.env, ...)
 detach(df)
-with(dune.env, foo("adonis2", dune, Management))
+with(dune.env, foo("adonis2", dune, Management, by = "terms"))
 ## the test case reported in github issue #285 by @ktmbiome
 var <- "Moisture"
-adonis2(dune ~ dune.env[, var])
+adonis2(dune ~ dune.env[, var], by = "terms")
 rm(var)
 ###
 

tests/vegan-tests.Rout.save

@@ -1,7 +1,7 @@
 
-R version 4.3.3 (2024-02-29) -- "Angel Food Cake"
+R version 4.4.1 (2024-06-14) -- "Race for Your Life"
 Copyright (C) 2024 The R Foundation for Statistical Computing
-Platform: aarch64-apple-darwin20 (64-bit)
+Platform: aarch64-apple-darwin20
 
 R is free software and comes with ABSOLUTELY NO WARRANTY.
 You are welcome to redistribute it under certain conditions.
@@ -109,13 +109,13 @@ Residual  5   0.80011
 ---
 Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
 > ## adonis
-> adonis2(fla, data = dune.env)
+> adonis2(fla, data = dune.env, by = "terms")
 Permutation test for adonis under reduced model
 Terms added sequentially (first to last)
 Permutation: free
 Number of permutations: 999
 
-adonis2(formula = fla, data = dune.env)
+adonis2(formula = fla, data = dune.env, by = "terms")
             Df SumOfSqs      R2      F Pr(>F)   
 Management   3   1.4686 0.34161 3.0480  0.003 **
 poly(A1, 2)  2   0.5829 0.13559 1.8146  0.057 . 
@@ -410,13 +410,13 @@ Eigenvalues for unconstrained axes:
 > ## adonis must be done with detached 'df' or it will be used instead
 > ## of with(dune.env, ...)
 > detach(df)
-> with(dune.env, foo("adonis2", dune, Management))
+> with(dune.env, foo("adonis2", dune, Management, by = "terms"))
 Permutation test for adonis under reduced model
 Terms added sequentially (first to last)
 Permutation: free
 Number of permutations: 999
 
-bar(formula = Y ~ X)
+bar(formula = Y ~ X, by = "terms")
          Df SumOfSqs      R2      F Pr(>F)   
 X         3   1.4686 0.34161 2.7672  0.006 **
 Residual 16   2.8304 0.65839                 
@@ -425,13 +425,13 @@ Total    19   4.2990 1.00000
 Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
 > ## the test case reported in github issue #285 by @ktmbiome
 > var <- "Moisture"
-> adonis2(dune ~ dune.env[, var])
+> adonis2(dune ~ dune.env[, var], by = "terms")
 Permutation test for adonis under reduced model
 Terms added sequentially (first to last)
 Permutation: free
 Number of permutations: 999
 
-adonis2(formula = dune ~ dune.env[, var])
+adonis2(formula = dune ~ dune.env[, var], by = "terms")
                 Df SumOfSqs      R2      F Pr(>F)    
 dune.env[, var]  3   1.7282 0.40199 3.5851  0.001 ***
 Residual        16   2.5709 0.59801                  
@@ -1003,4 +1003,4 @@ Cumulative Proportion 0.9994867 1.0000000
 > 
 > proc.time()
    user  system elapsed 
-  1.418   0.063   1.482 
+  1.108   0.041   1.165