From 55992af191b653b4353f68fe5b56e912d718f3a7 Mon Sep 17 00:00:00 2001
From: Jari Oksanen <jhoksane@gmail.com>
Date: Tue, 2 Feb 2021 12:48:14 +0200
Subject: [PATCH] diversity gains arg groups for pooled diversity (gamma) of
 SUs

This allows easy calculation of additive diversity indices based
on diversity indicex. Earlier we had this arg only for specnumber
to get the species number of pooled SUs.

See github issue #393
---
 R/diversity.R    | 14 +++++++++++++-
 man/diversity.Rd | 20 +++++++++++++-------
 2 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/R/diversity.R b/R/diversity.R
index a3cf5386d..a8f033da4 100644
--- a/R/diversity.R
+++ b/R/diversity.R
@@ -1,11 +1,23 @@
 `diversity` <-
-    function (x, index = "shannon", MARGIN = 1, base = exp(1))
+    function (x, index = "shannon", groups, MARGIN = 1, base = exp(1))
 {
     x <- drop(as.matrix(x))
     if (!is.numeric(x))
         stop("input data must be numeric")
     if (any(x < 0, na.rm = TRUE))
         stop("input data must be non-negative")
+    ## sum communities for groups
+    if (!missing(groups)) {
+        if (MARGIN == 2)
+            x <- t(x)
+        if (length(groups) == 1) # total for all SU
+            groups <- rep(groups, NROW(x))
+        x <- aggregate(x, list(groups), sum) # pool SUs by groups
+        rownames(x) <- x[,1]
+        x <- x[,-1, drop=FALSE]
+        if (MARGIN == 2)
+            x <- t(x)
+    }
     INDICES <- c("shannon", "simpson", "invsimpson")
     index <- match.arg(index, INDICES)
     if (length(dim(x)) > 1) {
diff --git a/man/diversity.Rd b/man/diversity.Rd
index c2ce3a872..563c0a31f 100644
--- a/man/diversity.Rd
+++ b/man/diversity.Rd
@@ -10,7 +10,7 @@
   richness.  }
 
 \usage{
-diversity(x, index = "shannon", MARGIN = 1, base = exp(1))
+diversity(x, index = "shannon", groups, MARGIN = 1, base = exp(1))
 fisher.alpha(x, MARGIN = 1, ...)
 specnumber(x, groups, MARGIN = 1)
 }
@@ -21,7 +21,8 @@ specnumber(x, groups, MARGIN = 1)
     \code{"simpson"} or \code{"invsimpson"}.}
   \item{MARGIN}{Margin for which the index is computed. }
   \item{base}{ The logarithm \code{base} used in \code{shannon}.}
-  \item{groups}{A grouping factor: if given, finds the total number of
+  \item{groups}{A grouping factor: if given, finds the diversity of
+    communities pooled by the groups or the total number of
     species in each group.}
   \item{...}{Parameters passed to the function.}
 }
@@ -89,7 +90,7 @@ specnumber(x, groups, MARGIN = 1)
 \author{ Jari Oksanen  and  Bob O'Hara (\code{fisher.alpha}).}
 
 \examples{
-data(BCI)
+data(BCI, BCI.env)
 H <- diversity(BCI)
 simp <- diversity(BCI, "simpson")
 invsimp <- diversity(BCI, "inv")
@@ -103,11 +104,16 @@ pairs(cbind(H, simp, invsimp, unbias.simp, alpha), pch="+", col="blue")
 S <- specnumber(BCI) ## rowSums(BCI > 0) does the same...
 J <- H/log(S)
 ## beta diversity defined as gamma/alpha - 1:
-data(dune)
-data(dune.env)
-alpha <- with(dune.env, tapply(specnumber(dune), Management, mean))
-gamma <- with(dune.env, specnumber(dune, Management))
+## alpha is the average no. of species in a group, and gamma is the
+## total number of species in the group
+(alpha <- with(BCI.env, tapply(specnumber(BCI), Habitat, mean)))
+(gamma <- with(BCI.env, specnumber(BCI, Habitat)))
 gamma/alpha - 1
+## similar calculations with Shannon diversity
+(alpha <- with(BCI.env, tapply(diversity(BCI), Habitat, mean))) # average
+(gamma <- with(BCI.env, diversity(BCI, groups=Habitat))) # pooled
+## additive beta diversity based on Shannon index
+gamma-alpha
 }
 \keyword{ univar }