Added and renamed 4 size overlap algorithms

NAMESPACE

@@ -13,7 +13,6 @@ export(cooc_null_model)
 export(czekanowski)
 export(czekanowski_skew)
 export(czekanowski_var)
-export(gamma_size)
 export(min_diff)
 export(min_ratio)
 export(niche_null_model)
@@ -38,11 +37,12 @@ export(sim7)
 export(sim8)
 export(sim9.fast)
 export(sim9.single)
+export(size_gamma)
 export(size_null_model)
-export(source_pool_draw)
+export(size_source_pool)
+export(size_uniform)
+export(size_uniform_user)
 export(species_combo)
-export(uniform_size)
-export(uniform_size_user)
 export(v_ratio)
 export(var_diff)
 export(var_ratio)

R/algorithms.R

@@ -542,34 +542,91 @@ ra4 <- function(speciesData=matrix(rpois(80,1),nrow=10))
 
   }
 
-
-#'Uniform size algorithm
-#'@description Function to randomize uniformly body sizes within  observed limits (classic Barton-David test)
+#' SizeUniform Size Overlap Randomization Algorithm
+#' @description Function to randomize body sizes within a uniform distribution
+#' with boundaries set by the largest and smallest species in the assemblage.
+#' @details If the assemblage contains n species,
+#' only the body sizes of the inner n - 2 species are randomized.
+#' @param speciesData a vector of positive real values representing the body
+#' sizes or trait values for each species.
+#' @return Returns a vector of body sizes that have been randomly assigned. The
+#' largest and smallest body sizes in the randomized assemblage match those in
+#' the empirical data.
+#' @references Simberloff, D. and W. Boecklen. 1981. Santa Rosalia
+#' reconsidered: size ratios and competition. Evolution 35: 1206-1228.
+#' 
+#' Tonkyn, D.W. and B.J. Cole. 1986. The statistical analysis of size ratios.
+#' American Naturalist 128: 66-81.
+#' @note Although the distribution of body sizes may not be truly uniform,
+#' it may be approximately uniform within the range of observed values,
+#' particularly for small assemblages. 
+#' @seealso \code{\link{size_gamma}} size distribution function.
+#' @examples 
+#' nullSizes <-size_uniform(speciesData=runif(20))
 #'@export
