version 1.4-4

cran · Sep 10, 2018 · a6d068e · a6d068e
1 parent 674ccc9
commit a6d068e
Show file tree

Hide file tree

Showing 30 changed files with 897 additions and 373 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,9 +1,9 @@
 Package: virtualspecies
 Type: Package
 Title: Generation of Virtual Species Distributions
-Version: 1.4-2
-Date: 2017-07-01
-Author: Boris Leroy, Christine N. Meynard, Celine Bellard and Franck Courchamp
+Version: 1.4-4
+Date: 2018-09-10
+Author: Boris Leroy [cre, aut], Christine N. Meynard [ctb], Celine Bellard [ctb], Franck Courchamp [ctb], Robin Delsol [ctb], Willson Gaul [ctb]
 Maintainer: Boris Leroy <leroy.boris@gmail.com>
 Description: Provides a framework for generating virtual species distributions,
     a procedure increasingly used in ecology to improve species distribution
@@ -12,11 +12,11 @@ Description: Provides a framework for generating virtual species distributions,
     realism.
 License: GPL (>= 2.0)
 Depends: raster
-Imports: ade4, dismo, graphics, grDevices, methods, rworldmap, stats,
+Imports: ade4, graphics, grDevices, methods, rworldmap, sp, stats,
         utils
 URL: http://borisleroy.com/virtualspecies
-RoxygenNote: 6.0.1
+RoxygenNote: 6.1.0
 NeedsCompilation: no
-Packaged: 2017-07-03 11:51:34 UTC; BorisMNHN
+Packaged: 2018-09-10 08:59:24 UTC; Farewell10
 Repository: CRAN
-Date/Publication: 2017-07-03 13:51:13 UTC
+Date/Publication: 2018-09-10 15:10:02 UTC
diff --git a/MD5 b/MD5
@@ -1,36 +1,37 @@
-f86766f35df8a4d42e9abda1150f3088 *DESCRIPTION
-96dcb550f105a0dfbc3fdd6901e8e0fa *NAMESPACE
-d342159cc65142aa279d0619349e7d2b *NEWS
-f558c06fca0d6fdfa8f3f4d60d9e98bc *R/convertToPA.R
-ce49154d58f5e93c908eae10d79aaa2d *R/formatFunctions.R
-8b4fe3586ac3e8fd8c4bfbdda5813bbf *R/generateRandomSp.R
-76a95c2bf239ad84cf3cbf211344c942 *R/generateSpFromBCA.R
-3d765a1ec95eabfbfbf06f8a023cf5ab *R/generateSpFromFun.R
-ba6ababc5336b4b6bd76ff29c336f25e *R/generateSpFromPCA.R
-853d84d2613d32b1facf0734f0943172 *R/genericfunctions.R
-90fd7843a54d65934bcf714beaf75560 *R/limitDistribution.R
-fcb90ae3b83402c834477df63ac2db52 *R/plotResponse.R
-6fb36003db1a9094fcbe80b6a65abaa1 *R/removeCollinearity.R
-9be6cc7f2b03a90c889bd026b6d2a540 *R/sampleOccurrences.R
-6963ca727b7f595ee1aba35ad6d52861 *R/sp.env.functions.R
+5f649a6a9f48b687ce9dddc97697a919 *DESCRIPTION
+5f4101c3517305580c97031a652858e4 *NAMESPACE
+ad1b5cf846b0c8770a80a0c0aeebef7a *NEWS
+61162f5a2fc7c05d974960d0fcc7586d *R/convertToPA.R
+1011145f8ea55c69597d1dcbd2309009 *R/formatFunctions.R
+463daad993b6b4adf3415f26f69a9b1b *R/generateRandomSp.R
+721f2b77b94763d39b891e72e29da1df *R/generateSpFromBCA.R
+d69e74e40fb9dba9d3bfc7d0bfa0638e *R/generateSpFromFun.R
+97f63384dd2ead3d4abe68f3ab63c068 *R/generateSpFromPCA.R
+33b47ca44152acf48db01776e9a19ed2 *R/genericfunctions.R
+24049629c3e8b6320d75a007fb021955 *R/limitDistribution.R
+8ca36ba1eae858fac03c1ad1f2802ccb *R/plotResponse.R
+73d567d59bd4fc06e42aa915d0b28f69 *R/removeCollinearity.R
+7cd36c3439ad28bfb57a9d462674d61f *R/sampleOccurrences.R
+ec22a004c2b14b46029b908bee6ce799 *R/sp.env.functions.R
 b15899277537256370881dc1485c9fd0 *R/synchroniseNA.R
 aae6ef3fc4f548f7c6ecc40d7a2e78fa *R/thermalFunctionDraft.R
