version 0.0.2

DESCRIPTION

@@ -1,23 +1,22 @@
 Package: comstab
 Title: Partitioning the Drivers of Stability of Ecological Communities
-Version: 0.0.1
+Version: 0.0.2
 Authors@R: 
     person("Jules", "Segrestin", , "jsegrestin@gmail.com", role = c("aut", "cre", "cph"),
            comment = c(ORCID = "0000-0001-7661-6061"))
 Description: Contains the basic functions to apply the unified framework
     for partitioning the drivers of stability of ecological communities. 
-    J. Segrestin, L. Götzenberger, E. Valencia, F. de Bello & J. Lepš (2024) 
-    "A unified framework for partitioning the drivers of stability of ecological communities" <minor revisions>.
+    Segrestin et al. (2024) <doi:10.1111/geb.13828>.
 License: GPL-3
 URL: https://github.com/jsegrestin/comstab
 BugReports: https://github.com/jsegrestin/comstab/issues
 Imports: graphics, stats, Ternary
 Encoding: UTF-8
 RoxygenNote: 7.3.1
 NeedsCompilation: no
-Packaged: 2024-02-19 08:39:21 UTC; jsegrestin
+Packaged: 2024-03-14 13:48:23 UTC; jsegrestin
 Author: Jules Segrestin [aut, cre, cph]
     (<https://orcid.org/0000-0001-7661-6061>)
 Maintainer: Jules Segrestin <jsegrestin@gmail.com>
 Repository: CRAN
-Date/Publication: 2024-02-20 20:20:09 UTC
+Date/Publication: 2024-03-14 15:30:05 UTC

MD5

@@ -1,12 +1,12 @@
-71f44d72a57760b512c429de84fb0bd9 *DESCRIPTION
+07874ff41c31801cd626c8c3bf784fd2 *DESCRIPTION
 a3ea5304c2025ab3689da4dbeefbd1dc *NAMESPACE
-975049a14cd985f8f462fafe5bcb614c *NEWS.md
+d0eafc8da5041a8cc1b076d2eaaed3c6 *NEWS.md
 dcc6724fadbede0be4cc4def20838f99 *R/comTS.R
-138132b6223e85eb37e76fd1396ea84a *R/partitionR.R
+595ca4844fe976a1ddc47aff49bba804 *R/partitionR.R
 a6f0e9d96a6f0031f392416592a8917e *R/plot.R
-a64ca09a1527f4700010abd0c595828e *R/ternStab.R
-a18500e17b9e88320a73d9a224d1457f *README.md
+d59e6aa3216696df7572ebeb7c5d68f6 *R/ternStab.R
+f386dc531a609b1fe7221e9c94e83e77 *README.md
 5d30f816cfb3dab43dc5c36e13934661 *man/comTS.Rd
-4a50a22bc2848a351a628f5aa9757ca0 *man/partitionR.Rd
+fff57a979ff0453eac5053b4dbd84211 *man/partitionR.Rd
 a5a37f234d48c74f8d857de0452b7302 *man/plot.comstab.Rd
 457494df391843506dd911fabd702ba6 *man/ternStab.Rd

NEWS.md

@@ -1,3 +1,9 @@
-# comstab 0.0.1
-
-* Initial CRAN submission.
+# comstab 0.0.2
+
+* Updated reference to the newly published manuscript.
+* 'PartitionR()' works with one-species communities and does not compute relative effects when a stabilizing effect > 1.
+* 'TernStab()' checks if relative effects can be calculated before plotting.
+
+# comstab 0.0.1
+
+* Initial CRAN submission.

R/partitionR.R

@@ -19,15 +19,16 @@
 #'  * `'Stabilization'` a named vector of the stabilizing effects. `tau` is the total stabilization, `Delta` is
 #'  the dominance effect, `Psi` is the asynchrony effect, and `omega` is the averaging effect.
 #'  * `'Relative'` a named vector of the relative contributions of each stabilizing effect to the total stabilization.
-#'  `Delta_cont`, `Psi_cont`, and `omega_cont` are the relative contribution of respectively, the dominance, asynchrony, and averaging effects to the total stabilization. 
+#'  `Delta_cont`, `Psi_cont`, and `omega_cont` are the relative contribution of respectively, the dominance, asynchrony, and averaging effects to the total stabilization.
+#'  Returns a vector of NAs if any Stabilizing effect is higher than 1.
 #'  
 #' @details The analytic framework is described in details in Segrestin *et al.* (2024).
 #' In short, the partitioning relies on the following equation: \deqn{CV_{com} = CV_e \Delta \Psi \omega} 
 #' where \eqn{CV_{com}} is the community coefficient of variation (reciprocal of community stability), 
 #' \eqn{CV_e} is the expected community CV when controlling for the dominance structure and species temporal synchrony,
 #' \eqn{ \Delta} is the dominance effect, \eqn{ \Psi} is the asynchrony effect, and \eqn{ \omega} is the averaging effect.
 #'
-#' @references Segrestin *et al.* (2024) A unified framework for partitioning the drivers of stability of ecological communities
+#' @references Segrestin *et al.* (2024) A unified framework for partitioning the drivers of stability of ecological communities. Global Ecology and Biogeography, https://doi.org/10.1111/geb.13828
 #' 
 #' @examples
 #' require(stats)
@@ -49,7 +50,6 @@ partitionR <- function(z, ny = 1){
   if(!is.matrix(z)) stop("Error: z is not a matrix")
   if(!is.numeric(z)) stop("Error: non-numerical values in z")
   if(dim(z)[1] == 1) stop("Error: single-row matrix")
-  if(dim(z)[2] == 1) warning("This analysis is not relevant for single-species communities")
   if(!is.numeric(ny)) stop("ny must be numeric")
 
   # Remove absent species
@@ -64,51 +64,83 @@ partitionR <- function(z, ny = 1){
   varsum <- stats::var(rowSums(z))
   meansum <- mean(rowSums(z))
   CV <- sqrt(varsum)/meansum
+  if(CV == 0) stop("The community CV is zero. This analysis does not apply to perfectly stable communities.")
 
-  # Expected community CV if all species had even abundances
-  vari <- apply(X = z, MARGIN = 2, FUN = stats::var)
-  meani <- colMeans(z)
-  CVi <- sqrt(vari) / meani
-  TPL <- stats::coef(stats::lm(log10(CVi) ~ log10(meani)))
-  CVe <- 10^TPL[1] * (meansum / n) ^ TPL[2]
-  if (stats::cor.test(log10(CVi), log10(meani))$p.value > 0.05) warning("No significant power law between species CVs and abundances.")
+  if(dim(z)[2] == 1) {
+
+    warning("This analysis is not relevant for single-species communities. All stabilizing effects were fixed to 1.")
+
+    # outputs
+    CVs <- stats::setNames(object = c(CV, CV, CV, CV),
+                           nm = c("CVe", "CVtilde", "CVa", "CVc"))
+    Stabilization <- stats::setNames(object = c(1, 1, 1, 1),
+                                     nm = c("tau", "Delta", "Psi", "omega"))
+    Relative <- stats::setNames(object = rep(NA, 3),
+                                nm = c("Delta_cont", "Psi_cont", "omega_cont"))
+    res <- list(CVs = CVs, Stabilization = Stabilization, Relative = Relative)
+    class(res) <- "comstab"
+    return(res)
+  }
 
-  # Dominance effect
-  sumsd <- sum(sqrt(vari))
-  CVtilde <- sumsd / meansum
-  Delta <- CVtilde / CVe
-
-  # Compensatory dynamics
-  sdsum <- sqrt(varsum)
-  rootPhi <- sdsum / sumsd
-
-  # Asynchrony effect
-  sumvar <- sum(vari)
-  beta <- log10(1/2) / (log10(sumvar / (sumsd^2)))
-  Psi <- rootPhi^beta
-
-  # averaging effect
-  omega <- rootPhi / Psi
-
-  # total stabilization
-  tau <- Delta * Psi * omega
-
-  # outputs
-  CVs <- stats::setNames(object = c(CVe, CVtilde, CVtilde * Psi, CV),
-                         nm = c("CVe", "CVtilde", "CVa", "CVc"))
-  Stabilization <- stats::setNames(object = c(tau, Delta, Psi, omega),
-                                   nm = c("tau", "Delta", "Psi", "omega"))
-  Relative <- stats::setNames(object = c(log10(Delta)/log10(tau), log10(Psi)/log10(tau), log10(omega)/log10(tau)),
-                              nm = c("Delta_cont", "Psi_cont", "omega_cont"))
-  res <- list(CVs = CVs, Stabilization = Stabilization, Relative = Relative)
-  class(res) <- "comstab"
-  return(res)
+  if(dim(z)[2] > 1) {
+
+    # Expected community CV if all species had even abundances
+    vari <- apply(X = z, MARGIN = 2, FUN = stats::var)
+    meani <- colMeans(z)
+    CVi <- sqrt(vari) / meani
+    TPL <- stats::coef(stats::lm(log10(CVi) ~ log10(meani)))
+    CVe <- 10^TPL[1] * (meansum / n) ^ TPL[2]
+
+    if(dim(z)[2] > 2){
+      testcor <- stats::cor.test(log10(CVi), log10(meani))$p.value > 0.05
+      if (testcor) warning("No significant power law between species CVs and abundances.")
+    }
+
+    # Dominance effect
+    sumsd <- sum(sqrt(vari))
+    CVtilde <- sumsd / meansum
+    Delta <- CVtilde / CVe
+    if(Delta > 1) warning("Destabilizing effect of dominants. Relative effects cannot be computed.")
+
+    # Compensatory dynamics
+    sdsum <- sqrt(varsum)
+    rootPhi <- sdsum / sumsd
+
+    # Asynchrony effect
+    sumvar <- sum(vari)
+    beta <- log10(1/2) / (log10(sumvar / (sumsd^2)))
+    Psi <- rootPhi^beta
+
+    # averaging effect
+    omega <- rootPhi / Psi
+    if(omega > 1) warning("Community diversity is lower than the null diversity. Relative effects cannot be computed.")
+
+    # total stabilization
+    tau <- Delta * Psi * omega
+
+    # outputs
+    CVs <- stats::setNames(object = c(CVe, CVtilde, CVtilde * Psi, CV),
+                           nm = c("CVe", "CVtilde", "CVa", "CVc"))
+    Stabilization <- stats::setNames(object = c(tau, Delta, Psi, omega),
+                                     nm = c("tau", "Delta", "Psi", "omega"))
+    if(any(Stabilization > 1)){
+      Relative <- stats::setNames(object = rep(NA, 3),
+                                  nm = c("Delta_cont", "Psi_cont", "omega_cont"))
+    } else {
+      Relative <- stats::setNames(object = c(log10(Delta)/log10(tau), log10(Psi)/log10(tau), log10(omega)/log10(tau)),
+                                  nm = c("Delta_cont", "Psi_cont", "omega_cont"))
+    }
+
+    res <- list(CVs = CVs, Stabilization = Stabilization, Relative = Relative)
+    class(res) <- "comstab"
+    return(res)
+  }
 }
 
 #' @export
 print.comstab <- function(x, ...){
   cat("\nPartitionning of the community temporal variability (CV)")
-  cat("\nSee Segrestin et al. (2023)")
+  cat("\nSee Segrestin et al. (2024)")
   cat("\n")
   cat(paste0("Community CV = ", round(x$CVs["CVc"], 2),
              "\nTotal stabilization = ", round(x$Stabilization["tau"], 2),

R/ternStab.R

@@ -40,6 +40,7 @@
 
 ternStab <- function(x, ..., point = TRUE, add = FALSE){
   if(!inherits(x, 'comstab')) stop("x must be an object of class 'comstab'.")
+  if(any(is.na(x$Relative))) stop("Relative effects not found. This usually happens when a stabilizing effect is higher than 1.")
 
   # the relative contributions of each stabilizing components
   rel <- x$Relative

README.md

@@ -1,9 +1,11 @@
 comstab
 ================
+[![R-CMD-check](https://github.com/jsegrestin/comstab/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/jsegrestin/comstab/actions/workflows/R-CMD-check.yaml)
+[![DOI](https://zenodo.org/badge/608223971.svg)](https://zenodo.org/doi/10.5281/zenodo.10687005)
 
 `comstab` is an R package that contains basic functions to apply the
 unified framework for partitioning the drivers of stability of
-ecological communities (Segrestin <i>et al.</i> 2024).
+ecological communities (Segrestin <i>et al.</i> 2024 Global Ecology and Biogeography).
 
 ## Installation