Rename methods for co-occurrence assessment

R/AllGenerics.R

@@ -787,7 +787,7 @@ setGeneric(
 #'  Jaccard, Morisita-Horn and Sorenson indices provide a scale of similarity
 #'  from \eqn{0}-\eqn{1} where \eqn{1} is perfect similarity and \eqn{0} is
 #'  no similarity. The Brainerd-Robinson index is scaled between \eqn{0} and
-#'  \eqn{200}. The Binomial co-occurrence assessment approximates a Z-score.
+#'  \eqn{200}.
 #'
 #'  \describe{
 #'   \item{`brainerd`}{[Brainerd-Robinson quantitative index][index_brainerd()].}
@@ -1072,12 +1072,15 @@ setGeneric(
 #'  individuals for each category, i.e. a contingency table). A [`data.frame`]
 #'  will be coerced to a `numeric` `matrix` via [data.matrix()].
 #' @param method A [`character`] string specifying the method to be
-#'  used (see details). Any unambiguous substring can be given.
+#'  used. It must be one of "`absolute`", "`relative`" or "`binomial`"
+#'  (see details). Any unambiguous substring can be given.
 #' @param ... Currently not used.
 #' @details
 #'  \describe{
-#'   \item{`count`}{Count how many times each pairs of types occur together in
-#'    at least one sample.}
+#'   \item{`absolute`}{Count how many times each pairs of types occur together
+#'   in at least one sample (absolute frequencies).}
+#'   \item{`relative`}{Count how many times each pairs of types occur together
+#'   in at least one sample (relative frequencies).}
 #'   \item{`binomial`}{[Binomial co-occurrence assessment][index_binomial()].}
 #'  }
 #' @return
@@ -1100,6 +1103,8 @@ setGeneric(
 #'  This assesses the degree of co-occurrence between taxa/types within a
 #'  dataset. The strongest associations are shown by large positive numbers,
 #'  the strongest segregations by large negative numbers.
+#'
+#'  The Binomial co-occurrence assessment approximates a Z-score.
 #' @return
 #'  A [`numeric`] vector.
 #' @references

R/occurrence.R

@@ -8,15 +8,15 @@ NULL
 setMethod(
   f = "occurrence",
   signature = c(object = "matrix"),
-  definition = function(object, method = c("count", "binomial")) {
+  definition = function(object, method = c("absolute", "relative", "binomial")) {
     ## Validation
     method <- match.arg(method, several.ok = FALSE)
 
     ## Pairwise comparison
     p <- ncol(object)
     labels <- colnames(object)
 
-    if (method == "count") {
+    if (method == "absolute" || method == "relative") {
       incid <- object > 0
       fun <- function(x) sum(incid[, x[1]] + incid[, x[2]] == 2)
     }
@@ -34,6 +34,10 @@ setMethod(
     mtx <- t(mtx)
     mtx[lower.tri(mtx, diag = FALSE)] <- index
 
+    if (method == "relative") {
+      mtx <- mtx / nrow(object)
+    }
+
     occ <- stats::as.dist(mtx)
     attr(occ, "total") <- nrow(object)
     occ

inst/examples/ex-occurrence.R

@@ -2,5 +2,8 @@
 data("cantabria")
 
 ## Plot spot diagram of a co-occurrence matrix
-occ <- occurrence(cantabria)
-plot_spot(occ)
+occ_abs <- occurrence(cantabria, method = "absolute") # Absolute frequencies
+plot_spot(occ_abs)
+
+occ_rel <- occurrence(cantabria, method = "relative") # Relative frequencies
+plot_spot(occ_rel)

inst/tinytest/test_index.R

@@ -111,11 +111,6 @@ x <- c(16, 9, 3, 0, 1)
 y <- c(13, 3, 2, 0, 0)
 expect_equal(round(index_brainerd(x, y)), 164) # 164
 
-## Binomial co-occurrence
-x <- c(16, 9, 3, 0, 1)
-y <- c(13, 3, 2, 0, 0)
-expect_equal(round(index_binomial(x, y), 3), 0.537) # 0.54
-
 # Turnover =====================================================================
 data("woodland")
 

inst/tinytest/test_occurrence.R

@@ -7,9 +7,14 @@ exp_occ <- matrix(
            1L, 1L, 3L, 0L, 0L),
   nrow = 5, ncol = 5
 )
-test_occ <- occurrence(pueblo)
+test_occ <- occurrence(pueblo, method = "absolute")
 expect_equivalent(test_occ, as.dist(exp_occ))
 
+## Binomial co-occurrence
+x <- c(16, 9, 3, 0, 1)
+y <- c(13, 3, 2, 0, 0)
+expect_equal(round(index_binomial(x, y), 3), 0.537) # 0.54
+
 if (at_home()) {
   source("helpers.R")
   using("tinysnapshot")