-293c34f8ab11dcd4b2f76c177d52663f *R/virtualspecies-package.R
+a2b70eaf46bfc3bec906484369d08804 *R/utilityFunctions.R
+8079f60c6704cc0e1b92f48dc0de4e98 *R/virtualspecies-package.R
 ef811ca3f8bf933c1ac15f303aed9ce0 *inst/CITATION
-b242df4d91d9e87c20a9bcb74b5e2797 *man/betaFun.Rd
-f841263ec05fcf2e98148d5e7574db74 *man/convertToPA.Rd
+ada378869af7d494616910936570f04b *man/betaFun.Rd
+242e89685b6baa807fe605a930d3c1a9 *man/convertToPA.Rd
 6cf68e1d6295361f4b2cc08ada59678c *man/custnorm.Rd
-cdcc5b66c190a20808c6137f592aefb8 *man/formatFunctions.Rd
-e31f4c70496fbe367681aa4e198a5eaa *man/generateRandomSp.Rd
-e69e89a4b587a46a44811570e68a3767 *man/generateSpFromBCA.Rd
-a5a98a6b54f3887f7e6b81d3a4cdb107 *man/generateSpFromFun.Rd
-7c94c2a500426da08b3ed7e819eb30ff *man/generateSpFromPCA.Rd
-333cc6472e773547254fcf3de218036e *man/limitDistribution.Rd
+4c00f7eff53e20b398a340941e359687 *man/formatFunctions.Rd
+e8a93399c767b5af97e0bc735f06bbb3 *man/generateRandomSp.Rd
+3895d9b4fe9d164c4b80bc985e97caa8 *man/generateSpFromBCA.Rd
+b981a59621c574c855cb33482241e95c *man/generateSpFromFun.Rd
+f7597b74812ed1bd1843a350c7588ab5 *man/generateSpFromPCA.Rd
+365d324c599192e91855b8e5eb039f0c *man/limitDistribution.Rd
 cea125e4b6d7bfc151f6ff3db52a5ecb *man/linearFun.Rd
 1af79f8aec422c37a3b212ed120934cb *man/logisticFun.Rd
-ad12113562da0ccdefcfeeae55f626e6 *man/plotResponse.Rd
+3ca9a2681d776c1f8c248fd1aa950983 *man/plotResponse.Rd
 095b08a7b2bfd81c6d03235714756a12 *man/quadraticFun.Rd
-30b4a69e038f3a4887a0fe6d0f470ae0 *man/removeCollinearity.Rd
-10c9fe9b39e40b60daf7bafe4e1d841c *man/sampleOccurrences.Rd
+173063845130f09a570fdf8c287cfc09 *man/removeCollinearity.Rd
+705c2c5074d02c7eeafa31279a295d29 *man/sampleOccurrences.Rd
 2b343cf59df59fc9f32bcc485381a388 *man/synchroniseNA.Rd
-2770977a5e0f58328caed1eec59446c3 *man/virtualspecies-package.Rd
+196ee8dfe37067d044872fb960e82921 *man/virtualspecies-package.Rd
diff --git a/NAMESPACE b/NAMESPACE
@@ -1,7 +1,9 @@
 # Generated by roxygen2: do not edit by hand
 
 S3method(plot,virtualspecies)
+S3method(print,VSSampledPoints)
 S3method(print,virtualspecies)
+S3method(str,VSSampledPoints)
 S3method(str,virtualspecies)
 export(betaFun)
 export(convertToPA)

diff --git a/NEWS b/NEWS
@@ -1,3 +1,12 @@
+virtualspecies v1.4-4 (Release date: 2018-09-10)
+==============
+
+Changes:
+* Modified function sampleOccurrences (more features, better output)
+* Added new generic print / str functions for sampleOccurrences outputs
+* Improvements to generateSpFromBCA()
+* Fixed a bug in convertToPA() where the generation of low prevalence species would generate warnings and sometimes fail to obtain a proper beta threshold
+
 virtualspecies v1.4-1 (Release date: 2016-12-22)
 ==============
 

diff --git a/R/convertToPA.R b/R/convertToPA.R
@@ -101,7 +101,7 @@
 #' \item{\code{PA.conversion}: the parameters used to convert the suitability into presence-absence}
 #' \item{\code{pa.raster}: the presence-absence map, as a Raster object containing 0 (absence) / 1 (presence) / NA}
 #' }