-uniform_size <- function(speciesData=runif(20)) {
+
+size_uniform <- function(speciesData=runif(20)) {
 
   endpoints <- c(min(speciesData),max(speciesData))  # save max and min boundaries
-  sim <- runif(n=(length(speciesData)-2),min=min(speciesData),max=max(speciesData))
+  sim <- runif(n=(length(speciesData)-2),min=endpoints[1],max=endpoints[2])
   randomVec <- c(endpoints,sim)
   return(randomVec)
 }
 
-#' User defined size limits
-#' @description Function to randomize uniformly body sizes within user-defined limits. Note that all n species are randomized in this algorithm
+#' SizeUser Size Overlap Randomization Algorithm
+#' @description Observed body sizes are randomized with a uniform distribution
+#' for which the user has defined the minimum and maximum possible body size.
+#' @details Within the user-defined limits, body sizes of all n species are
+#' randomized, whereas uniform_size randomizes only n - 2 of the body
+#' sizes and uses the extreme values to set the endpoints.
+#' @param speciesData a vector of observed body sizes.
+#' @param userLow a user-defined lower limit.
+#' @param userHigh a user-defined upper limit.
+#' @return Returns a vector of randomized body sizes.	
+#' @note As the difference between the lower and upper boundaries is increased
+#' the test will yield results that are random or aggregated, even though the 
+#' same data might yield a segregated pattern when the uniform_size algorithm
+#' is used. For this reason, this algorithm is not recommended for size ratio
+#' analyses.
+#' @seealso \code{\link{size_uniform}} size distribution algorithm.
+#' @examples 
+#' nullSizes <- uniform_size_user(speciesData=runif(20,min=10,max=20),userLow=8,userHigh=24)
 #' @export
-uniform_size_user <- function(speciesData=runif(n=20),userLow=0.9*min(speciesData),
+
+size_uniform_user <- function(speciesData=runif(n=20),userLow=0.9*min(speciesData),
                               userHigh=1.1*max(speciesData)){
 #  if(!is.null(Param.List$Special)){User.low <- Param.List$Special[1]
 #                                    User.high <- Param.List$Special[2]}
-  randomVec <- runif(n=length(speciesData),min=userLow,max=userHigh)
+  randomVec <- size_uniform_user(n=length(speciesData),min=userLow,max=userHigh)
 
   return(randomVec)
 }
 
-#' Source pool of body sizes
-#' @description Function to randomize body sizes by drawing from a user-defined source pool. Species are drawn without replacement, and there is a specified probability vector for the source pool species
+#' SizeSourcePoolDraw Size Overlap Randomization Algorithm
+#' @description Function to randomize body sizes by drawing species from a 
+#' user-defined source pool. Species are drawn without replacement, 
+#' and there is a specified probability vector for the source pool species
+
+#' @param speciesData a vector of observed body sizes.
+#' @param sourcePool a vector of body sizes of species in the user-defined
+#' pool of potential colonists.
+#' @param speciesProbs a vector of relative colonization weights of 
+#' length 'sourcePool'.
+#' @return Returns a vector of body sizes of an assemblage randomly drawn
+#' from a user-defined source pool.
+#' @references Strong, D.R. Jr., L.A. Szyska, and D. Simberloff. 1979. Tests of
+#' community-wide character displacement against null hypotheses. Evolution 33:
+#' 897-913.
+
+#' Schluter, D. and P.R. Grant. 1984. Determinants of morphological patterns in
+#' communities of Darwin's finches. American Naturalist 123: 175-196.
+#' @note Although delineating a source pool of species and estimating their
+#' relative colonization probabilities is difficult, this is the most realistic
+#' approach to constructing a null distribution.
+#' @examples 
+#' obsOverlap <- size_source_pool(speciesData=21:30,sourcePool= runif(n=2*length(speciesData),min=10,max=50), speciesProbs=rep(1,length(sourcePool)))
 #' @export
-source_pool_draw <- function(speciesData=21:30,sourcePool=
+size_source_pool <- function(speciesData=21:30,sourcePool=
                                runif(n=2*length(speciesData),min=10,max=50),
                              speciesProbs=rep(1,length(sourcePool))) {
 
@@ -609,4 +666,3 @@ size_gamma <- function (speciesData=rnorm(50,mean=100,sd=1)) {
 
   return(gammaDraw)
 }
-#' @export

man/size_gamma.Rd

@@ -0,0 +1,33 @@
+% Generated by roxygen2 (4.0.1): do not edit by hand
+\name{size_gamma}
+\alias{size_gamma}
+\title{SizeGamma Size Overlap Randomization Algorithm}
+\usage{
+size_gamma(speciesData = rnorm(50, mean = 100, sd = 1))
+}
+\arguments{
+\item{speciesData}{a vector of body sizes or other trait measurements of
+species. All values must be positive real numbers.}
+}
+\value{
+Returns a vector of simulated body sizes as the same length as speciesData.
+}
+\description{
+Function to generate a random distribution of body sizes by
+drawing from a gamma distribution. Shape and rate parameters of the gamma
+are estimated from the empirical data.
+}
+\note{
+The shape and rate parameters are estimated from the real data using
+the maximum likelihood estimators generated from the fitdr function in
+the MASS library. The flexible gamma distribution can be fit to a variety of
+normal, log-normal, and exponential distributions that are typical for trait
+data measured on a continuous non-negative scale.
+}
+\examples{
+obsOverlap <- size_gamma(speciesData=rnorm(50,mean=100,sd=1))
+}
+\seealso{
+\code{\link{fitdr}} in the MASS library.
+}
+

man/size_source_pool.Rd

@@ -0,0 +1,43 @@
+% Generated by roxygen2 (4.0.1): do not edit by hand
+\name{size_source_pool}
+\alias{size_source_pool}
+\title{SizeSourcePoolDraw Size Overlap Randomization Algorithm}
+\usage{
+size_source_pool(speciesData = 21:30, sourcePool = runif(n = 2 *
+  length(speciesData), min = 10, max = 50), speciesProbs = rep(1,
+  length(sourcePool)))
+}
+\arguments{
+\item{speciesData}{a vector of observed body sizes.}
+
+\item{sourcePool}{a vector of body sizes of species in the user-defined
+pool of potential colonists.}
+
+\item{speciesProbs}{a vector of relative colonization weights of
+length 'sourcePool'.}
+}
+\value{
+Returns a vector of body sizes of an assemblage randomly drawn
+from a user-defined source pool.
+}
+\description{
+Function to randomize body sizes by drawing species from a
+user-defined source pool. Species are drawn without replacement,
+and there is a specified probability vector for the source pool species
+}
+\note{
+Although delineating a source pool of species and estimating their
+relative colonization probabilities is difficult, this is the most realistic
+approach to constructing a null distribution.
+}
+\examples{
+obsOverlap <- size_source_pool(speciesData=21:30,sourcePool= runif(n=2*length(speciesData),min=10,max=50), speciesProbs=rep(1,length(sourcePool)))
+}
+\references{
+Strong, D.R. Jr., L.A. Szyska, and D. Simberloff. 1979. Tests of
+community-wide character displacement against null hypotheses. Evolution 33:
+897-913.
+Schluter, D. and P.R. Grant. 1984. Determinants of morphological patterns in
+communities of Darwin's finches. American Naturalist 123: 175-196.
+}
+

man/size_uniform.Rd

@@ -0,0 +1,43 @@
+% Generated by roxygen2 (4.0.1): do not edit by hand
+\name{size_uniform}
+\alias{size_uniform}
+\title{SizeUniform Size Overlap Randomization Algorithm}
+\usage{
+size_uniform(speciesData = runif(20))
+}
+\arguments{
+\item{speciesData}{a vector of positive real values representing the body
+sizes or trait values for each species.}
+}
+\value{
+Returns a vector of body sizes that have been randomly assigned. The
+largest and smallest body sizes in the randomized assemblage match those in
+the empirical data.
+}
+\description{
+Function to randomize body sizes within a uniform distribution
+with boundaries set by the largest and smallest species in the assemblage.
+}
+\details{
+If the assemblage contains n species,
+only the body sizes of the inner n - 2 species are randomized.
+}
+\note{
+Although the distribution of body sizes may not be truly uniform,
+it may be approximately uniform within the range of observed values,
+particularly for small assemblages.
+}
+\examples{
+nullSizes <-size_uniform(speciesData=runif(20))
+}
+\references{
+Simberloff, D. and W. Boecklen. 1981. Santa Rosalia
+reconsidered: size ratios and competition. Evolution 35: 1206-1228.
+
+Tonkyn, D.W. and B.J. Cole. 1986. The statistical analysis of size ratios.
+American Naturalist 128: 66-81.
+}
+\seealso{
+\code{\link{size_gamma}} size distribution function.
+}
+

man/size_uniform_user.Rd

@@ -0,0 +1,41 @@
+% Generated by roxygen2 (4.0.1): do not edit by hand
+\name{size_uniform_user}
+\alias{size_uniform_user}
+\title{SizeUser Size Overlap Randomization Algorithm}
+\usage{
+size_uniform_user(speciesData = runif(n = 20), userLow = 0.9 *
+  min(speciesData), userHigh = 1.1 * max(speciesData))
+}
+\arguments{
+\item{speciesData}{a vector of observed body sizes.}
+
+\item{userLow}{a user-defined lower limit.}
+
+\item{userHigh}{a user-defined upper limit.}
+}
+\value{
+Returns a vector of randomized body sizes.
+}
+\description{
+Observed body sizes are randomized with a uniform distribution
+for which the user has defined the minimum and maximum possible body size.
+}
+\details{
+Within the user-defined limits, body sizes of all n species are
+randomized, whereas uniform_size randomizes only n - 2 of the body
+sizes and uses the extreme values to set the endpoints.
+}
+\note{
+As the difference between the lower and upper boundaries is increased
+the test will yield results that are random or aggregated, even though the
+same data might yield a segregated pattern when the uniform_size algorithm
+is used. For this reason, this algorithm is not recommended for size ratio
+analyses.
+}
+\examples{
+nullSizes <- uniform_size_user(speciesData=runif(20,min=10,max=20),userLow=8,userHigh=24)
+}
+\seealso{
+\code{\link{size_uniform}} size distribution algorithm.
+}
+