-#' The structure of the virtualspecies object can be seen using str()
+#' The structure of the virtualspecies object can be seen using \code{str()}
 #' @examples
 #' # Create an example stack with two environmental variables
 #' a <- matrix(rep(dnorm(1:100, 50, sd = 25)), 

diff --git a/R/formatFunctions.R b/R/formatFunctions.R
@@ -2,7 +2,7 @@
 #' 
 #' @description
 #' This function is a helper function to simplify the formatting of functions
-#' for generateSpFromFun.
+#' for \code{\link{generateSpFromFun}}
 #' @details
 #' This function formats the \code{parameters} argument of \code{\link{generateSpFromFun}}.  
 #' For each environmental variable, provide a vector containing the function name, and its arguments.  

diff --git a/R/generateRandomSp.R b/R/generateRandomSp.R
@@ -26,7 +26,7 @@
 #' (may result in environmental conditions that do not co-exist).
 #' @param species.type [response approach] \code{"additive"} or \code{"multiplicative"}. Defines 
 #' how the final probability of presence is calculated: if \code{"additive"}, responses to each
-#' variable are summed; if \code{"multiplicative"}, responses are multiplicated.
+#' variable are summed; if \code{"multiplicative"}, responses are multiplied.
 #' See \code{\link{generateSpFromFun}}
 #' @param niche.breadth [pca approach] \code{"any"}, \code{"narrow"} or \code{"wide"}. This parameter
 #' defines how tolerant is the species regarding environmental conditions by adjusting
@@ -51,6 +51,9 @@
 #' \code{PA.method = "probability"}. The value of \code{alpha} will
 #' shape the logistic function transforming occurrences into presence-absences.
 #' See \code{\link{logisticFun}} and examples therein for the choice of \code{alpha}
+#' @param adjust.alpha \code{TRUE} or \code{FALSE}. Only useful if 
+#' \code{rescale = FALSE}. If  \code{adjust.alpha = TRUE}, then the value of \code{alpha} will
+#' be adjusted to an appropriate value  for the range of suitabilities.  
 #' @param species.prevalence \code{NULL} or a numeric value between 0 and 1.
 #' The species prevalence is the proportion of sites actually occupied by the
 #' species. See \code{\link{convertToPA}}
@@ -60,19 +63,19 @@
 #' a response approach. In case of a response approach, only four response functions are
 #' currently used: gaussian, linear, logistic and quadratic functions.
 #' 
-#' Note that in case of numerouse predictor variables, the "response" approach will
+#' Note that in case of numerous predictor variables, the "response" approach will
 #' not work well because it will often generate contradicting response functions 
 #' (e.g., mean annual temperature optimum at degrees C and temperature of the coldest month at
 #' 10 degrees C). In these case, it is advised to use the PCA approach (by default, a PCA approach
 #' will be used if there are more than 6 predictor variables).
 #' 
 #' If \code{rescale.each.response = TRUE}, then the probability response to each
 #' variable will be normalised between 0 and 1 according to the following formula:
-#' P.rescaled = (P - min(P)) / (max(P) - min (P)). Simlarly, if \code{rescale = TRUE},
+#' P.rescaled = (P - min(P)) / (max(P) - min (P)). Similarly, if \code{rescale = TRUE},
 #' the final environmental suitability will be rescaled between 0 and 1 with the same formula.
 #' 
 #' By default, the function will perform a probabilistic conversion into presence-
-#' absence, with a randomly chosen beta threshold. If you want to custmose the 
+#' absence, with a randomly chosen beta threshold. If you want to customise the 
 #' conversion parameters, you have to define \bold{two} of the three following parameters:
 #' \itemize{
 #' \item{\code{beta}: the 'threshold' of the logistic function (i.e. the 
@@ -104,7 +107,7 @@
 #' \item{\code{PA.conversion}: the parameters used to convert the suitability into presence-absence}
 #' \item{\code{pa.raster}: the presence-absence map, as a Raster object containing 0 (absence) / 1 (presence) / NA}
 #' }
-#' The structure of the virtualspecies can object be seen using str()
+#' The structure of the virtualspecies can object be seen using \code{str()}
 #' @examples
 #' # Create an example stack with six environmental variables
 #' a <- matrix(rep(dnorm(1:100, 50, sd = 25)), 
@@ -141,6 +144,7 @@ generateRandomSp <- function(raster.stack,
                              nb.points = 10000,
                              PA.method = "probability",
                              alpha = -.1,
+                             adjust.alpha = TRUE,
                              beta = "random",
                              species.prevalence = NULL,
                              plot = TRUE)
@@ -176,6 +180,7 @@ generateRandomSp <- function(raster.stack,
   if(approach == "pca")
   {
     results <- generateSpFromPCA(raster.stack,
+                                 rescale = rescale,
                                  niche.breadth = niche.breadth,
                                  sample.points = sample.points, 
                                  nb.points = nb.points,
@@ -274,26 +279,51 @@ generateRandomSp <- function(raster.stack,
       valid.cells <- valid.cells * (tmp.rast > 0.05)
     }
     message(" - Calculating species suitability\n")
-    results <- generateSpFromFun(raster.stack, parameters, species.type = species.type, plot = FALSE)
+    results <- generateSpFromFun(raster.stack, 
+                                 parameters, 
+                                 rescale = rescale,
+                                 species.type = species.type, 
+                                 plot = FALSE,
+                                 rescale.each.response = rescale.each.response)
   }
 
 
 
 
 
-  if(convert.to.PA == TRUE)
-  {
+  if(convert.to.PA == TRUE) {
     message(" - Converting into Presence - Absence\n")
-    results <- convertToPA(results, 
-                           PA.method = PA.method,
-                           alpha = alpha,
-                           beta = beta,
-                           species.prevalence = species.prevalence,
-                           plot = FALSE)
 
-    if(plot) plot(stack(results$suitab.raster, results$pa.raster), main = c("Suitability", "Presence-absence"))
-  } else
-  {
+    # Need to adjust alpha to appropriate scale if rescale = FALSE
+    if(rescale == FALSE) {
+      if(adjust.alpha)
+      {
+        alpha <- diff(c(minValue(results$suitab.raster),
+                        maxValue(results$suitab.raster))) * alpha
+      }
+      results <- convertToPA(results, 
+                             PA.method = PA.method,
+                             alpha = alpha,
+                             beta = beta,
+                             species.prevalence = species.prevalence,
+                             plot = FALSE)
+
+      if(plot) plot(stack(results$suitab.raster, 
+                          results$pa.raster), main = c("Suitability", 
+                                                       "Presence-absence"))
+    } else {
+
+      results <- convertToPA(results, 
+                             PA.method = PA.method,
+                             alpha = alpha,
+                             beta = beta,
+                             species.prevalence = species.prevalence,
+                             plot = FALSE)
+
+      if(plot) plot(stack(results$suitab.raster, results$pa.raster), 
+                    main = c("Suitability", "Presence-absence"))
+    }
+  } else {
     if(plot) plot(results$suitab.raster, main = "Suitability")
   }
 

diff --git a/R/generateSpFromBCA.R b/R/generateSpFromBCA.R
@@ -63,13 +63,13 @@
 #' a fraction of the axis:
 #' \itemize{
 #' \item{\code{"any"}: the standard deviations can have values from 1\% to 50\% of axes' ranges. For example if the first axis of the PCA ranges from -5 to +5,
-#' then sd values along this axe can range from 0.1 to 5.
+#' then sd values along this axis can range from 0.1 to 5.
 #' }
 #' \item{\code{"narrow"}: the standard deviations are limited between 1\% and 10\% of axes' ranges. For example if the first axis of the PCA ranges from -5 to +5,
-#' then sd values along this axe can range from 0.1 to 1.
+#' then sd values along this axis can range from 0.1 to 1.
 #' }
 #' \item{\code{"wide"}: the standard deviations are limited between 10\% and 50\% of axes' ranges. For example if the first axis of the PCA ranges from -5 to +5,
-#' then sd values along this axe can range from 1 to 5.
+#' then sd values along this axis can range from 1 to 5.
 #' }
 #' }
 #' If a \code{bca} object is provided, the output bca object will contain the new environments coordinates along the provided bca axes.
@@ -86,7 +86,7 @@
 #' \item{\code{suitab.raster.future}: the virtual species distribution, as a Raster object containing the
 #' future environmental suitability}
 #' }
-#' The structure of the virtualspecies object can be seen using str()
+#' The structure of the virtualspecies object can be seen using \code{str()}
 #' 
 #' 
 #' 
@@ -367,6 +367,6 @@ generateSpFromBCA <- function(raster.stack.current, raster.stack.future, rescale
                                  stack.lengths = stack.lengths),
                   suitab.raster.current = suitab.raster.current,
                   suitab.raster.future = suitab.raster.future)
-  class(results) <- append(class(results), "virtualspecies")
+  class(results) <- append("virtualspecies", class(results))
   return(results)
 }
diff --git a/R/generateSpFromFun.R b/R/generateSpFromFun.R
@@ -14,7 +14,7 @@
 #' \code{species.type}
 #' @param species.type \code{"additive"} or \code{"multiplicative"}. Only used if \code{formula = NULL}. 
 #' Defines how the final environmental suitability is calculated: if \code{"additive"}, responses to each
-#' variable are summed; if \code{"multiplicative"}, responses are multiplicated.
+#' variable are summed; if \code{"multiplicative"}, responses are multiplied.
 #' @param rescale.each.response \code{TRUE} or \code{FALSE}. If \code{TRUE}, the individual responses to
 #' each environmental variable are rescaled between 0 and 1 (see details).
 #' @param plot \code{TRUE} or \code{FALSE}. If \code{TRUE}, the generated virtual species will be plotted.
@@ -24,7 +24,7 @@
 #' \item{\code{details}: the details and parameters used to generate the species}
 #' \item{\code{suitab.raster}: the raster containing the environmental suitability of the virtual species}
 #' }
-#' The structure of the virtualspecies object can be seen using str()
+#' The structure of the virtualspecies object can be seen using \code{str()}
 #' @seealso \code{\link{generateSpFromPCA}} to generate a virtual species with a PCA approach
 #' @details
 #' This functions proceeds into several steps:
@@ -57,8 +57,8 @@
 #' Any response function that can be applied to the environmental variables can
 #' be chosen here. Several functions are proposed in this package:
 #' \code{\link{linearFun}}, \code{\link{logisticFun}} and \code{\link{quadraticFun}}.
-#' Another classical example is the normal distribution: \code{\link[stats]{dnorm}}.
-#' Ther users can also create and use their own functions.
+#' Another classical example is the normal distribution: \code{\link[stats:Normal]{stats::dnorm()}}.
+#' Users can also create and use their own functions very easily.
 #' 
 #'   
 #' If \code{rescale.each.response = TRUE}, then the probability response to each
@@ -238,7 +238,7 @@ generateSpFromFun <- function(raster.stack, parameters,
     plot(results$suitab.raster, main = "Environmental suitability of the virtual species")
   }
 
-  class(results) <- append(class(results), "virtualspecies")
+  class(results) <- append("virtualspecies", class(results))
 
   return(results)
 }
diff --git a/R/generateSpFromPCA.R b/R/generateSpFromPCA.R
@@ -50,13 +50,13 @@
 #' a fraction of the axis:
 #' \itemize{
 #' \item{\code{"any"}: the standard deviations can have values from 1\% to 50\% of axes' ranges. For example if the first axis of the PCA ranges from -5 to +5,
-#' then sd values along this axe can range from 0.1 to 5.
+#' then sd values along this axis can range from 0.1 to 5.
 #' }
 #' \item{\code{"narrow"}: the standard deviations are limited between 1\% and 10\% of axes' ranges. For example if the first axis of the PCA ranges from -5 to +5,
-#' then sd values along this axe can range from 0.1 to 1.
+#' then sd values along this axis can range from 0.1 to 1.
 #' }
 #' \item{\code{"wide"}: the standard deviations are limited between 10\% and 50\% of axes' ranges. For example if the first axis of the PCA ranges from -5 to +5,
-#' then sd values along this axe can range from 1 to 5.
+#' then sd values along this axis can range from 1 to 5.
 #' }
 #' }
 #' @import raster
@@ -76,7 +76,7 @@
 #' \item{\code{suitab.raster}: the virtual species distribution, as a Raster object containing the
 #' environmental suitability}
 #' }
-#' The structure of the virtualspecies object can be seen using str()
+#' The structure of the virtualspecies object can be seen using \code{str()}
 #' @examples
 #' # Create an example stack with four environmental variables
 #' a <- matrix(rep(dnorm(1:100, 50, sd = 25)), 
@@ -293,7 +293,7 @@ generateSpFromPCA <- function(raster.stack, rescale = TRUE, niche.breadth = "any
                                  means = means,
                                  sds = sds),
                   suitab.raster = suitab.raster)
-  class(results) <- append(class(results), "virtualspecies")
+  class(results) <-  append("virtualspecies", class(results))
   return(results)
 }