├── .Rbuildignore ├── .gitignore ├── .travis.yml ├── CITATION ├── DESCRIPTION ├── LICENSE ├── NAMESPACE ├── R ├── EcoSimR-package.r ├── algorithms.R ├── coccurrence_null.R ├── metrics.R ├── niche_overlap_null.R ├── null_model_engine.R ├── randomMatrixGenerator.R ├── reproduce_model.R ├── sim9fast.R └── sizeratio_null.R ├── README.md ├── appveyor.yml ├── data └── datasets.rda ├── inst ├── CITATION ├── burnin.png ├── cooc.png ├── cooc_hist.png ├── niche.png ├── niche_hist.png ├── size.png └── size_hist.png ├── man ├── EcoSimR.Rd ├── c_score.Rd ├── c_score_skew.Rd ├── c_score_var.Rd ├── checker.Rd ├── cooc_null_model.Rd ├── czekanowski.Rd ├── czekanowski_skew.Rd ├── czekanowski_var.Rd ├── dataMacWarb.Rd ├── dataRodents.Rd ├── dataWiFinches.Rd ├── min_diff.Rd ├── min_ratio.Rd ├── niche_null_model.Rd ├── null_model_engine.Rd ├── pianka.Rd ├── pianka_skew.Rd ├── pianka_var.Rd ├── plot.coocnullmod.Rd ├── plot.nichenullmod.Rd ├── plot.nullmod.Rd ├── plot.sizenullmod.Rd ├── ra1.Rd ├── ra2.Rd ├── ra3.Rd ├── ra4.Rd ├── ranMatGen.Rd ├── reproduce_model.Rd ├── sim1.Rd ├── sim10.Rd ├── sim2.Rd ├── sim3.Rd ├── sim4.Rd ├── sim5.Rd ├── sim6.Rd ├── sim7.Rd ├── sim8.Rd ├── sim9.Rd ├── sim9_single.Rd ├── size_gamma.Rd ├── size_null_model.Rd ├── size_source_pool.Rd ├── size_uniform.Rd ├── size_uniform_user.Rd ├── species_combo.Rd ├── summary.coocnullmod.Rd ├── summary.nichenullmod.Rd ├── summary.nullmod.Rd ├── summary.sizenullmod.Rd ├── v_ratio.Rd ├── var_diff.Rd ├── var_ratio.Rd └── vector_sample.Rd ├── tests ├── testthat.R └── testthat │ ├── test_cooccurrence.R │ ├── test_nichebreadth.R │ └── test_sizeratio.R └── vignettes ├── CoOccurrenceVignette.Rmd ├── SizeRatioVignette.Rmd ├── nicheOverlapVignette.Rmd └── nullModelPlug-Ins.Rmd /.Rbuildignore: -------------------------------------------------------------------------------- 1 | ^.*\.Rproj$ 2 | ^\.Rproj\.user$ 3 | .travis.yml 4 | appveyor.yml 5 | .Rhistory 6 | .RData 7 | .gitignore 8 | README.md 9 | 10 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .Rhistory 2 | outputs_local 3 | .Rproj.user 4 | EcoSimR.Rproj 5 | .RData 6 | tmp.R 7 | dev.R 8 | .DS_Store 9 | EcoSimR.Rcheck/ 10 | *.gz 11 | *check/ 12 | *~ 13 | *.swp 14 | sync_site.sh 15 | inst/doc 16 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: r 2 | 3 | after_failure: 4 | - "./travis-tool.sh dump_logs" 5 | - Rscript -e 'library(covr);coveralls()' 6 | 7 | before_script: 8 | - Rscript -e "install.packages('knitr',repos='http://cran.cnr.Berkeley.edu/')" 9 | - Rscript -e "install.packages('rmarkdown',repos='http://cran.cnr.Berkeley.edu/')" 10 | 11 | 12 | after_success: 13 | - Rscript -e 'library(covr);coveralls()' -------------------------------------------------------------------------------- /CITATION: -------------------------------------------------------------------------------- 1 | 2 | citEntry(entry = "Manual", 3 | title = "EcoSimR: Null model analysis for ecological data", 4 | author = "Nicholas J. Gotelli and Edmund M. Hart and Aaron M. Ellison", 5 | year = "2015", 6 | note = "R package version 0.1.0", 7 | url = "http://github.com/gotellilab/EcoSimR", 8 | doi = "10.5281/zenodo.16522", 9 | 10 | textVersion = 11 | paste("Nicholas J. Gotelli, Edmund M. Hart and Aaron M. Ellison (2015) EcoSimR: Null model analysis for ecological data. R package version 0.1.0. http://github.com/gotellilab/EcoSimR DOI: 10.5281/zenodo.16522") 12 | ) -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: EcoSimR 2 | Type: Package 3 | Title: Null Model Analysis for Ecological Data 4 | Version: 0.1.0 5 | Date: 2015-04-02 6 | BugReports: https://github.com/GotelliLab/EcoSimR/issues 7 | Authors@R: c(person("Nick", "Gotelli", role = c("aut"), 8 | email = "ngotelli@uvm.edu"), 9 | person("Edmund", "Hart", role = c("aut","cre"), 10 | email = "edmund.m.hart@gmail.com"), 11 | person("Aaron", "Ellison", role = c("aut"), 12 | email = "aellison@fas.harvard.edu") ) 13 | LazyLoad: yes 14 | LazyData: yes 15 | Description: Given a site by species interaction matrix, users can make inferences about species interactions by performance hypothesis comparing test statistics against a null distribution. The current package provides algorithms and metrics for niche-overlap, body size ratios and species co-occurrence. Users can also integrate their own algorithms and metrics within these frameworks or completely novel null models. Detailed explanations about the underlying assumptions of null model analysis in ecology can be found at http://ecosimr.org. 16 | License: MIT + file LICENSE 17 | Depends: 18 | MASS 19 | Suggests: 20 | testthat, 21 | knitr 22 | VignetteBuilder: knitr 23 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | YEAR: 2015 2 | COPYRIGHT HOLDER: Nicholas Gotelli, Edmund Hart and Aaron Ellison -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | # Generated by roxygen2 (4.1.0): do not edit by hand 2 | 3 | S3method(plot,coocnullmod) 4 | S3method(plot,nichenullmod) 5 | S3method(plot,nullmod) 6 | S3method(plot,sizenullmod) 7 | S3method(summary,coocnullmod) 8 | S3method(summary,nichenullmod) 9 | S3method(summary,nullmod) 10 | S3method(summary,sizenullmod) 11 | export(c_score) 12 | export(c_score_skew) 13 | export(c_score_var) 14 | export(checker) 15 | export(cooc_null_model) 16 | export(czekanowski) 17 | export(czekanowski_skew) 18 | export(czekanowski_var) 19 | export(min_diff) 20 | export(min_ratio) 21 | export(niche_null_model) 22 | export(null_model_engine) 23 | export(pianka) 24 | export(pianka_skew) 25 | export(pianka_var) 26 | export(ra1) 27 | export(ra2) 28 | export(ra3) 29 | export(ra4) 30 | export(ranMatGen) 31 | export(reproduce_model) 32 | export(sim1) 33 | export(sim10) 34 | export(sim2) 35 | export(sim3) 36 | export(sim4) 37 | export(sim5) 38 | export(sim6) 39 | export(sim7) 40 | export(sim8) 41 | export(sim9) 42 | export(sim9_single) 43 | export(size_gamma) 44 | export(size_null_model) 45 | export(size_source_pool) 46 | export(size_uniform) 47 | export(size_uniform_user) 48 | export(species_combo) 49 | export(v_ratio) 50 | export(var_diff) 51 | export(var_ratio) 52 | export(vector_sample) 53 | import(MASS) 54 | -------------------------------------------------------------------------------- /R/EcoSimR-package.r: -------------------------------------------------------------------------------- 1 | #' EcoSimR 2 | #' EcoSimR is a collection of functions for calculating community metrics and algorithms for randomizing community data for null model analysis. Current modules are included for the analysis of niche overlap, body size overlap, and species co-occurrence. EcoSimR also allows users to define their own functions and algorithms to develop new null models. 3 | #' @name EcoSimR 4 | #' @docType package 5 | NULL 6 | 7 | #' MacArthur's (1958) warbler data 8 | #' This data matrix is from MacArthur's classic (1958) paper on the coexistence of 5 species of New England warbler. Each row of the data matrix is a different species of warbler, and each column is one of 16 different subregions of a coniferous tree. Each entry is the percentage of time that each species was observed foraging in a different subregion of the tree (see Figures 2-4 in MacArthur 1958). Zeroes indicate subregions of the tree in which a species was not recorded foraging. 9 | #' @references MacArthur, R.H. 1958. Population ecology of some warblers of northeastern coniferous forests. Ecology 39: 599-699. 10 | #' @name dataMacWarb 11 | #' @docType data 12 | #' @keywords datasets 13 | #' @keywords data 14 | NULL 15 | 16 | #' West Indian Finches data 17 | #' This data frame is a binary presence-absence matrix for West Indies finches (Fringillidae). Each row is a different species of finch and each column is one of the 19 major islands in the West Indies. Entries indicate the presence (1) or absence (0) of a species on an island. Data from Gotelli and Abele (1982). 18 | #' @references Gotelli, N.J. and L.G. Abele. 1982. Statistical distributions of West Indian land bird families. Journal of Biogeography 9: 421-435. 19 | #' @name dataWiFinches 20 | #' @docType data 21 | #' @keywords datasets 22 | #' @keywords data 23 | NULL 24 | 25 | #' Desert rodent data set 26 | #' This data vector is from Brown's (1975) study of the coexistence of desert rodent species. Each entry is the average adult body mass in grams of six co-occurring species of Sonoran Desert rodents. 27 | #' @references Brown, J.H. 1975. Geographical ecology of desert rodents. p. 314-341 in: Ecology and Evolution of Communities. M.L. Cody and J.M. Diamond (eds.). Harvard University Press, Cambridge. 28 | #' @name dataRodents 29 | #' @docType data 30 | #' @keywords datasets 31 | #' @keywords data 32 | NULL -------------------------------------------------------------------------------- /R/coccurrence_null.R: -------------------------------------------------------------------------------- 1 | #'Co-Occurrence Null model 2 | #'@description Create a Co-Occurrence null model 3 | #'@param speciesData a dataframe in which rows are species, columns are sites, 4 | #' and the entries indicate the absence (0) or presence (1) of a species in a 5 | #' site. Empty rows and empty columns should not be included in the matrix. 6 | #'@param algo the algorithm to use, must be "sim1", "sim2", "sim3", "sim4", "sim5", "sim6", "sim7", "sim8", "sim9", "sim10"; default is "sim9". 7 | #'@param metric the metric used to calculate the null model: choices are "species_combo", "checker", "c_score", "c_score_var", "c_score_skew", "v_ratio"; default is "c_score". 8 | #'@param nReps the number of replicate null assemblages to create; default is 1000 replicates. 9 | #'@param saveSeed TRUE or FALSE. If TRUE the current seed is saved so the simulation can be repeated; default is FALSE. 10 | #'@param burn_in The number of burn_in iterations to use with the simFast algorithm; default is 500 burn-in replicates. 11 | #'@param algoOpts a list containing all the options for the specific algorithm you want to use. Must match the algorithm given in the `algo` argument. 12 | #'@param metricOpts a list containing all the options for the specific metric you want to use. Must match the metric given in the `metric` argument. 13 | #'@param suppressProg TRUE or FALSE. If true, display of the progress bar in the console is suppressed; default is FALSE. This setting is useful for creating markdown documents with `knitr`. 14 | #'@examples \dontrun{ 15 | #' 16 | #' ## Run the null model 17 | #' finchMod <- cooc_null_model(dataWiFinches, algo="sim9",nReps=10000,burn_in = 500) 18 | #' ## Summary and plot info 19 | #' summary(finchMod) 20 | #' plot(finchMod,type="burn_in") 21 | #' plot(finchMod,type="hist") 22 | #' plot(finchMod,type="cooc") 23 | #' 24 | #' ## Example that is repeatable with a saved seed 25 | #' finchMod <- cooc_null_model(dataWiFinches, algo="sim1",saveSeed = TRUE) 26 | #' mean(finchMod$Sim) 27 | #' ## Run the model with the seed saved 28 | #' 29 | #' finchMod <- cooc_null_model(dataWiFinches, algo="sim1",saveSeed=T) 30 | #' ## Check model output 31 | #' mean(finchMod$Sim) 32 | #' 33 | #' reproduce_model(finchMod) 34 | #' 35 | #' finchMod <- cooc_null_model(dataWiFinches, algo="sim1") 36 | #' ## Check model output is the same as before 37 | #' mean(finchMod$Sim) 38 | #' reproduce_model(finchMod) 39 | #' 40 | #' 41 | #'} 42 | #' 43 | #'@export 44 | 45 | cooc_null_model <- function(speciesData, algo = "sim9", metric = "c_score", nReps = 1000, saveSeed = FALSE, burn_in = 500,algoOpts = list(),metricOpts = list(),suppressProg = FALSE){ 46 | aChoice <- c(paste("sim",c(1:10),sep="")) 47 | mChoice <- c("species_combo", "checker", "c_score", "c_score_var", "c_score_skew", "v_ratio") 48 | 49 | algo <- match.arg(algo,choices = aChoice) 50 | metric <- match.arg(metric,choices = mChoice) 51 | ## Control behavior of whether or not sim9fast is used. 52 | if(algo != "sim9"){ 53 | params <- list(speciesData = speciesData, algo = algo, metric = metric, nReps = nReps, saveSeed 54 | = saveSeed 55 | ,algoOpts = algoOpts,metricOpts = metricOpts,suppressProg = suppressProg) 56 | output <- do.call(null_model_engine,params) 57 | output$burn.in <- burn_in 58 | class(output) <- "coocnullmod" 59 | return(output) 60 | } else if(algo == "sim9"){ 61 | params <- list(speciesData = speciesData,algo = algo, metric = metric, nReps = nReps, saveSeed = saveSeed, burn_in = burn_in, suppressProg = suppressProg) 62 | output <- do.call(sim9,params) 63 | class(output) <- "coocnullmod" 64 | return(output) 65 | } 66 | 67 | 68 | } 69 | 70 | 71 | #' Generic function for calculating null model summary statistics. 72 | #' @description Takes as input a list of Null.Model.Out, with Obs, Sim, Elapsed Time, and Time Stamp values. 73 | #' @param object the null model object to print a summary. 74 | #' @param ... extra parameters 75 | #' @details The summary output includes a timestamp and complete statistics on the simulated values of the metric, including the mean, variance, and one and two-tailed 95% confidence intervals. The lower and upper tails for the observed value are given, as is the standardized effect size (SES), which is calculated as the (Metric(obs) - average(Metric(sim)))/(standard deviation(Metric(sim))). Large positive values (or negative) values indicate that the observed metric is significantly larger (or smaller) than predicted by the null model. If the distribution of errors is approximately normal, then non-significant values will fall roughly within +- two SES values. 76 | #' @export 77 | 78 | summary.coocnullmod <- function(object,...) 79 | { 80 | nullmodObj <- object 81 | cat("Time Stamp: " , nullmodObj$Time.Stamp, "\n") 82 | cat("Reproducible: ",nullmodObj$Reproducible, "\n") 83 | cat("Number of Replications: ",nullmodObj$nReps, "\n") 84 | cat("Elapsed Time: ", nullmodObj$Elapsed.Time, "\n") 85 | cat("Metric: ", nullmodObj$Metric, "\n") 86 | cat("Algorithm: ", nullmodObj$Algorithm, "\n") 87 | 88 | cat("Observed Index: ", format(nullmodObj$Obs,digits=5), "\n") 89 | cat("Mean Of Simulated Index: ",format(mean(nullmodObj$Sim),digits=5), "\n") 90 | cat("Variance Of Simulated Index: ",format(var(nullmodObj$Sim),digits=5), "\n") 91 | cat("Lower 95% (1-tail): ",format(quantile(nullmodObj$Sim,0.05),digits=5), "\n") 92 | cat("Upper 95% (1-tail): ",format(quantile(nullmodObj$Sim,0.95),digits=5), "\n") 93 | cat("Lower 95% (2-tail): ",format(quantile(nullmodObj$Sim,0.025),digits=5), "\n") 94 | cat("Upper 95% (2-tail): ",format(quantile(nullmodObj$Sim,0.975),digits=5), "\n") 95 | 96 | #P-values 97 | if (nullmodObj$Obs > max(nullmodObj$Sim)) { 98 | cat("Lower-tail P > ",(length(nullmodObj$Sim) - 1)/length(nullmodObj$Sim), "\n") 99 | cat("Upper-tail P < ",1/length(nullmodObj$Sim), "\n") 100 | } else if(nullmodObj$Obs < min(nullmodObj$Sim)) { 101 | cat("Lower-tail P > ", 1/length(nullmodObj$Sim), "\n") 102 | cat("Upper-tail P < ",(length(nullmodObj$Sim) - 1)/length(nullmodObj$Sim), "\n") 103 | } else { 104 | cat("Lower-tail P = ", format(sum(nullmodObj$Obs >= nullmodObj$Sim)/length(nullmodObj$Sim),digits=5), "\n") 105 | cat("Upper-tail P = ", format(sum(nullmodObj$Obs <= nullmodObj$Sim)/length(nullmodObj$Sim),digits=5), "\n") 106 | } 107 | 108 | cat(paste("Observed metric > ",sum(nullmodObj$Obs > nullmodObj$Sim)," simulated metrics",sep=""), "\n") 109 | cat(paste("Observed metric < ",sum(nullmodObj$Obs < nullmodObj$Sim)," simulated metrics",sep=""), "\n") 110 | cat(paste("Observed metric = ",sum(nullmodObj$Obs == nullmodObj$Sim)," simulated metrics",sep="") , "\n") 111 | cat("Standardized Effect Size (SES): ", format((nullmodObj$Obs - mean(nullmodObj$Sim))/sd(nullmodObj$Sim),digits=5), "\n") 112 | 113 | #if(!is.null(Output.File)) close(outfile) 114 | } 115 | 116 | 117 | 118 | 119 | #' Co-Occurrence Model Plot Function 120 | #' @description Plot co-occurrence null model object. 121 | #' @param x the null model object to plot. 122 | #' @param type the type of null plot to make. See details for more information. 123 | #' @param ... Other variables to be passed on to base plotting. 124 | #' @details the valid types for the Co-occurrence module are "hist" to display a histogram of the simulated metric values, "cooc" to display the observed data matrix and one simulated matrix, and (for sim9 only), "burn_in" to display a trace of the metric values during the burn-in period. 125 | #' 126 | #' The "hist" plot type is common to all EcoSimR modules. The blue histogram represents the NRep values of the metric for the simulated assemblages. The red vertical line represents the metric value for the real assemblage. The two pairs of vertical dashed black lines represent the one-tailed (long dash) and two-tailed (short dash) 95% confidence exact confidence intervals of the simulated data. 127 | #' 128 | #' The "cooc" plot type illustrates the binary presence-absence data (observed = red, simulated = blue). Each row in the grid is a species, each column is a site, and the entries represent the presence (color-filled) or absence (empty) of a species in a site. The rows and columns are illustrated with the same ordering as the original data matrix. 129 | #' 130 | #' The "burn_in" plot type illustrates the trace values of the metric generated for sim9 during the burn-in period. The x axis is the replicate number and the y axis is the value of the metric. The metric for the original data matrix is illustrated as a horizontal red line. Consecutive simulated metric values are illustrated with a blue line, and the gray line is a simple loess fit to the simulated values. If the burn_in period is sufficiently long, the trace should be stable, indicating that a stationary distribution has probably been reached. 131 | #' 132 | #' @export 133 | 134 | 135 | 136 | plot.coocnullmod <- function(x, type = "hist",...) 137 | { 138 | nullmodObj <- x 139 | 140 | if(type == "cooc"){ 141 | Date.Stamp=date() 142 | par(mfrow=c(1,2)) 143 | 144 | # reverse the matrix rows for plotting consistency 145 | m <- nullmodObj$Randomized.Data 146 | m <- m[rev(1:nrow(m)),] 147 | 148 | # setup plotting space 149 | 150 | plot(m,xlim=c(0,ncol(m)),ylim=c(0,nrow(m)),type="n",ann=FALSE,axes=FALSE) 151 | mtext("Sites",side=1,font=2) 152 | mtext("Species",side=2,font=2) 153 | mtext("Simulated",side=3,font=2,col="royalblue3") 154 | # define coordinate vectors 155 | yrec <- rep(0:(nrow(m)-1),ncol(m)) 156 | xrec <- rep(0:(ncol(m)-1),each=nrow(m)) 157 | 158 | # Set up color labels 159 | Plot.cols <- c("white","royalblue3") 160 | Color.Vector <- Plot.cols[as.integer(m)+1] 161 | 162 | # Plot and fill rectangles 163 | rect(xrec,yrec,xrec+1,yrec+1,col=Color.Vector) 164 | 165 | 166 | mtext(as.character(Date.Stamp),side=3,adj=1,line=3) 167 | # reverse the matrix rows for plotting consistency 168 | m <- nullmodObj$Data 169 | m <- m[rev(1:nrow(m)),] 170 | 171 | # setup plotting space 172 | 173 | plot(m,xlim=c(0,ncol(m)),ylim=c(0,nrow(m)),type="n", 174 | ann=FALSE,axes=FALSE) 175 | mtext("Sites",side=1,font=2) 176 | mtext("Species",side=2,font=2) 177 | mtext("Observed",side=3,font=2,col="red3") 178 | # define coordinate vectors 179 | yrec <- rep(0:(nrow(m)-1),ncol(m)) 180 | xrec <- rep(0:(ncol(m)-1),each=nrow(m)) 181 | 182 | # Set up color labels 183 | Plot.cols <- c("white","red3") 184 | Color.Vector <- Plot.cols[as.integer(m)+1] 185 | 186 | # Plot and fill rectangles 187 | rect(xrec,yrec,xrec+1,yrec+1,col=Color.Vector) 188 | } 189 | 190 | if(type == "hist"){ 191 | opar <- par(no.readonly=TRUE) 192 | par(mfrow=c(1,1)) 193 | par(cex=1, cex.axis = 1.5, 194 | cex.main=1,cex.lab=1.6) 195 | par (mar=c(5,6,4,2)+0.1) 196 | hist(nullmodObj$Sim, breaks=20, col="royalblue3", 197 | xlab="Simulated Metric",ylab="Frequency",main="", xlim=range(c(nullmodObj$Sim,nullmodObj$Obs))) 198 | abline(v=nullmodObj$Obs,col="red",lty="solid",lwd=2.5) 199 | abline(v=quantile(nullmodObj$Sim,c(0.05,0.95)),col="black",lty="dashed",lwd=2.5) 200 | abline(v=quantile(nullmodObj$Sim,c(0.025,0.975)),col="black",lty="dotted",lwd=2.5) 201 | mtext(as.character(date()),side=3,adj=1,line=3) 202 | 203 | } 204 | 205 | if(type=="burn_in"){ 206 | if(is.na(nullmodObj$burn.in)){ 207 | warning("You can only create a burn_in plot for a model run with the 'simFast' algorithm") 208 | 209 | } 210 | par(mfrow=c(1,1)) 211 | v <- nullmodObj$burn.in.metric 212 | z <- nullmodObj$Obs 213 | v <- c(z,v) 214 | plot(x=1:length(v),y=v,xlab="Iteration",ylab="Index", 215 | las=1,type="l",col="royalblue3") 216 | abline(h=z,col="red3") 217 | lines(lowess(1:length(v),v), col="gray",lwd=4) # lowess line (x,y) 218 | 219 | } 220 | 221 | } 222 | -------------------------------------------------------------------------------- /R/niche_overlap_null.R: -------------------------------------------------------------------------------- 1 | #'Niche overlap null models 2 | #'@description Create a null model for niche overlap; choices of algorithm and metric are constrained to be valid for niche null models. 3 | #'@param speciesData a data frame in which each row is a species, each column is a resource utilization category, and the entries represent the quantity of the resource used by each species. Examples might be the amount of time a species spends foraging in different microhabitats, the biomass of different prey types, or counts of the number of times an adult female oviposits eggs on different species of a host plant. 4 | #'@param algo the algorithm to use, must be "ra1", "ra2", "ra3", "ra4"; default is "ra3". 5 | #'@param metric the metric used to calculate the null model: choices are "pianka", "czekanowski", "pianka_var", "czekanowski_var", "pianka_skew", "czekanowski_skew"; default is "pianka". 6 | ##'@param nReps the number of replicate null assemblages to create; default is 1000 replicates. 7 | #'@param saveSeed TRUE or FALSE. If TRUE the current seed is saved so the simulation can be repeated; default is FALSE. 8 | #'@param algoOpts a list containing all the options for the specific algorithm you want to use. Must match the algorithm given in the `algo` argument. 9 | #'@param metricOpts a list containing all the options for the specific metric you want to use. Must match the metric given in the `metric` argument. 10 | #'@param suppressProg TRUE or FALSE. If true, display of the progress bar in the console is suppressed; default is FALSE. This setting is useful for creating markdown documents with `knitr`. 11 | #'@examples \dontrun{ 12 | #' ## Load MacAruthur warbler data 13 | #' data(dataMacWarb) 14 | #' 15 | #' ## Run the null model 16 | #' warbMod <- niche_null_model(dataMacWarb,nReps=1000) 17 | #' ## Summary and plot info 18 | #' summary(warbMod) 19 | #' plot(warbMod) 20 | #' plot(warbMod,type="niche") 21 | #'} 22 | #' 23 | #'@export 24 | 25 | niche_null_model <- function(speciesData, algo = "ra3", metric = "pianka", nReps = 1000,saveSeed=FALSE,algoOpts = list(),metricOpts = list(),suppressProg = FALSE){ 26 | 27 | aChoice <- c("ra1","ra2","ra3","ra4") 28 | mChoice<- c("pianka", "czekanowski", "pianka_var", "czekanowski_var", "pianka_skew", "czekanowski_skew") 29 | algo <- match.arg(algo,choices = aChoice) 30 | metric <- match.arg(metric,choices = mChoice) 31 | params <- list(speciesData = speciesData, algo = algo, metric = metric, nReps = nReps, saveSeed = saveSeed,algoOpts = algoOpts,metricOpts = metricOpts, suppressProg = suppressProg) 32 | output <- do.call(null_model_engine,params) 33 | class(output) <- "nichenullmod" 34 | return(output) 35 | 36 | } 37 | 38 | 39 | #' Generic function for calculating null model summary statistics 40 | #' @description Takes as input a list of Null.Model.Out, with Obs, Sim, Elapsed Time, and Time Stamp values 41 | #' @param object the null model object to print a summary of. 42 | #' @param ... Extra parameters for summary . 43 | #' @details The summary output includes a timestamp and complete statistics on the simulated values of the metric, including the mean, variance, and one and two-tailed 95% confidence intervals. The lower and upper tails for the observed value are given, as is the standardized effect size (SES), which is calculated as the (Metric(obs) - average(Metric(sim)))/(standard deviation(Metric(sim))). Large positive values (or negative) values indicate that the observed metric is significantly larger (or smaller) than predicted by the null model. If the distribution of errors is approximately normal, then non-significant values will fall roughly within +- two SES values. 44 | #' @export 45 | 46 | summary.nichenullmod <- function(object,...) 47 | { 48 | 49 | nullmodObj <- object 50 | 51 | cat("Time Stamp: " , nullmodObj$Time.Stamp, "\n") 52 | cat("Reproducible: ",nullmodObj$Reproducible, "\n") 53 | cat("Number of Replications: ",nullmodObj$nReps, "\n") 54 | cat("Elapsed Time: ", nullmodObj$Elapsed.Time, "\n") 55 | cat("Metric: ", nullmodObj$Metric, "\n") 56 | cat("Algorithm: ", nullmodObj$Algorithm, "\n") 57 | 58 | cat("Observed Index: ", format(nullmodObj$Obs,digits=5), "\n") 59 | cat("Mean Of Simulated Index: ",format(mean(nullmodObj$Sim),digits=5), "\n") 60 | cat("Variance Of Simulated Index: ",format(var(nullmodObj$Sim),digits=5), "\n") 61 | cat("Lower 95% (1-tail): ",format(quantile(nullmodObj$Sim,0.05),digits=5), "\n") 62 | cat("Upper 95% (1-tail): ",format(quantile(nullmodObj$Sim,0.95),digits=5), "\n") 63 | cat("Lower 95% (2-tail): ",format(quantile(nullmodObj$Sim,0.025),digits=5), "\n") 64 | cat("Upper 95% (2-tail): ",format(quantile(nullmodObj$Sim,0.975),digits=5), "\n") 65 | 66 | #P-values 67 | if (nullmodObj$Obs > max(nullmodObj$Sim)) { 68 | cat("Lower-tail P > ",(length(nullmodObj$Sim) - 1)/length(nullmodObj$Sim), "\n") 69 | cat("Upper-tail P < ",1/length(nullmodObj$Sim), "\n") 70 | } else if(nullmodObj$Obs < min(nullmodObj$Sim)) { 71 | cat("Lower-tail P > ", 1/length(nullmodObj$Sim), "\n") 72 | cat("Upper-tail P < ",(length(nullmodObj$Sim) - 1)/length(nullmodObj$Sim), "\n") 73 | } else { 74 | cat("Lower-tail P = ", format(sum(nullmodObj$Obs >= nullmodObj$Sim)/length(nullmodObj$Sim),digits=5), "\n") 75 | cat("Upper-tail P = ", format(sum(nullmodObj$Obs <= nullmodObj$Sim)/length(nullmodObj$Sim),digits=5), "\n") 76 | } 77 | 78 | cat(paste("Observed metric > ",sum(nullmodObj$Obs > nullmodObj$Sim)," simulated metrics",sep="") , "\n") 79 | cat(paste("Observed metric < ",sum(nullmodObj$Obs < nullmodObj$Sim)," simulated metrics",sep="") , "\n") 80 | cat(paste("Observed metric = ",sum(nullmodObj$Obs == nullmodObj$Sim)," simulated metrics",sep=""), "\n") 81 | cat("Standardized Effect Size (SES): ", format((nullmodObj$Obs - mean(nullmodObj$Sim))/sd(nullmodObj$Sim),digits=5), "\n") 82 | 83 | #if(!is.null(Output.File)) close(outfile) 84 | } 85 | 86 | 87 | 88 | 89 | #' Niche Null Model Plot function 90 | #' @description Plot niche overlap null model object. 91 | #' @param x the null model object to plot. 92 | #' @param type the type of null model plot to display. See details for more information. 93 | #' @param ... Other variables to be passed on to base plotting. 94 | #' @details the valid types for the Niche Overlap module are "hist" to display a histogram of the simulated metric values, and "niche" to display the observed data matrix and one simulated matrix. 95 | #' 96 | #' The "hist" plot type is common to all EcoSimR modules. The blue histogram represents the NRep values of the metric for the simulated assemblages. The red vertical line represents the metric value for the real assemblage. The two pairs of vertical dashed black lines represent the one-tailed (long dash) and two-tailed (short dash) 95% confidence exact confidence intervals of the simulated data. 97 | #' 98 | #' The "niche" plot type illustrates the utilization data (observed = red, simulated = blue). Each row in the figure is a species, and each column is a resource utilization category. The area of each circle depicted is proportional to the utilization of a resoruce category by a species. Empty positions indicate a resource utilization of 0.0. The rows and columns are illustrated with the same ordering as the original data matrix. 99 | #' 100 | #' @export 101 | 102 | 103 | 104 | plot.nichenullmod <- function(x, type = "hist",...) 105 | { 106 | nullmodObj <- x 107 | if(type == "hist"){ 108 | 109 | opar <- par(no.readonly=TRUE) 110 | par(cex=1, cex.axis = 1.5, 111 | cex.main=1,cex.lab=1.6) 112 | par (mar=c(5,6,4,2)+0.1,mfrow=c(1,1)) 113 | #------------------------------------------------------ 114 | hist(nullmodObj$Sim, breaks=20, col="royalblue3", 115 | 116 | xlab="Simulated Metric",ylab="Frequency",main="", 117 | xlim=range(c(nullmodObj$Sim,nullmodObj$Obs))) 118 | abline(v=nullmodObj$Obs,col="red",lty="solid",lwd=2.5) 119 | abline(v=quantile(nullmodObj$Sim,c(0.05,0.95)),col="black",lty="dashed",lwd=2.5) 120 | abline(v=quantile(nullmodObj$Sim,c(0.025,0.975)),col="black",lty="dotted",lwd=2.5) 121 | mtext(as.character(date()),side=3,adj=1,line=3) 122 | } 123 | 124 | if(type == "niche"){ 125 | opar<- par(no.readonly=TRUE) 126 | par(mfrow=c(2,1)) 127 | Data <- nullmodObj$Data/rowSums(nullmodObj$Data) 128 | plot(rep(1:ncol(Data),times = nrow(Data)), 129 | rep(1:nrow(Data),each=ncol(Data)), 130 | xlab="Resource Category",ylab="Species",cex=10*sqrt(t(Data)/pi),col="red3",lwd=2, 131 | main="Observed Utilization Matrix",col.main="red3",cex.main=1.5) 132 | mtext(as.character(nullmodObj$Time.Stamp),side=3,adj=1,line=3) 133 | 134 | One.Null.Matrix <- nullmodObj$Randomized.Data 135 | One.Null.Matrix <- One.Null.Matrix/rowSums(One.Null.Matrix) 136 | plot(rep(1:ncol(One.Null.Matrix),times = nrow(One.Null.Matrix)), 137 | rep(1:nrow(One.Null.Matrix),each=ncol(One.Null.Matrix)), 138 | xlab="Resource Category",ylab="Species",cex=10*sqrt(t(One.Null.Matrix)/pi),col="royalblue3",lwd=2, 139 | main="Simulated Utilization Matrix",col.main="royalblue3",cex.main=1.5) 140 | par(opar) 141 | } 142 | 143 | } 144 | -------------------------------------------------------------------------------- /R/null_model_engine.R: -------------------------------------------------------------------------------- 1 | #'Run null model 2 | #'@description This function drives all the different kinds of null models that can be run. It is the underlying engine. 3 | #'@param speciesData a dataframe for analysis that is compatable with the metrics and algorithms used. 4 | #'@param algo the algorithm used to randomize the data. 5 | #'@param metric the metric used to quantify pattern in the data. 6 | #'@param nReps the number of null assemblages to simulate. 7 | #'@param saveSeed Save the existing random seed to allow the user to reproduce the exact model results. The default value is FALSE, in which case the random number seed that is created is not stored in the output. 8 | #'@param algoOpts a list containing options for a supplied alogrithm. 9 | #'@param metricOpts a list containing options for a supplied metric. 10 | #'@param type The type of null model being run. If the null model is intended to be used with one of the existing modules, the type should be "size","niche", or "cooc". If the user is creating an entirely new null model, type should be set to NULL (the default value). 11 | #'@param suppressProg TRUE or FALSE. If true, display of the progress bar in the console is suppressed; default is FALSE. This setting is useful for creating markdown documents with `knitr`. 12 | #'@examples \dontrun{ 13 | #' # User defined function 14 | #' 15 | #' 16 | #'} 17 | #'@export 18 | 19 | 20 | null_model_engine <- function(speciesData, algo, metric, nReps = 1000, saveSeed = FALSE, algoOpts = list(), metricOpts = list(),type=NULL,suppressProg=FALSE) 21 | { 22 | if(suppressProg){ 23 | pb <- txtProgressBar(min = 0, max = nReps, style = 3, file = stderr()) 24 | } else{ 25 | pb <- txtProgressBar(min = 0, max = nReps, style = 3) 26 | } 27 | ## Set the seed 28 | if(saveSeed){ 29 | randomSeed <- .Random.seed 30 | } else { 31 | randomSeed <- NULL 32 | } 33 | 34 | ## Convert to matrix for type consistency 35 | if(!is.matrix(speciesData)){ speciesData <- as.matrix(speciesData)} 36 | 37 | ### Check for row names hidden in the data frame and automagically strip them. 38 | 39 | if(suppressWarnings(is.na(as.numeric(speciesData[2,1])))){ 40 | speciesData <- speciesData[,-1] 41 | class(speciesData) <- "numeric" 42 | } 43 | 44 | algoF <- get(algo) 45 | metricF <- get(metric) 46 | 47 | ### Error check for input functions 48 | if(!grepl("speciesData",names(formals(algoF)[1]))){ 49 | stop("Please enter a valid algorithm with 'speciesData' as the first parameter") 50 | } 51 | if(!grepl("m",names(formals(metricF)[1])) && nchar(names(formals(metricF)[1])) == 1 ){ 52 | stop("Please enter a valid metric with 'm' as the first parameter") 53 | } 54 | 55 | 56 | 57 | startTime <- Sys.time() 58 | 59 | 60 | if (nReps < 2) nReps <- 2 61 | 62 | sim <- rep(NA,nReps) 63 | 64 | algoOpts[["speciesData"]] <- speciesData 65 | metricOpts[["m"]] <- speciesData 66 | obs <- as.vector(do.call(metricF,metricOpts)) 67 | 68 | 69 | for(i in 1:nReps){ 70 | m <- do.call(algoF,algoOpts) 71 | metricOpts[["m"]] <- m 72 | sim[i] <- do.call(metricF,metricOpts) 73 | setTxtProgressBar(pb, i) 74 | } 75 | close(pb) 76 | ## Save final matrix for plotting 77 | finalRandomData <- m 78 | 79 | endTime <- Sys.time() 80 | elapsedTime <- format(endTime-startTime,digits=2) 81 | timeStamp <- date() 82 | 83 | ### Reverse engineers the naming for consistent output 84 | ### Be sure to update the code below if new algos and metrics are added 85 | 86 | 87 | 88 | nullModelOut <- list(Obs=obs,Sim=sim, Elapsed.Time=elapsedTime, Time.Stamp=timeStamp,Metric = metric, Algorithm = algo, nReps = nReps, 89 | Reproducible = saveSeed,RandomSeed = randomSeed, Data = speciesData,Randomized.Data = finalRandomData) 90 | 91 | if(is.null(type)){ 92 | class(nullModelOut) <- "nullmod" 93 | } else if (type %in% c("niche","cooc","size")){ 94 | class(nullModelOut) <- paste(type,"nullmod",sep="") 95 | 96 | 97 | } 98 | 99 | return(nullModelOut) 100 | 101 | } 102 | 103 | 104 | 105 | #' Generic function for calculating null model summary statistics 106 | #' @description Takes as input a list of Null.Model.Out, with Obs, Sim, Elapsed Time, and Time Stamp values 107 | #' @param object the null model object to print a summary of. 108 | #' @param ... Extra parameters for summary. 109 | #' @details The summary output includes a timestamp and complete statistics on the simulated values of the metric, including the mean, variance, and one and two-tailed 95% confidence intervals. The lower and upper tails for the observed value are given, as is the standardized effect size (SES), which is calculated as the (Metric(obs) - average(Metric(sim)))/(standard deviation(Metric(sim))). Large positive values (or negative) values indicate that the observed metric is significantly larger (or smaller) than predicted by the null model. If the distribution of errors is approximately normal, then non-significant values will fall roughly within +- two SES values. 110 | #' @export 111 | 112 | summary.nullmod <- function(object,...) 113 | { 114 | nullmodObj <- object 115 | #if (!is.null(Output.File)) outfile <- file(p$Output.File, "w") else outfile <-"" 116 | 117 | cat("Time Stamp: " , nullmodObj$Time.Stamp, "\n") 118 | cat("Reproducible: ",nullmodObj$Reproducible, "\n") 119 | cat("Number of Replications: ",nullmodObj$nReps, "\n") 120 | cat("Elapsed Time: ", nullmodObj$Elapsed.Time, "\n") 121 | cat("Metric: ", nullmodObj$Metric, "\n") 122 | cat("Algorithm: ", nullmodObj$Algorithm, "\n") 123 | 124 | cat("Observed Index: ", format(nullmodObj$Obs,digits=5), "\n") 125 | cat("Mean Of Simulated Index: ",format(mean(nullmodObj$Sim),digits=5), "\n") 126 | cat("Variance Of Simulated Index: ",format(var(nullmodObj$Sim),digits=5), "\n") 127 | cat("Lower 95% (1-tail): ",format(quantile(nullmodObj$Sim,0.05),digits=5), "\n") 128 | cat("Upper 95% (1-tail): ",format(quantile(nullmodObj$Sim,0.95),digits=5), "\n") 129 | cat("Lower 95% (2-tail): ",format(quantile(nullmodObj$Sim,0.025),digits=5), "\n") 130 | cat("Upper 95% (2-tail): ",format(quantile(nullmodObj$Sim,0.975),digits=5), "\n") 131 | 132 | #P-values 133 | if (nullmodObj$Obs > max(nullmodObj$Sim)) { 134 | cat("Lower-tail P < ",(length(nullmodObj$Sim) - 1)/length(nullmodObj$Sim), "\n") 135 | cat("Upper-tail P > ",1/length(nullmodObj$Sim), "\n") 136 | } else if(nullmodObj$Obs < min(nullmodObj$Sim)) { 137 | cat("Lower-tail P > ", 1/length(nullmodObj$Sim), "\n") 138 | cat("Upper-tail P < ",(length(nullmodObj$Sim) - 1)/length(nullmodObj$Sim), "\n") 139 | } else { 140 | cat("Lower-tail P = ", format(sum(nullmodObj$Obs >= nullmodObj$Sim)/length(nullmodObj$Sim),digits=5), "\n") 141 | cat("Upper-tail P = ", format(sum(nullmodObj$Obs <= nullmodObj$Sim)/length(nullmodObj$Sim),digits=5), "\n") 142 | } 143 | 144 | cat(paste("Observed metric > ",sum(nullmodObj$Obs > nullmodObj$Sim)," simulated metrics",sep="") , "\n") 145 | cat(paste("Observed metric < ",sum(nullmodObj$Obs < nullmodObj$Sim)," simulated metrics",sep="") ,"\n") 146 | cat(paste("Observed metric = ",sum(nullmodObj$Obs == nullmodObj$Sim)," simulated metrics",sep="") , "\n") 147 | cat("Standardized Effect Size (SES): ", format((nullmodObj$Obs - mean(nullmodObj$Sim))/sd(nullmodObj$Sim),digits=5), "\n") 148 | 149 | #if(!is.null(Output.File)) close(outfile) 150 | } 151 | 152 | 153 | #' plot a histogram null model 154 | #' @description Plot a null model object. 155 | #' @param x the null model object to plot. 156 | #' @param ... Other variables to be passed on to base plotting. 157 | #' @details The "hist" plot type is common to all EcoSimR modules. The blue histogram represents the NRep values of the metric for the simulated assemblages. The red vertical line represents the metric value for the real assemblage. The two pairs of vertical dashed black lines represent the one-tailed (long dash) and two-tailed (short dash) 95% confidence exact confidence intervals of the simulated data. 158 | #' 159 | #' @export 160 | 161 | 162 | 163 | plot.nullmod <- function(x,...) 164 | { 165 | nullmodObj <- x 166 | par(mfrow=c(1,1)) 167 | opar <- par(no.readonly=TRUE) 168 | par(cex=1, cex.axis = 1.5, 169 | cex.main=1,cex.lab=1.6) 170 | par (mar=c(5,6,4,2)+0.1) 171 | hist(nullmodObj$Sim, breaks=20, col="royalblue3", 172 | 173 | xlab="Simulated Metric",ylab="Frequency",main="", 174 | xlim=range(c(nullmodObj$Sim,nullmodObj$Obs))) 175 | 176 | abline(v=nullmodObj$Obs,col="red",lty="solid",lwd=2.5) 177 | abline(v=quantile(nullmodObj$Sim,c(0.05,0.95)),col="black",lty="dashed",lwd=2.5) 178 | abline(v=quantile(nullmodObj$Sim,c(0.025,0.975)),col="black",lty="dotted",lwd=2.5) 179 | mtext(as.character(date()),side=3,adj=1,line=3) 180 | } 181 | 182 | 183 | -------------------------------------------------------------------------------- /R/randomMatrixGenerator.R: -------------------------------------------------------------------------------- 1 | #'Random Matrix Generator 2 | #'@description Create a random matrix with specified dimensions, percentage fill, marginal distributions, and matrix type (abundance or binary) to test the behavior of null model randomization algorithms. 3 | #'@param aBetaRow parameter shape1 for beta of row marginals 4 | #'@param bBetaRow parameter shape2 for beta of row marginals 5 | #'@param aBetaCol parameter shape1 for beta of column marginals 6 | #'@param bBetaCol parameter shape2 for beta of column marginals 7 | #'@param numRows number of rows in random matrix 8 | #'@param numCols number of columns in random matrix 9 | #'@param mFill proportion of matrix cells to be filled with non-zero elements 10 | #'@param abun expected total abundance (from Poisson distribution) of individuals in the matrix. If set to the default value of 0, abundances are not shown but are replaced by occurrences (1s) 11 | #'@param emptyRow specifies whether empty rows in random matrix will be retained (TRUE) or stripped out (FALSE) 12 | #'@param emptyCol specified wither empty columns will be retained (TRUE) or stripped out (FALSE) 13 | #'@details Understanding the behavior of null models with artificial data is an essential step before applying them to real data. This function creates stochastic community matrices in which each row is a species, each column is a site or island, and each entry is the occurrence (presence-absence) or abundance of a species in a site. For the analysis of niche overlap, the sites can be treated as unordered niche categories, and the abundances are the utilization values for each species. 14 | #' 15 | #'Row and column marginal distributions are described from a beta distribution, with user supplied coefficients. Marginal distributions are rescaled to one, and the conjoint probability of a species occurring in a site is determined with the outer product of the species (=row) and site(= column) marginals. This simple calculation assumes sites and species are independent, and excludes site x species interactions as well as species x species interactions. 16 | #' 17 | #'The user specifies the percent fill of the matrix, and this number of cells are randomly selected without replacement using the cojoint probabilities calculated from each marginal distribution. If the user has requested a presence-absence matrix (`abun = 0'), these cells are assigned a value of 1. If the user has reqested an abundance matrix ('abun > 0'), then the value of abundance specifies the summed abundance of all individuals in the matrix. The value of `abun` is used to set the lambda parameter for each occupied cell, and then a single draw from a Poisson distribution is used for the abundance in that cell. Small conjoint marginal probabilities can lead to empty rows or columns and the user can specify whether or not to retain empty rows and columns. The matrix rows and columns are sorted in descending order according to the marginal frequencies, and these are returned (matrix$rowMarg and matrix$colMarg) along with the matrix (matrix$m) in list form. 18 | #' 19 | #' `aBetaRow`, `bBetaRow`, `aBetaCol`, and `bBetaCol` specify the two shape parameters for the row and column marginals. The marginal values are created by a single random draw from these beta distributions, and then are rescaled so they sum to 1.0. Thus, the mean parameter value specified by the beta distribution does not matter in the calculation. Instead, it is the size of the variance that determines the amount of heterogeneity among row or column margins. Small values for the two shape parameters generate greater heterogeneity among the rows or columns marginals of the matrix. 20 | #' 21 | #' Thus, a distribution with `aBetaRow=1000` and `bBetaRow=1000` will generate marginal probabilities that are virtually identical for the different species (=rows), whereas `aBetaRow=1` and `bBetaRow=1` will generate uniform probabilities. These default values applied to both rows and columns will generate a typical presence-absence matrix, with some common and some sparse species, and some species-rich and species-poor sites. 22 | #' 23 | #' Setting `numRows`, `numCols`, and `mFill` allow the test matrix to be tailored to match the observed matrix. However, it may be necessary to increase `numRows` and `nCols` if the parameters often generate empty rows or columns. 24 | #' 25 | #' If low values of `abun` are specified, some occupied cells may be set to 0 because of a random draw from the Poisson distribution for that matrix cell. 26 | #' 27 | #' Once the test matrix is created, it can be used to explore any of the combinations of algorithm and matrix that are available in EcoSimR. 28 | #' @examples \dontrun{ 29 | #' ## Create a null matrix similar to MacArthur's warblers 30 | #' testMatrix <- ranMatGen(aBetaCol=1000,bBetaCol=1000, 31 | #' aBetaRow=1,bBetaRow=1, 32 | #' numRows=5,numCols=16, 33 | #' mFill=0.75, abun=1000, 34 | #' emptyRow=FALSE,emptyCol=TRUE)$m 35 | #' 36 | #' ## Run the null model 37 | #' testMod <- niche_null_model(testMatrix) 38 | #' 39 | #' ## Summary and niche utilization plot 40 | #' summary(testAnalysis) 41 | #' plot(testMod,type="niche") 42 | #' 43 | #' 44 | #' ## Create a null matrix similar to West Indies Finches 45 | #' testMatrix <- ranMatGen(aBetaCol=0.5,bBetaCol=0.5, 46 | #' aBetaRow=0.5,bBetaRow=0.5, 47 | #' numRows=30,numCols=30, 48 | #' mFill=0.25,abun=0,emptyRow=FALSE, 49 | #' emptyCol=FALSE)$m 50 | #' 51 | #' ## Run the null model 52 | #' testMod <- cooc_null_model(testMatrix$m, 53 | #' algo="simFast", 54 | #' burnin=10000,n.reps=1000) 55 | #' 56 | #' ## Summary and matrix, burn-in plots 57 | #' summary(testMod) 58 | #' plot(testMod,type="cooc") 59 | #' plot(testMod,type="burnin") 60 | #'} 61 | #' 62 | #'@export 63 | 64 | 65 | # function ranMatGen 66 | # 67 | # NJG 68 | # 2 August 2014 69 | # Creates a random matrix (binary or integer) 70 | # The user specifies the matrix dimensions and fill 71 | # and gives parameters to specify beta distributions 72 | # for row and column sums. 73 | # 74 | # The function returns a random matrix, 75 | # and the marginal weights from which it was constructed 76 | 77 | ranMatGen <- function (aBetaRow = 1, bBetaRow = 1, 78 | aBetaCol = 1, bBetaCol = 1, 79 | numRows = 20, numCols = 5, 80 | mFill = 0.5, abun = 0, 81 | emptyRow=FALSE, emptyCol=FALSE) 82 | { 83 | 84 | 85 | # set the marginal distributions, sort them, and rescale 86 | rowMarg <- sort(rbeta(n=numRows,shape1=aBetaRow,shape2=bBetaRow),decreasing=TRUE) 87 | rowMarg <- rowMarg/(sum(rowMarg)) 88 | 89 | colMarg <- sort(rbeta(n=numCols,shape1=aBetaCol,shape2=bBetaCol),decreasing=TRUE) 90 | colMarg <- colMarg/(sum(colMarg)) 91 | 92 | # create the heat map matrix using independent marginals 93 | heatMatrix <- outer(rowMarg,colMarg) 94 | 95 | # draw specified number of cells 96 | drawCells <- sample(x=heatMatrix,size=round(numRows*numCols*mFill),replace=FALSE,prob=heatMatrix) 97 | 98 | 99 | # create array to hold coordinates of chosen cells 100 | matCoor <- matrix(nrow=length(drawCells),ncol=2) 101 | 102 | # determine coordinates of chosen cells 103 | for (i in 1:length(drawCells)) { 104 | matCoor[i,c(1,2)] <- which(heatMatrix==drawCells[i],arr.ind=TRUE)[c(1,2)] 105 | } 106 | 107 | # create empty random matrix 108 | ranMat <- matrix(0,nrow=numRows,ncol=numCols) 109 | 110 | # fill in for binary presence absence matrix or abundance 111 | 112 | for (i in 1:nrow(matCoor)) { 113 | 114 | # if abun==0, fill in with occurrences 115 | if(abun==0)ranMat[matCoor[i,1],matCoor[i,2]] <- 1 else 116 | 117 | # if abun > 0 use poisson function for abundances 118 | ranMat[matCoor[i,1],matCoor[i,2]] <- rpois(1,lambda=abun*(drawCells[i]/sum(drawCells))) 119 | } 120 | 121 | 122 | # optionally remove empty rows and/or columns 123 | emptyRows <- which(rowSums(ranMat)==0) 124 | emptyCols <- which(colSums(ranMat)==0) 125 | 126 | if (!emptyRow & length(emptyRows)>0) ranMat <- ranMat[-(emptyRows),] 127 | 128 | if (!emptyCol & length(emptyCols)>0) ranMat <- ranMat[,-(emptyCols)] 129 | 130 | return(list(m=ranMat,rowMarg=rowMarg,colMarg=colMarg)) 131 | } 132 | -------------------------------------------------------------------------------- /R/reproduce_model.R: -------------------------------------------------------------------------------- 1 | #' Reproduce a result 2 | #' @description Helps reproduce the result of a simulation by restoring the RNG to the state of a supplied null model object. 3 | #' @param model the model object containing the result to be reproduced. 4 | #' @details Works by resetting the RNG state to what it was for a given EcoSimR simulation. This only works if the user saved the seed with the saveSeed parameter. 5 | #' @examples \dontrun{ 6 | #' finchMod <- cooc_null_model(dataWiFinches, algo="sim1",saveSeed=T) 7 | #' ## Check model output 8 | #' mean(finchMod$Sim) 9 | #' 10 | #' reproduce_model(finchMod) 11 | #' 12 | #' finchMod <- cooc_null_model(dataWiFinches, algo="sim1") 13 | #' ## Check model output is the same as before 14 | #' mean(finchMod$Sim) 15 | #' reproduce_model(finchMod) 16 | #' } 17 | #' @export 18 | 19 | reproduce_model <- function(model) { 20 | if (model$Reproducible){ 21 | assign(".Random.seed", model$RandomSeed, .GlobalEnv) 22 | } else { 23 | stop("You didn't save the seed for this model run, please run again and set saveSeed = TRUE") 24 | } 25 | 26 | } 27 | -------------------------------------------------------------------------------- /R/sim9fast.R: -------------------------------------------------------------------------------- 1 | #'Sim9 Co-occurrence Randomization Algorithm 2 | #'@description An improved implementation of the sequential swap algorithm. 3 | #'@param speciesData a dataframe in which rows are species, columns are sites, 4 | #' and the entries indicate the absence (0) or presence (1) of a species in a 5 | #' site. Empty rows and empty columns should not be included in the matrix. 6 | #'@param algo the algorithm to use, must be "sim1", "sim2", "sim3", "sim4", "sim5", "sim6", "sim7", "sim8", "sim9", "sim10"; default is "sim9". 7 | #'@param metric the metric used to calculate the null model: choices are "species_combo", "checker", "c_score", "c_score_var", "c_score_skew", "v_ratio"; default is "c_score". 8 | #'@param nReps the number of replicate null assemblages to create; default is 1000 replicates. 9 | #'@param saveSeed TRUE or FALSE. If TRUE the current seed is saved so the simulation can be repeated; default is FALSE. 10 | #'@param burn_in The number of burn_in iterations to use with the simFast algorithm; default is 500 burn-in replicates. 11 | #'@param algoOpts a list containing all the options for the specific algorithm you want to use. Must match the algorithm given in the `algo` argument. 12 | #'@param metricOpts a list containing all the options for the specific metric you want to use. Must match the metric given in the `metric` argument. 13 | #'@param suppressProg TRUE or FALSE. If true, display of the progress bar in the console is suppressed; default is FALSE. This setting is useful for creating markdown documents with `knitr`. 14 | #'@details Generating a set of random matrices with fixed row and column sums is a challenging computational problem. In the ecological literature, these matrices have been created by an MCMC "sequential swap" algorithm (Gotelli 2000). Two rows are two columns are chosen randomly ,and if the 4 cells form a 01/10 pattern, the cell values can be swapped to 10/01 and then replaced in the matrix. This generates a slightly different matrix with the same row and column totals. If the cells cannot be swapped, the trial is discarded. Because only 4 cells are reshuffled, it takes many successive swaps to eliminate transient effects as the matrix moves away from the original configuration and approaches a stationary distribution. A second disadvantage of the sequential swap is that all matrices are not sampled equiprobably because the failed swaps are discarded. This bias seems small for binary matrices that are typically generated by ecological studies (< 100 x 100), but could be important for "big data" applications. 15 | #' 16 | #'EcoSimR uses an unbiased and more efficient algorithm, which Strona et al. (2014) have recently dubbed the "curveball algorithm". In this algorithm, two rows from the matrix are randomly chosen to create a submatrix. Within the submatrix, columns in which the column sums are equal to zero are randomly swapped. The resulting submatrix is then returned to the full matrix, with modified values in two of the rows. If no swapping is possible (which is an improbable event for most ecological matrices), the unswapped matrix is still retained. The curveball algorithm is much more efficient than the sequential swap because most iterations reshuffle many elements in the matrix simultaneously. Strona et al. (2014) show empirically that this algorithm gives unbiased results. However, the resulting MCMC chains will still exhibit autocorrelation for consecutive matrices, especially if the matrix is very large. Future versions of EcoSimR will allow for a thinning parameter to avoid using every sequential matrix from the MCMC chain. The current version of EcoSimR allows for control over the burn-in period and generates a burn-in plot so the user can see whether stationarity has been achieved. 17 | #' 18 | #'@references 19 | #' Chen, Y., P. Diaconis, S.P. Holmes, and J.S. Liu. 2005. Sequential Monte Carlo methods for statistical analysis of tables. JASA 100: 109-120. 20 | #' 21 | #'Cobb, G. W., and Chen, Y.-P. 2003. An Application of Markov Chain Monte Carlo to Community Ecology. American Mathematical Monthly 110: 265-288. 22 | #' 23 | #'Gotelli, N.J. 2000. Null model analysis of species co-occurrence patterns. Ecology 81: 2606-2621. 24 | #' 25 | #' Strona. G., D. Nappo, F. Boccacci, S. Fattorini, and J. San-Miguel-Ayanz. 2014. A fast and unbiased procedure to randomize ecological binary matrices with fixed row and column totals. Nature Communications 5:4114 | DOI: 10.1038/ncomms5114. 26 | 27 | #' 28 | #'@examples \dontrun{ 29 | #' 30 | #' ## Run the null model 31 | #' finchMod <- cooc_null_model(dataWiFinches, algo="sim1",nReps=1000000,burn_in = 500) 32 | #' ## Summary and plot info 33 | #' summary(finchMod) 34 | #' plot(finchMod,type="burn_in") 35 | #' plot(finchMod,type="hist") 36 | #' plot(finchMod,type="cooc") 37 | #'} 38 | #' 39 | #'@export 40 | 41 | 42 | 43 | 44 | 45 | sim9 <- function (speciesData,algo,metric, nReps = 1000 , saveSeed = FALSE,burn_in = 0,algoOpts = list(),metricOpts = list(),suppressProg = TRUE) 46 | { 47 | 48 | if(saveSeed){ 49 | randomSeed <- .Random.seed 50 | } else { 51 | randomSeed <- NULL 52 | } 53 | 54 | ## Convert to matrix for type consistency 55 | if(!is.matrix(speciesData)){ speciesData <- as.matrix(speciesData)} 56 | 57 | ### Check for row names hidden in the data frame and automagically strip them. 58 | 59 | if(suppressWarnings(is.na(as.numeric(speciesData[2,1])))){ 60 | speciesData <- speciesData[,-1] 61 | class(speciesData) <- "numeric" 62 | } 63 | 64 | 65 | Start.Time <- Sys.time() 66 | metricF <- get(metric) 67 | 68 | Obs <- metricF(speciesData) 69 | #Trim the matrix to be just rowssums > 0 70 | msim <- speciesData[rowSums(speciesData) > 0, ] 71 | ifelse(burn_in == 0, burn_in <- max(1000,10*nrow(msim)),burn_in <- burn_in) 72 | burn.in.metric <- vector(mode="numeric",length = burn_in) 73 | simulated.metric <- vector(mode="numeric",length = nReps) 74 | # run sequential swap for burn in series 75 | if(suppressProg){ 76 | bi_pb <- txtProgressBar(min = 0, max = nReps, style = 3, file = stderr()) 77 | } else{ 78 | cat("Burn-in Progress \n") 79 | bi_pb <- txtProgressBar(min = 0, max = nReps, style = 3) 80 | } 81 | for (i in 1:burn_in) 82 | { 83 | msim <-sim9_single(msim) 84 | burn.in.metric[i] <- metricF(msim) 85 | setTxtProgressBar(bi_pb, i) 86 | } 87 | close(bi_pb) 88 | # run sequential swap for simulated series 89 | if(suppressProg){ 90 | stat_pb <- txtProgressBar(min = 0, max = nReps, style = 3, file = stderr()) 91 | } else{ 92 | cat("Swap Progress \n") 93 | 94 | stat_pb <- txtProgressBar(min = 0, max = nReps, style = 3) 95 | } 96 | for (i in 1: nReps) 97 | { 98 | msim <-sim9_single(msim) 99 | simulated.metric[i] <- metricF(msim) 100 | setTxtProgressBar(stat_pb, i) 101 | } 102 | close(stat_pb) 103 | 104 | Sim <- simulated.metric 105 | End.Time <- Sys.time() 106 | Elapsed.Time <- format(End.Time-Start.Time,digits=2) 107 | Time.Stamp <- date() 108 | 109 | sim9.fast.out <- list(Obs=Obs,Sim=Sim, Elapsed.Time=Elapsed.Time, Time.Stamp=Time.Stamp,Metric = metric, Algorithm = algo, N.Reps = nReps, SaveSeed = saveSeed, RandomSeed = randomSeed,Randomized.Data = msim , Data = speciesData,burn.in = burn_in,burn.in.metric= burn.in.metric) 110 | # plot to screen the trace function for the burn in 111 | 112 | class(sim9.fast.out) <- "nullmod" 113 | return(sim9.fast.out) 114 | } 115 | 116 | 117 | 118 | #' sim9_single 119 | #' @description Function for a single iteration of the sequential swap. 120 | #' @param speciesData binary presence-absence matrix. 121 | #' @details See details for sim9. 122 | #' @export 123 | sim9_single <- function (speciesData = matrix(rbinom(100, 1, 0.5), nrow = 10)) 124 | { 125 | # select two random rows and create submatrix 126 | ran.rows <- sample.int(nrow(speciesData), 2) 127 | m.pair <- speciesData[ran.rows, ] 128 | 129 | # find columns if any in pair for which colsum =1; these can be swapped 130 | Sum.Is.One = colSums(m.pair) == 1 131 | 132 | # Only swap if there are two or more columns to swap 133 | if(sum(Sum.Is.One) > 1){ 134 | columns <- which(Sum.Is.One) 135 | 136 | # return swap entries in the two rows 137 | speciesData[ran.rows, columns] <- m.pair[, sample(columns)] 138 | } 139 | 140 | return(speciesData) 141 | } 142 | 143 | 144 | -------------------------------------------------------------------------------- /R/sizeratio_null.R: -------------------------------------------------------------------------------- 1 | #'Size Ratio 2 | #'@description Create a Size Ratio null model 3 | #'@param speciesData a data vector in which each entry is the measured trait (such as body size or flowering date) for each species in the assemblage. 4 | #'@param algo the algorithm to use, must be "size_uniform", "size_uniform_user", "size_source_pool", "size_gamma". 5 | #'@param metric the metric used to caluclate the null model: choices are "min_diff", "min_ratio", "var_diff", "var_ratio"; default is "var_ratio". 6 | #'@param nReps the number of replicate null assemblages to create; default is 1000 replicates. 7 | #'@param saveSeed TRUE or FALSE. If TRUE the current seed is saved so the simulation can be repeated; default is FALSE. 8 | #'@param algoOpts a list containing all the options for the specific algorithm you want to use. Must match the algorithm given in the `algo` argument. 9 | #'@param metricOpts a list containing all the options for the specific metric you want to use. Must match the metric given in the `metric` argument. 10 | #'@param suppressProg TRUE or FALSE. If true, display of the progress bar in the console is suppressed; default is FALSE. This setting is useful for creating markdown documents with `knitr`. 11 | #'@examples \dontrun{ 12 | #' ## Run the null model 13 | #' rodentMod <- size_null_model(dataRodents) 14 | #' ## Summary and plot info 15 | #' summary(rodentMod) 16 | #' plot(rodentMod,type="hist") 17 | #' plot(rodentMod,type="size") 18 | #' 19 | #' ## Uniform Size model with user inputs 20 | #' rodentMod2 <- size_null_model(dataRodents,algo="size_uniform_user", 21 | #' algoOpts = list(userLow = 3,userHigh=15)) 22 | #' summary(rodentMod2) 23 | #' plot(rodentMod2,type="hist") 24 | #' plot(rodentMod2,type="size") 25 | #' 26 | #' ### Source pool model 27 | #' 28 | #' rodentMod_sp <- size_null_model(dataRodents,algo="size_source_pool", 29 | #' algoOpts = list(sourcePool = runif(dim(dataRodents)[1],1,15))) 30 | #' 31 | #' summary(rodentMod_sp) 32 | #' plot(rodentMod_sp,type="hist") 33 | #' plot(rodentMod_sp,type="size") 34 | #' 35 | #'} 36 | #' 37 | #'@export 38 | 39 | size_null_model <- function(speciesData, algo = "size_uniform", metric = "var_ratio", nReps = 1000, saveSeed = FALSE, algoOpts = list(), metricOpts = list(),suppressProg = FALSE){ 40 | 41 | mChoice<- c("min_diff", "min_ratio", "var_diff", "var_ratio") 42 | aChoice <- c("size_uniform", "size_uniform_user", "size_source_pool", "size_gamma") 43 | 44 | algo <- match.arg(algo,choices = aChoice) 45 | metric <- match.arg(metric,choices = mChoice) 46 | 47 | params <- list(speciesData = speciesData, algo = algo, metric = metric, nReps = nReps, saveSeed = saveSeed, algoOpts = algoOpts, metricOpts = metricOpts,suppressProg = suppressProg) 48 | output <- do.call(null_model_engine,params) 49 | class(output) <- "sizenullmod" 50 | return(output) 51 | 52 | } 53 | 54 | 55 | #' Generic function for calculating null model summary statistics 56 | #' @description Takes as input a list of Null.Model.Out, with Obs, Sim, Elapsed Time, and Time Stamp values 57 | #' @param object the null model object to print a summary of. 58 | #' @param ... Extra parameters for summary. 59 | #' @details The summary output includes a timestamp and complete statistics on the simulated values of the metric, including the mean, variance, and one and two-tailed 95% confidence intervals. The lower and upper tails for the observed value are given, as is the standardized effect size (SES), which is calculated as the (Metric(obs) - average(Metric(sim)))/(standard deviation(Metric(sim))). Large positive values (or negative) values indicate that the observed metric is significantly larger (or smaller) than predicted by the null model. If the distribution of errors is approximately normal, then non-significant values will fall roughly within +- two SES values. 60 | #' @export 61 | 62 | summary.sizenullmod <- function(object,...) 63 | { 64 | nullmodObj <- object 65 | #if (!is.null(Output.File)) outfile <- file(p$Output.File, "w") else outfile <-"" 66 | 67 | cat("Time Stamp: " , nullmodObj$Time.Stamp, "\n") 68 | cat("Reproducible: ",nullmodObj$Reproducible, "\n") 69 | cat("Number of Replications: ",nullmodObj$nReps, "\n") 70 | cat("Elapsed Time: ", nullmodObj$Elapsed.Time, "\n") 71 | cat("Metric: ", nullmodObj$Metric, "\n") 72 | cat("Algorithm: ", nullmodObj$Algorithm, "\n") 73 | 74 | cat("Observed Index: ", format(nullmodObj$Obs,digits=5), "\n") 75 | cat("Mean Of Simulated Index: ",format(mean(nullmodObj$Sim),digits=5), "\n") 76 | cat("Variance Of Simulated Index: ",format(var(nullmodObj$Sim),digits=5), "\n") 77 | cat("Lower 95% (1-tail): ",format(quantile(nullmodObj$Sim,0.05),digits=5), "\n") 78 | cat("Upper 95% (1-tail): ",format(quantile(nullmodObj$Sim,0.95),digits=5), "\n") 79 | cat("Lower 95% (2-tail): ",format(quantile(nullmodObj$Sim,0.025),digits=5), "\n") 80 | cat("Upper 95% (2-tail): ",format(quantile(nullmodObj$Sim,0.975),digits=5), "\n") 81 | 82 | #P-values 83 | if (nullmodObj$Obs > max(nullmodObj$Sim)) { 84 | cat("Lower-tail P < ",(length(nullmodObj$Sim) - 1)/length(nullmodObj$Sim), "\n") 85 | cat("Upper-tail P > ",1/length(nullmodObj$Sim), "\n") 86 | } else if(nullmodObj$Obs < min(nullmodObj$Sim)) { 87 | cat("Lower-tail P > ", 1/length(nullmodObj$Sim), "\n") 88 | cat("Upper-tail P < ",(length(nullmodObj$Sim) - 1)/length(nullmodObj$Sim), "\n") 89 | } else { 90 | cat("Lower-tail P = ", format(sum(nullmodObj$Obs >= nullmodObj$Sim)/length(nullmodObj$Sim),digits=5), "\n") 91 | cat("Upper-tail P = ", format(sum(nullmodObj$Obs <= nullmodObj$Sim)/length(nullmodObj$Sim),digits=5), "\n") 92 | } 93 | 94 | cat(paste("Observed metric > ",sum(nullmodObj$Obs > nullmodObj$Sim)," simulated metrics",sep="") , "\n") 95 | cat(paste("Observed metric < ",sum(nullmodObj$Obs < nullmodObj$Sim)," simulated metrics",sep="") ,"\n") 96 | cat(paste("Observed metric = ",sum(nullmodObj$Obs == nullmodObj$Sim)," simulated metrics",sep="") , "\n") 97 | cat("Standardized Effect Size (SES): ", format((nullmodObj$Obs - mean(nullmodObj$Sim))/sd(nullmodObj$Sim),digits=5), "\n") 98 | 99 | #if(!is.null(Output.File)) close(outfile) 100 | } 101 | 102 | 103 | 104 | #' Size Ratio Plot Function 105 | #' @description Plot Size Ratio null model object. 106 | #' @param x the null model object to plot. 107 | #' @param type the type of null model plot to display. See details for more information. 108 | #' @param ... Other variables to be passed on to base plotting. 109 | #' @details the valid types for the Size Overlap module are "hist" to display a histogram of the simulated metric values, and "size" to display the observed data matrix and one simulated matrix. 110 | #' 111 | #' The "hist" plot type is common to all EcoSimR modules. The blue histogram represents the NRep values of the metric for the simulated assemblages. The red vertical line represents the metric value for the real assemblage. The two pairs of vertical dashed black lines represent the one-tailed (long dash) and two-tailed (short dash) 95% confidence exact confidence intervals of the simulated data. 112 | #' 113 | #' The "size" plot type illustrates the trait data (observed = red, simulated = blue). Each circle in the number line represents the trait value of a different species. For the observed and simulated data, a histogram of the ordered size differences is also illustrated. 114 | #' 115 | #' @export 116 | 117 | plot.sizenullmod <- function(x, type = "hist",...) 118 | { 119 | nullmodObj <- x 120 | if(type == "hist"){ 121 | par(mfrow=c(1,1)) 122 | opar <- par(no.readonly=TRUE) 123 | par(cex=1, cex.axis = 1.5, 124 | cex.main=1,cex.lab=1.6) 125 | par (mar=c(5,6,4,2)+0.1) 126 | hist(nullmodObj$Sim, breaks=20, col="royalblue3", 127 | 128 | xlab="Simulated Metric",ylab="Frequency",main="", 129 | xlim=range(c(nullmodObj$Sim,nullmodObj$Obs))) 130 | 131 | abline(v=nullmodObj$Obs,col="red",lty="solid",lwd=2.5) 132 | abline(v=quantile(nullmodObj$Sim,c(0.05,0.95)),col="black",lty="dashed",lwd=2.5) 133 | abline(v=quantile(nullmodObj$Sim,c(0.025,0.975)),col="black",lty="dotted",lwd=2.5) 134 | mtext(as.character(date()),side=3,adj=1,line=3) 135 | } 136 | 137 | if(type=="size"){ 138 | 139 | 140 | opar<- par(no.readonly=TRUE) 141 | par(mfrow=c(2,1)) 142 | 143 | One.Null.Vector <- nullmodObj$Randomized.Data 144 | 145 | limits <- range(c(nullmodObj$Data,One.Null.Vector)) 146 | x.lims <- c((limits[1]-0.1*limits[2]),(1.1*limits[2])) 147 | if(x.lims[1]<0)x.lims[1] <- 0 148 | plot(nullmodObj$Data,xlim=x.lims,ylim=c(0,5),axes=TRUE,ann=TRUE,ylab="", 149 | xlab="Body Size",cex.lab=1.5,cex.axis=1.5,yaxt="n",bty="n") 150 | lines(x=x.lims,y=c(2,2)) 151 | points(x=nullmodObj$Data,y=rep(2,length(nullmodObj$Data)),pch=21,bg="red3",cex=2) 152 | lines(x=x.lims,y=c(4,4)) 153 | points(x=One.Null.Vector,y=rep(4,length(One.Null.Vector)),pch=21,bg="royalblue3",cex=2) 154 | text.center <- mean(x.lims) 155 | text(text.center,1,"Observed",font=2,cex=1.2) 156 | text(text.center,3,"Simulated",font=2,cex=1.2) 157 | 158 | 159 | 160 | mtext(as.character(nullmodObj$Time.Stamp),side=3,adj=1,line=3) 161 | Segs.Obs <-sort(diff(sort(nullmodObj$Data))) 162 | 163 | Segs.Sim <- sort(diff(sort(One.Null.Vector))) 164 | 165 | Segs.Mat <- matrix(c(Segs.Obs,Segs.Sim),ncol=2) 166 | 167 | barplot(Segs.Mat,beside=TRUE,col=rep(c("red3","royalblue3"),each=nrow(Segs.Mat)), 168 | names.arg=c("Observed","Simulated"),ylab="Body Size Difference",font=2, 169 | cex.names=1.5,sub="Sorted Size Differences",cex.sub=1.5,font.sub=2) 170 | 171 | 172 | par(opar) 173 | 174 | } 175 | 176 | } 177 | 178 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![Build Status](https://travis-ci.org/GotelliLab/EcoSimR.svg?branch=master)](https://travis-ci.org/GotelliLab/EcoSimR) 2 | [![Build status](https://ci.appveyor.com/api/projects/status/fc5qpu8v3b1ku4ud?svg=true)](https://ci.appveyor.com/project/emhart/ecosimr) 3 | [![Coverage Status](https://coveralls.io/repos/GotelliLab/EcoSimR/badge.svg?branch=master)](https://coveralls.io/r/GotelliLab/EcoSimR?branch=master) 4 | [![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.16636.svg)](http://dx.doi.org/10.5281/zenodo.16636) 5 | ![License](http://img.shields.io/badge/license-MIT-brightgreen.svg) 6 | ![Downloads](http://cranlogs.r-pkg.org/badges/EcoSimR) 7 | 8 | EcoSimR 9 | ======= 10 | 11 | Repository for EcoSimR, by Gotelli, N.J. and A.M. Ellison. 2015. EcoSimR 0.1.0 http://ecosimr.org 12 | 13 | QuickStart 14 | ======= 15 | 16 | First install the dev branch 17 | ```r 18 | install.packages("EcoSimR") 19 | ``` 20 | Currently null models can be run on niche data, co-occurrence data, and size ratio data 21 | 22 | **Niche null models** 23 | ```r 24 | library(EcoSimR) 25 | 26 | warbMod <- niche_null_model(macwarb) 27 | summary(warbMod) 28 | plot(warbMod,type="niche") 29 | plot(warbMod, type="hist") 30 | ``` 31 | ```r 32 | Time Stamp: Thu Jul 24 22:29:52 2014 33 | Random Number Seed: -418884223 34 | Number of Replications: 1000 35 | Elapsed Time: 0.46 secs 36 | Metric: pianka 37 | Algorithm: ra3 38 | Observed Index: 0.55514 39 | Mean Of Simulated Index: 0.39145 40 | Variance Of Simulated Index: 0.0022785 41 | Lower 95% (1-tail): 0.32365 42 | Upper 95% (1-tail): 0.47571 43 | Lower 95% (2-tail): 0.31274 44 | Upper 95% (2-tail): 0.50608 45 | P(Obs <= null) = 0.997 46 | P(Obs >= null) = 0.003 47 | P(Obs = null) = 0 48 | Standardized Effect Size (SES): 3.4293 49 | 50 | ``` 51 | 52 | *Niche plots* 53 | 54 | ![Niche Null models](inst/niche.png) 55 | 56 | *Histogram* 57 | 58 | ![Niche Null models](inst/niche_hist.png) 59 | 60 | **Co-Occurrence Null Models** 61 | 62 | ```r 63 | finchMod <- cooc_null_model(wiFinches, algo="sim3") 64 | summary(finchMod) 65 | plot(finchMod, typ="cooc") 66 | plot(finchMod, type="hist") 67 | ``` 68 | 69 | ```r 70 | Time Stamp: Thu Jul 24 22:42:17 2014 71 | Random Number Seed: 1969414287 72 | Number of Replications: 1000 73 | Elapsed Time: 2.7 secs 74 | Metric: c_score 75 | Algorithm: sim3 76 | Observed Index: 3.7941 77 | Mean Of Simulated Index: 7.2588 78 | Variance Of Simulated Index: 0.25058 79 | Lower 95% (1-tail): 6.6324 80 | Upper 95% (1-tail): 8.1905 81 | Lower 95% (2-tail): 6.5294 82 | Upper 95% (2-tail): 8.3912 83 | P(Obs <= null) = 0 84 | P(Obs >= null) = 1 85 | P(Obs = null) = 0 86 | Standardized Effect Size (SES): -6.9214 87 | 88 | ``` 89 | 90 | *Sample of shuffled matrix* 91 | 92 | ![Co-Occurrence null models](inst/cooc.png) 93 | 94 | *Histogram* 95 | 96 | ![Co-Occurrence null models](inst/cooc_hist.png) 97 | 98 | Also when we run with the `simFast` algorithm we can get a burn in plot 99 | 100 | ```r 101 | finchMod <- cooc_null_model(wiFinches, algo="simFast",burnin=500) 102 | plot(finchMod,type="burnin") 103 | ``` 104 | ![Co-Occurrence ](inst/burnin.png) 105 | 106 | **Size Ratio null models** 107 | 108 | Lastly we can run null models on size ratios, and produce two different kinds of plots 109 | 110 | ```r 111 | rodentMod <- size_null_model(rodents) 112 | summary(rodentMod) 113 | plot(rodentMode,type="size") 114 | plot(rodentMode,type="hist") 115 | ``` 116 | ``` 117 | Time Stamp: Thu Jul 24 22:45:34 2014 118 | Random Number Seed: -438432393 119 | Number of Replications: 1000 120 | Elapsed Time: 0.15 secs 121 | Metric: var_ratio 122 | Algorithm: uniform_size 123 | Observed Index: 0.071826 124 | Mean Of Simulated Index: 0.18809 125 | Variance Of Simulated Index: 0.012434 126 | Lower 95% (1-tail): 0.055043 127 | Upper 95% (1-tail): 0.41076 128 | Lower 95% (2-tail): 0.044767 129 | Upper 95% (2-tail): 0.45634 130 | P(Obs <= null) = 0.097 131 | P(Obs >= null) = 0.903 132 | P(Obs = null) = 0 133 | Standardized Effect Size (SES): -1.0427 134 | ``` 135 | 136 | *Size null model* 137 | 138 | ![Co-Occurrence null models](inst/size.png) 139 | 140 | 141 | *Histogram* 142 | 143 | ![Co-Occurrence null models](inst/size_hist.png) 144 | -------------------------------------------------------------------------------- /appveyor.yml: -------------------------------------------------------------------------------- 1 | environment: 2 | R_CHECK_ARGS: --no-build-vignettes --no-manual 3 | 4 | init: 5 | ps: | 6 | $ErrorActionPreference = "Stop" 7 | Invoke-WebRequest http://raw.github.com/krlmlr/r-appveyor/master/scripts/appveyor-tool.ps1 -OutFile "..\appveyor-tool.ps1" 8 | Import-Module '..\appveyor-tool.ps1' 9 | install: 10 | ps: Bootstrap 11 | 12 | build_script: 13 | - travis-tool.sh install_deps 14 | 15 | test_script: 16 | - travis-tool.sh run_tests 17 | 18 | on_failure: 19 | - travis-tool.sh dump_logs -------------------------------------------------------------------------------- /data/datasets.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GotelliLab/EcoSimR/06e10252ee5d8ae19eca7dd176d297585cdb3222/data/datasets.rda -------------------------------------------------------------------------------- /inst/CITATION: -------------------------------------------------------------------------------- 1 | 2 | citEntry(entry = "Manual", 3 | title = "EcoSimR: Null model analysis for ecological data", 4 | author = "Nicholas J. Gotelli and Edmund M. Hart and Aaron M. Ellison", 5 | year = "2015", 6 | note = "R package version 0.1.0", 7 | url = "http://github.com/gotellilab/EcoSimR", 8 | doi = "10.5281/zenodo.16522", 9 | 10 | textVersion = 11 | paste("Nicholas J. Gotelli, Edmund M. Hart and Aaron M. Ellison (2015) EcoSimR: Null model analysis for ecological data. R package version 0.1.0. http://github.com/gotellilab/EcoSimR DOI: 10.5281/zenodo.16522") 12 | ) -------------------------------------------------------------------------------- /inst/burnin.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GotelliLab/EcoSimR/06e10252ee5d8ae19eca7dd176d297585cdb3222/inst/burnin.png -------------------------------------------------------------------------------- /inst/cooc.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GotelliLab/EcoSimR/06e10252ee5d8ae19eca7dd176d297585cdb3222/inst/cooc.png -------------------------------------------------------------------------------- /inst/cooc_hist.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GotelliLab/EcoSimR/06e10252ee5d8ae19eca7dd176d297585cdb3222/inst/cooc_hist.png -------------------------------------------------------------------------------- /inst/niche.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GotelliLab/EcoSimR/06e10252ee5d8ae19eca7dd176d297585cdb3222/inst/niche.png -------------------------------------------------------------------------------- /inst/niche_hist.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GotelliLab/EcoSimR/06e10252ee5d8ae19eca7dd176d297585cdb3222/inst/niche_hist.png -------------------------------------------------------------------------------- /inst/size.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GotelliLab/EcoSimR/06e10252ee5d8ae19eca7dd176d297585cdb3222/inst/size.png -------------------------------------------------------------------------------- /inst/size_hist.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GotelliLab/EcoSimR/06e10252ee5d8ae19eca7dd176d297585cdb3222/inst/size_hist.png -------------------------------------------------------------------------------- /man/EcoSimR.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/EcoSimR-package.r 3 | \docType{package} 4 | \name{EcoSimR} 5 | \alias{EcoSimR} 6 | \alias{EcoSimR-package} 7 | \title{EcoSimR 8 | EcoSimR is a collection of functions for calculating community metrics and algorithms for randomizing community data for null model analysis. Current modules are included for the analysis of niche overlap, body size overlap, and species co-occurrence. EcoSimR also allows users to define their own functions and algorithms to develop new null models.} 9 | \description{ 10 | EcoSimR 11 | EcoSimR is a collection of functions for calculating community metrics and algorithms for randomizing community data for null model analysis. Current modules are included for the analysis of niche overlap, body size overlap, and species co-occurrence. EcoSimR also allows users to define their own functions and algorithms to develop new null models. 12 | } 13 | 14 | -------------------------------------------------------------------------------- /man/c_score.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{c_score} 4 | \alias{c_score} 5 | \title{CScore Co-occurrence Metric} 6 | \usage{ 7 | c_score(m = matrix(rbinom(100, 1, 0.5), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{m}{a binary presence-absence matrix in which rows are species and columns 11 | are sites.} 12 | } 13 | \value{ 14 | Returns the average C-score calculated across all possible species pairs 15 | in the matrix. 16 | } 17 | \description{ 18 | Takes a binary presence-absence matrix and returns 19 | Stone and Roberts' (1990) C-score. 20 | } 21 | \details{ 22 | For each unique pair of species, the C-score is calculated as 23 | 24 | \deqn{C_{ij} = (R_i - S)(R_j - S)}{C_ij = (R_i - S)(R_j - S)} 25 | 26 | where R_i and R_j are the row sums for species i and j, and S is the number 27 | of shared sites in which both species i and species j are present. For any 28 | particular species pair, the larger the C-score, the more segregated the 29 | pair, with fewer shared sites. However, the index can be difficult to 30 | interpret when calculated as a matrix-wide average, because a single matrix 31 | can contain individual pairs of species that are segregated, random, or aggregated. 32 | 33 | Degenerate matrices result from simulations where a row or column sum may be 0. 34 | } 35 | \note{ 36 | The matrix-wide C-score is not calculated for missing species, so empty 37 | rows in the matrix do not affect the result. 38 | } 39 | \examples{ 40 | obsCScore <- c_score(m=matrix(rbinom(100,1,0.5),nrow=10)) 41 | } 42 | \references{ 43 | Stone. L. and A. Roberts. 1990. The checkerboard score and species 44 | distributions. Oecologia 85: 74-79. 45 | 46 | Gotelli, N.J. and W. Ulrich. 2010. The empirical Bayes approach as a tool to 47 | identify non-random species associations. Oecologia 162:463-477. 48 | } 49 | 50 | -------------------------------------------------------------------------------- /man/c_score_skew.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{c_score_skew} 4 | \alias{c_score_skew} 5 | \title{CScoreSkew Co-occurrence Metric} 6 | \usage{ 7 | c_score_skew(m = matrix(rbinom(100, 1, 0.5), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{m}{a binary presence-absence matrix in which rows are species and columns 11 | are sites.} 12 | } 13 | \value{ 14 | Returns the skewness of the C-score calculated across all possible 15 | species pairs in the matrix. 16 | } 17 | \description{ 18 | Takes a binary presence-absence matrix and returns 19 | the skewness of the Stone and Roberts' (1990) C-score. 20 | } 21 | \details{ 22 | A large positive value of skewness implies a preponderance of species pairs 23 | with large C-score values (segregated), whereas a large negative value of 24 | skewness implies a preponderance of species pairs with small C-score values 25 | (aggregated). 26 | } 27 | \note{ 28 | The matrix-wide C-score is not calculated for missing species, so empty 29 | rows in the matrix do not affect the result. This index has not been 30 | thoroughly tested with real data sets. 31 | } 32 | \examples{ 33 | skewCScore <- c_score_skew(m=matrix(rbinom(100,1,0.5),nrow=10)) 34 | } 35 | \references{ 36 | Stone, L. and A. Roberts. 1990. The checkerboard score and species 37 | distributions. Oecologia 85: 74-79. 38 | 39 | Stone, L. and A. Roberts. 1992. Competitive exclusion, or species aggregation? 40 | An aid in deciding. Oecologia 91: 419-424. 41 | } 42 | \seealso{ 43 | \code{\link{c_score}} co-occurrence index. 44 | } 45 | 46 | -------------------------------------------------------------------------------- /man/c_score_var.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{c_score_var} 4 | \alias{c_score_var} 5 | \title{CScoreVariance Co-occurrence Metric} 6 | \usage{ 7 | c_score_var(m = matrix(rbinom(100, 1, 0.5), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{m}{a binary presence-absence matrix in which rows are species and columns 11 | are sites.} 12 | } 13 | \value{ 14 | Returns the variance of the C-score calculated across all possible 15 | species pairs in the matrix. 16 | } 17 | \description{ 18 | Takes a binary presence-absence matrix and returns 19 | the variance of the Stone and Roberts' (1990) C-score. 20 | } 21 | \details{ 22 | A large value of this variance implies that some species pairs 23 | in the matrix are strongly segregated (large C-score) and other species pairs 24 | are random or aggregated. 25 | } 26 | \note{ 27 | The matrix-wide C-score is not calculated for missing species, so empty 28 | rows in the matrix do not affect the result. This index has not been 29 | thoroughly tested with real data sets. 30 | } 31 | \examples{ 32 | varCScore <- c_score_var(m=matrix(rbinom(100,1,0.5),nrow=10)) 33 | } 34 | \references{ 35 | Stone, L. and A. Roberts. 1990. The checkerboard score and species 36 | distributions. Oecologia 85: 74-79. 37 | 38 | Stone, L. and A. Roberts. 1992. Competitive exclusion, or species aggregation? 39 | An aid in deciding. Oecologia 91: 419-424. 40 | } 41 | \seealso{ 42 | \code{\link{c_score}} co-occurrence index. 43 | } 44 | 45 | -------------------------------------------------------------------------------- /man/checker.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{checker} 4 | \alias{checker} 5 | \title{Checker Co-occurrence Metric} 6 | \usage{ 7 | checker(m = matrix(rbinom(100, 1, 0.5), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{m}{A binary presence-absence matrix in which rows are species and columns 11 | are sites.} 12 | } 13 | \value{ 14 | Returns the number of unique species pairs that never co-occur. 15 | } 16 | \description{ 17 | Function to calculate number of unique pairs of species 18 | that never co-occur and form a "checkerboard pair". 19 | } 20 | \details{ 21 | In Diamond's (1975) assembly rules model, pairs of species that 22 | never co-occur in any site are interpreted as examples of interspecific competition. 23 | A set of communities structured this way should contain more checkerboard 24 | pairs than expected by chance. 25 | } 26 | \examples{ 27 | obsChecker <- checker(m=matrix(rbinom(100,1,0.5),nrow=10)) 28 | } 29 | \references{ 30 | Diamond, J.M. 1975. Assembly of species communities. p. 342-444 in: 31 | Ecology and Evolution of Communities. M.L. Cody and J.M. Diamond (eds.). 32 | Harvard University Press, Cambridge. 33 | 34 | Connor, E.F. and D. Simberloff. 1979. The assembly of species communities: chance 35 | or competition? Ecology 60: 1132-1140. 36 | } 37 | 38 | -------------------------------------------------------------------------------- /man/cooc_null_model.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/coccurrence_null.R 3 | \name{cooc_null_model} 4 | \alias{cooc_null_model} 5 | \title{Co-Occurrence Null model} 6 | \usage{ 7 | cooc_null_model(speciesData, algo = "sim9", metric = "c_score", 8 | nReps = 1000, saveSeed = FALSE, burn_in = 500, algoOpts = list(), 9 | metricOpts = list(), suppressProg = FALSE) 10 | } 11 | \arguments{ 12 | \item{speciesData}{a dataframe in which rows are species, columns are sites, 13 | and the entries indicate the absence (0) or presence (1) of a species in a 14 | site. Empty rows and empty columns should not be included in the matrix.} 15 | 16 | \item{algo}{the algorithm to use, must be "sim1", "sim2", "sim3", "sim4", "sim5", "sim6", "sim7", "sim8", "sim9", "sim10"; default is "sim9".} 17 | 18 | \item{metric}{the metric used to calculate the null model: choices are "species_combo", "checker", "c_score", "c_score_var", "c_score_skew", "v_ratio"; default is "c_score".} 19 | 20 | \item{nReps}{the number of replicate null assemblages to create; default is 1000 replicates.} 21 | 22 | \item{saveSeed}{TRUE or FALSE. If TRUE the current seed is saved so the simulation can be repeated; default is FALSE.} 23 | 24 | \item{burn_in}{The number of burn_in iterations to use with the simFast algorithm; default is 500 burn-in replicates.} 25 | 26 | \item{algoOpts}{a list containing all the options for the specific algorithm you want to use. Must match the algorithm given in the `algo` argument.} 27 | 28 | \item{metricOpts}{a list containing all the options for the specific metric you want to use. Must match the metric given in the `metric` argument.} 29 | 30 | \item{suppressProg}{TRUE or FALSE. If true, display of the progress bar in the console is suppressed; default is FALSE. This setting is useful for creating markdown documents with `knitr`.} 31 | } 32 | \description{ 33 | Create a Co-Occurrence null model 34 | } 35 | \examples{ 36 | \dontrun{ 37 | 38 | ## Run the null model 39 | finchMod <- cooc_null_model(dataWiFinches, algo="sim9",nReps=10000,burn_in = 500) 40 | ## Summary and plot info 41 | summary(finchMod) 42 | plot(finchMod,type="burn_in") 43 | plot(finchMod,type="hist") 44 | plot(finchMod,type="cooc") 45 | 46 | ## Example that is repeatable with a saved seed 47 | finchMod <- cooc_null_model(dataWiFinches, algo="sim1",saveSeed = TRUE) 48 | mean(finchMod$Sim) 49 | ## Run the model with the seed saved 50 | 51 | finchMod <- cooc_null_model(dataWiFinches, algo="sim1",saveSeed=T) 52 | ## Check model output 53 | mean(finchMod$Sim) 54 | 55 | reproduce_model(finchMod$Sim) 56 | 57 | finchMod <- cooc_null_model(dataWiFinches, algo="sim1") 58 | ## Check model output is the same as before 59 | mean(finchMod$Sim) 60 | reproduce_model(finchMod$Sim) 61 | 62 | 63 | } 64 | } 65 | 66 | -------------------------------------------------------------------------------- /man/czekanowski.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{czekanowski} 4 | \alias{czekanowski} 5 | \title{Czekanowski Niche Overlap Metric} 6 | \usage{ 7 | czekanowski(m = matrix(rpois(80, 1), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{m}{a matrix of resource utilization values.} 11 | } 12 | \value{ 13 | Returns the average pairwise niche overlap. 14 | } 15 | \description{ 16 | Takes a resource utilization matrix as input and 17 | returns the average pairwise Czekanowki niche overlap index. 18 | } 19 | \details{ 20 | The Czekanowski niche overlap index is averaged 21 | over each unique species pair. The index measures the area of intersection 22 | of the resource utilization histograms of each species pair. 23 | Values of Czekanowski niche overlap index close to 0.0 24 | reflect usage of exclusive resource categories, whereas values close to 1.0 25 | reflect similar resource utilization spectra. 26 | 27 | \deqn{O_{jk} = O_{kj} = 1 - 0.5\sum_{i=1}^n|p_{ij} - p_{ik}|}{O_jk = O_kj = 1 - 0.5*sum|p_ij - p_ik|}' 28 | } 29 | \note{ 30 | The resource utilization matrix (rows = species, columns = discrete 31 | resource categories) may include zeroes, but no negative numbers or missing 32 | values. Relative resource within a species is first calculated, so the rows 33 | need not sum to 1.0. 34 | } 35 | \examples{ 36 | obsOverlap <- czekanowski(m=matrix(rpois(40,0.5),nrow=8)) 37 | } 38 | \references{ 39 | Feinsinger, P., E.E. Spears, and R. Poole. 1981. A simple measure 40 | of niche breadth. Ecology 62: 27-32. 41 | 42 | Winemiller, K.O. and E.R. Pianka. 1990. Organization in natural assemblages 43 | of desert lizards and tropical fishes. Ecological Monographs 60: 27-55. 44 | } 45 | \seealso{ 46 | \code{\link{pianka}} niche overlap index. 47 | } 48 | 49 | -------------------------------------------------------------------------------- /man/czekanowski_skew.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{czekanowski_skew} 4 | \alias{czekanowski_skew} 5 | \title{CzekanowskiSkew Niche Overlap Metric} 6 | \usage{ 7 | czekanowski_skew(m = matrix(rpois(80, 1), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{m}{a matrix of resource utilization values.} 11 | } 12 | \value{ 13 | Returns the skewness of the average pairwise niche overlap. 14 | } 15 | \description{ 16 | Takes a niche utilization matrix returns the skew of the 17 | Czekanowski pairwise niche overlap index. 18 | } 19 | \details{ 20 | A large positive value for skewness implies that there are more species pairs 21 | with high than low niche overlap. A large negative value for skewness implies there are more 22 | species pairs with low than high niche overlap. The performance of this algorithm 23 | has not been thoroughly tested with real data sets. 24 | } 25 | \note{ 26 | The resource utilization matrix (rows = species, columns = discrete 27 | resource categories) may include zeroes, but no negative numbers or missing 28 | values. Relative resource within a species is first calculated, so the rows 29 | need not sum to 1.0. 30 | } 31 | \examples{ 32 | obsSkew <- czekanowski_skew(m=matrix(rpois(40,0.5),nrow=8)) 33 | } 34 | \references{ 35 | Winemiller, K.O. and E.R. Pianka. 1990. Organization in natural assemblages 36 | of desert lizards and tropical fishes. Ecological Monographs 60: 27-55. 37 | } 38 | \seealso{ 39 | \code{\link{czekanowski}} niche overlap index. 40 | } 41 | 42 | -------------------------------------------------------------------------------- /man/czekanowski_var.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{czekanowski_var} 4 | \alias{czekanowski_var} 5 | \title{CzekanowskiVariance Niche Overlap Metric} 6 | \usage{ 7 | czekanowski_var(m = matrix(rpois(80, 1), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{m}{a matrix of resource utilization values.} 11 | } 12 | \value{ 13 | Returns the variance of the average pairwise niche overlap. 14 | } 15 | \description{ 16 | Takes a niche utilization matrix returns the variance of the 17 | Czekanowski niche overlap index 18 | } 19 | \details{ 20 | A large value for variance implies that some species pairs show high 21 | niche overlap and others show low niche overlap. A low value for variance 22 | implies that niche overlap (high or low) is very similar among all species pairs. 23 | } 24 | \note{ 25 | The resource utilization matrix (rows = species, columns = discrete 26 | resource categories) may include zeroes, but no negative numbers or missing 27 | values. Relative resource within a species is first calculated, so the rows 28 | need not sum to 1.0. 29 | } 30 | \examples{ 31 | obsVar <- czekanowski_var(m=matrix(rpois(40,0.5),nrow=8)) 32 | } 33 | \references{ 34 | Winemiller, K.O. and E.R. Pianka. 1990. Organization in natural 35 | assemblages of desert lizards and tropical fishes. Ecological Monographs 60: 36 | 27-55. 37 | } 38 | \seealso{ 39 | \code{\link{czekanowski}} niche overlap index. 40 | } 41 | 42 | -------------------------------------------------------------------------------- /man/dataMacWarb.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/EcoSimR-package.r 3 | \docType{data} 4 | \name{dataMacWarb} 5 | \alias{dataMacWarb} 6 | \title{MacArthur's (1958) warbler data 7 | This data matrix is from MacArthur's classic (1958) paper on the coexistence of 5 species of New England warbler. Each row of the data matrix is a different species of warbler, and each column is one of 16 different subregions of a coniferous tree. Each entry is the percentage of time that each species was observed foraging in a different subregion of the tree (see Figures 2-4 in MacArthur 1958). Zeroes indicate subregions of the tree in which a species was not recorded foraging.} 8 | \description{ 9 | MacArthur's (1958) warbler data 10 | This data matrix is from MacArthur's classic (1958) paper on the coexistence of 5 species of New England warbler. Each row of the data matrix is a different species of warbler, and each column is one of 16 different subregions of a coniferous tree. Each entry is the percentage of time that each species was observed foraging in a different subregion of the tree (see Figures 2-4 in MacArthur 1958). Zeroes indicate subregions of the tree in which a species was not recorded foraging. 11 | } 12 | \references{ 13 | MacArthur, R.H. 1958. Population ecology of some warblers of northeastern coniferous forests. Ecology 39: 599-699. 14 | } 15 | \keyword{data} 16 | \keyword{datasets} 17 | 18 | -------------------------------------------------------------------------------- /man/dataRodents.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/EcoSimR-package.r 3 | \docType{data} 4 | \name{dataRodents} 5 | \alias{dataRodents} 6 | \title{Desert rodent data set 7 | This data vector is from Brown's (1975) study of the coexistence of desert rodent species. Each entry is the average adult body mass in grams of six co-occurring species of Sonoran Desert rodents.} 8 | \description{ 9 | Desert rodent data set 10 | This data vector is from Brown's (1975) study of the coexistence of desert rodent species. Each entry is the average adult body mass in grams of six co-occurring species of Sonoran Desert rodents. 11 | } 12 | \references{ 13 | Brown, J.H. 1975. Geographical ecology of desert rodents. p. 314-341 in: Ecology and Evolution of Communities. M.L. Cody and J.M. Diamond (eds.). Harvard University Press, Cambridge. 14 | } 15 | \keyword{data} 16 | \keyword{datasets} 17 | 18 | -------------------------------------------------------------------------------- /man/dataWiFinches.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/EcoSimR-package.r 3 | \docType{data} 4 | \name{dataWiFinches} 5 | \alias{dataWiFinches} 6 | \title{West Indian Finches data 7 | This data frame is a binary presence-absence matrix for West Indies finches (Fringillidae). Each row is a different species of finch and each column is one of the 19 major islands in the West Indies. Entries indicate the presence (1) or absence (0) of a species on an island. Data from Gotelli and Abele (1982).} 8 | \description{ 9 | West Indian Finches data 10 | This data frame is a binary presence-absence matrix for West Indies finches (Fringillidae). Each row is a different species of finch and each column is one of the 19 major islands in the West Indies. Entries indicate the presence (1) or absence (0) of a species on an island. Data from Gotelli and Abele (1982). 11 | } 12 | \references{ 13 | Gotelli, N.J. and L.G. Abele. 1982. Statistical distributions of West Indian land bird families. Journal of Biogeography 9: 421-435. 14 | } 15 | \keyword{data} 16 | \keyword{datasets} 17 | 18 | -------------------------------------------------------------------------------- /man/min_diff.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{min_diff} 4 | \alias{min_diff} 5 | \title{MinDiff Size Overlap Metric} 6 | \usage{ 7 | min_diff(m = runif(20)) 8 | } 9 | \arguments{ 10 | \item{m}{a vector of non-negative trait measures, one for each species} 11 | } 12 | \value{ 13 | Returns the minimum difference between adjacent, ordered values. 14 | } 15 | \description{ 16 | Function to calculate the minimum absolute size difference 17 | between species within an assemblage. 18 | } 19 | \details{ 20 | Although this index is typically used to examine body size differences 21 | in an animal assemblage, it could be used for any morphological index, 22 | such as beak size, or for a phenological "trait", such as peak flowering time in a plant 23 | assemblage. 24 | } 25 | \examples{ 26 | MinSizeDif <- min_diff(rgamma(20,shape=3,scale=2)) 27 | } 28 | \references{ 29 | Simberloff, D. and W.J. Boecklen. 1981. Santa Rosalia reconsidered: size 30 | ratios and competition. Evolution 35: 1206-1228. 31 | } 32 | 33 | -------------------------------------------------------------------------------- /man/min_ratio.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{min_ratio} 4 | \alias{min_ratio} 5 | \title{MinRatio Size Overlap Ratio Metric} 6 | \usage{ 7 | min_ratio(m = runif(20)) 8 | } 9 | \arguments{ 10 | \item{m}{a vector of non-negative trait measures, one for each species} 11 | } 12 | \value{ 13 | Returns the minimum size ratio difference between adjacent, ordered values. 14 | } 15 | \description{ 16 | Function to calculate the minimum size ratio (larger/next larger) 17 | between species within an assemblage. 18 | } 19 | \details{ 20 | This index is based on the minimum size ratio (larger/next larger) difference between 21 | consecutively ordered species in an assemblage. It is appropriate for 22 | morphological traits, but not phenological ones. 23 | } 24 | \examples{ 25 | MinSizeDif <- min_ratio(rgamma(20,shape=3,scale=2)) 26 | } 27 | \references{ 28 | Simberloff, D. and W.J. Boecklen. 1981. Santa Rosalia reconsidered: size 29 | ratios and competition. Evolution 35: 1206-1228. 30 | } 31 | 32 | -------------------------------------------------------------------------------- /man/niche_null_model.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/niche_overlap_null.R 3 | \name{niche_null_model} 4 | \alias{niche_null_model} 5 | \title{Niche overlap null models} 6 | \usage{ 7 | niche_null_model(speciesData, algo = "ra3", metric = "pianka", 8 | nReps = 1000, saveSeed = FALSE, algoOpts = list(), 9 | metricOpts = list(), suppressProg = FALSE) 10 | } 11 | \arguments{ 12 | \item{speciesData}{a data frame in which each row is a species, each column is a resource utilization category, and the entries represent the quantity of the resource used by each species. Examples might be the amount of time a species spends foraging in different microhabitats, the biomass of different prey types, or counts of the number of times an adult female oviposits eggs on different species of a host plant.} 13 | 14 | \item{algo}{the algorithm to use, must be "ra1", "ra2", "ra3", "ra4"; default is "ra3".} 15 | 16 | \item{metric}{the metric used to calculate the null model: choices are "pianka", "czekanowski", "pianka_var", "czekanowski_var", "pianka_skew", "czekanowski_skew"; default is "pianka".} 17 | 18 | \item{nReps}{the number of replicate null assemblages to create; default is 1000 replicates.} 19 | 20 | \item{saveSeed}{TRUE or FALSE. If TRUE the current seed is saved so the simulation can be repeated; default is FALSE.} 21 | 22 | \item{algoOpts}{a list containing all the options for the specific algorithm you want to use. Must match the algorithm given in the `algo` argument.} 23 | 24 | \item{metricOpts}{a list containing all the options for the specific metric you want to use. Must match the metric given in the `metric` argument.} 25 | 26 | \item{suppressProg}{TRUE or FALSE. If true, display of the progress bar in the console is suppressed; default is FALSE. This setting is useful for creating markdown documents with `knitr`.} 27 | } 28 | \description{ 29 | Create a null model for niche overlap; choices of algorithm and metric are constrained to be valid for niche null models. 30 | } 31 | \examples{ 32 | \dontrun{ 33 | ## Load MacAruthur warbler data 34 | data(dataMacWarb) 35 | 36 | ## Run the null model 37 | warbMod <- niche_null_model(dataMacWarb,nReps=1000) 38 | ## Summary and plot info 39 | summary(warbMod) 40 | plot(warbMod) 41 | plot(warbMod,type="niche") 42 | } 43 | } 44 | 45 | -------------------------------------------------------------------------------- /man/null_model_engine.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/null_model_engine.R 3 | \name{null_model_engine} 4 | \alias{null_model_engine} 5 | \title{Run null model} 6 | \usage{ 7 | null_model_engine(speciesData, algo, metric, nReps = 1000, saveSeed = FALSE, 8 | algoOpts = list(), metricOpts = list(), type = NULL, 9 | suppressProg = FALSE) 10 | } 11 | \arguments{ 12 | \item{speciesData}{a dataframe for analysis that is compatable with the metrics and algorithms used.} 13 | 14 | \item{algo}{the algorithm used to randomize the data.} 15 | 16 | \item{metric}{the metric used to quantify pattern in the data.} 17 | 18 | \item{nReps}{the number of null assemblages to simulate.} 19 | 20 | \item{saveSeed}{Save the existing random seed to allow the user to reproduce the exact model results. The default value is FALSE, in which case the random number seed that is created is not stored in the output.} 21 | 22 | \item{algoOpts}{a list containing options for a supplied alogrithm.} 23 | 24 | \item{metricOpts}{a list containing options for a supplied metric.} 25 | 26 | \item{type}{The type of null model being run. If the null model is intended to be used with one of the existing modules, the type should be "size","niche", or "cooc". If the user is creating an entirely new null model, type should be set to NULL (the default value).} 27 | 28 | \item{suppressProg}{TRUE or FALSE. If true, display of the progress bar in the console is suppressed; default is FALSE. This setting is useful for creating markdown documents with `knitr`.} 29 | } 30 | \description{ 31 | This function drives all the different kinds of null models that can be run. It is the underlying engine. 32 | } 33 | \examples{ 34 | \dontrun{ 35 | # User defined function 36 | 37 | 38 | } 39 | } 40 | 41 | -------------------------------------------------------------------------------- /man/pianka.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{pianka} 4 | \alias{pianka} 5 | \title{Pianka Niche Overlap Metric} 6 | \usage{ 7 | pianka(m = matrix(rpois(80, 1), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{m}{a matrix of resource utilization values.} 11 | } 12 | \value{ 13 | Returns the average pairwise niche overlap. 14 | } 15 | \description{ 16 | Takes a resource utilization matrix as input and 17 | returns the average pairwise Pianka's niche overlap index. 18 | } 19 | \details{ 20 | Pianka's niche overlap index is averaged 21 | over each unique species pair. The index is symmetric, 22 | with a normalization term in the denominator for the overlap 23 | between species 1 and 2. Values of Pianka's niche overlap index close to 0.0 24 | reflect usage of exclusive resource categories, whereas values close to 1.0 25 | reflect similar resource utilization spectra. 26 | \deqn{O_{jk} = O_{kj} = \frac{\sum_{n}^{i}p_{ij}p_{jk}}{\sqrt{\sum_{n}^{i}p_{ij}^2\sum_{n}^{i}p_{ik}^2}}}{O_jk = O_kj = sum(p_ij*p_jk) / sqrt(sum((p_ij)^2)sum((p_jk)^2))} 27 | } 28 | \note{ 29 | The resource utilization matrix (rows = species, columns = discrete 30 | resource categories) may include zeroes, but no negative numbers or missing 31 | values. Relative resource within a species is first calculated, so the rows 32 | need not sum to 1.0. 33 | } 34 | \examples{ 35 | obsOverlap <- pianka(m=matrix(rpois(40,0.5),nrow=8)) 36 | } 37 | \references{ 38 | Pianka, E. 1973. The structure of lizard communities. 39 | Annual Review of Ecology and Systematics 4:53-74. 40 | 41 | Winemiller, K.O. and E.R. Pianka. 1990. Organization in natural assemblages 42 | of desert lizards and tropical fishes. Ecological Monographs 60: 27-55. 43 | } 44 | \seealso{ 45 | \code{\link{czekanowski}} niche overlap index. 46 | } 47 | 48 | -------------------------------------------------------------------------------- /man/pianka_skew.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{pianka_skew} 4 | \alias{pianka_skew} 5 | \title{PiankaSkew Niche Overlap Metric} 6 | \usage{ 7 | pianka_skew(m = matrix(rpois(80, 1), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{m}{a matrix of resource utilization values.} 11 | } 12 | \value{ 13 | Returns the skewness of the average pairwise niche overlap. 14 | } 15 | \description{ 16 | Takes a niche utilization matrix returns the skewness of the 17 | Pianka pairwise niche overlap index. 18 | } 19 | \details{ 20 | A large positive value for skewness implies that there are more species pairs 21 | with high than low niche overlap. A large negative value for skewness implies there are more 22 | species pairs with low than high niche overlap. The performance of this algorithm 23 | has not been thoroughly tested with real data sets. 24 | } 25 | \note{ 26 | The resource utilization matrix (rows = species, columns = discrete 27 | resource categories) may include zeroes, but no negative numbers or missing 28 | values. Relative resource within a species is first calculated, so the rows 29 | need not sum to 1.0. 30 | } 31 | \examples{ 32 | obsSkew<- pianka_skew(m=matrix(rpois(40,0.5),nrow=8)) 33 | } 34 | \references{ 35 | Winemiller, K.O. and E.R. Pianka. 1990. Organization in natural assemblages 36 | of desert lizards and tropical fishes. Ecological Monographs 60: 27-55. 37 | } 38 | \seealso{ 39 | \code{\link{pianka}} niche overlap index. 40 | } 41 | 42 | -------------------------------------------------------------------------------- /man/pianka_var.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{pianka_var} 4 | \alias{pianka_var} 5 | \title{PiankaVariance Niche Overlap Metric} 6 | \usage{ 7 | pianka_var(m = matrix(rpois(80, 1), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{m}{a matrix of resource utilization values.} 11 | } 12 | \value{ 13 | Returns the variance of the average pairwise niche overlap. 14 | } 15 | \description{ 16 | Takes a niche utilization matrix as in put and 17 | returns the variance of Pianka's niche overlap index. 18 | } 19 | \details{ 20 | A large value for variance implies that some species pairs show high 21 | niche overlap and others show low niche overlap. A low value for variance 22 | implies that niche overlap (high or low) is very similar among all species pairs. 23 | } 24 | \note{ 25 | The resource utilization matrix (rows = species, columns = discrete 26 | resource categories) may include zeroes, but no negative numbers or missing 27 | values. Relative resource within a species is first calculated, so the rows 28 | need not sum to 1.0. 29 | } 30 | \examples{ 31 | obsVar <- pianka_var(m=matrix(rpois(40,0.5),nrow=8)) 32 | } 33 | \references{ 34 | Winemiller, K.O. and E.R. Pianka. 1990. Organization in natural 35 | assemblages of desert lizards and tropical fishes. Ecological Monographs 60: 36 | 27-55. 37 | } 38 | \seealso{ 39 | \code{\link{pianka}} niche overlap index. 40 | } 41 | 42 | -------------------------------------------------------------------------------- /man/plot.coocnullmod.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/coccurrence_null.R 3 | \name{plot.coocnullmod} 4 | \alias{plot.coocnullmod} 5 | \title{Co-Occurrence Model Plot Function} 6 | \usage{ 7 | \method{plot}{coocnullmod}(x, type = "hist", ...) 8 | } 9 | \arguments{ 10 | \item{x}{the null model object to plot.} 11 | 12 | \item{type}{the type of null plot to make. See details for more information.} 13 | 14 | \item{...}{Other variables to be passed on to base plotting.} 15 | } 16 | \description{ 17 | Plot co-occurrence null model object. 18 | } 19 | \details{ 20 | the valid types for the Co-occurrence module are "hist" to display a histogram of the simulated metric values, "cooc" to display the observed data matrix and one simulated matrix, and (for sim9 only), "burn_in" to display a trace of the metric values during the burn-in period. 21 | 22 | The "hist" plot type is common to all EcoSimR modules. The blue histogram represents the NRep values of the metric for the simulated assemblages. The red vertical line represents the metric value for the real assemblage. The two pairs of vertical dashed black lines represent the one-tailed (long dash) and two-tailed (short dash) 95% confidence exact confidence intervals of the simulated data. 23 | 24 | The "cooc" plot type illustrates the binary presence-absence data (observed = red, simulated = blue). Each row in the grid is a species, each column is a site, and the entries represent the presence (color-filled) or absence (empty) of a species in a site. The rows and columns are illustrated with the same ordering as the original data matrix. 25 | 26 | The "burn_in" plot type illustrates the trace values of the metric generated for sim9 during the burn-in period. The x axis is the replicate number and the y axis is the value of the metric. The metric for the original data matrix is illustrated as a horizontal red line. Consecutive simulated metric values are illustrated with a blue line, and the gray line is a simple loess fit to the simulated values. If the burn_in period is sufficiently long, the trace should be stable, indicating that a stationary distribution has probably been reached. 27 | } 28 | 29 | -------------------------------------------------------------------------------- /man/plot.nichenullmod.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/niche_overlap_null.R 3 | \name{plot.nichenullmod} 4 | \alias{plot.nichenullmod} 5 | \title{Niche Null Model Plot function} 6 | \usage{ 7 | \method{plot}{nichenullmod}(x, type = "hist", ...) 8 | } 9 | \arguments{ 10 | \item{x}{the null model object to plot.} 11 | 12 | \item{type}{the type of null model plot to display. See details for more information.} 13 | 14 | \item{...}{Other variables to be passed on to base plotting.} 15 | } 16 | \description{ 17 | Plot niche overlap null model object. 18 | } 19 | \details{ 20 | the valid types for the Niche Overlap module are "hist" to display a histogram of the simulated metric values, and "niche" to display the observed data matrix and one simulated matrix. 21 | 22 | The "hist" plot type is common to all EcoSimR modules. The blue histogram represents the NRep values of the metric for the simulated assemblages. The red vertical line represents the metric value for the real assemblage. The two pairs of vertical dashed black lines represent the one-tailed (long dash) and two-tailed (short dash) 95% confidence exact confidence intervals of the simulated data. 23 | 24 | The "niche" plot type illustrates the utilization data (observed = red, simulated = blue). Each row in the figure is a species, and each column is a resource utilization category. The area of each circle depicted is proportional to the utilization of a resoruce category by a species. Empty positions indicate a resource utilization of 0.0. The rows and columns are illustrated with the same ordering as the original data matrix. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/plot.nullmod.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/null_model_engine.R 3 | \name{plot.nullmod} 4 | \alias{plot.nullmod} 5 | \title{plot a histogram null model} 6 | \usage{ 7 | \method{plot}{nullmod}(x, ...) 8 | } 9 | \arguments{ 10 | \item{x}{the null model object to plot.} 11 | 12 | \item{...}{Other variables to be passed on to base plotting.} 13 | } 14 | \description{ 15 | Plot a null model object. 16 | } 17 | \details{ 18 | The "hist" plot type is common to all EcoSimR modules. The blue histogram represents the NRep values of the metric for the simulated assemblages. The red vertical line represents the metric value for the real assemblage. The two pairs of vertical dashed black lines represent the one-tailed (long dash) and two-tailed (short dash) 95% confidence exact confidence intervals of the simulated data. 19 | } 20 | 21 | -------------------------------------------------------------------------------- /man/plot.sizenullmod.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/sizeratio_null.R 3 | \name{plot.sizenullmod} 4 | \alias{plot.sizenullmod} 5 | \title{Size Ratio Plot Function} 6 | \usage{ 7 | \method{plot}{sizenullmod}(x, type = "hist", ...) 8 | } 9 | \arguments{ 10 | \item{x}{the null model object to plot.} 11 | 12 | \item{type}{the type of null model plot to display. See details for more information.} 13 | 14 | \item{...}{Other variables to be passed on to base plotting.} 15 | } 16 | \description{ 17 | Plot Size Ratio null model object. 18 | } 19 | \details{ 20 | the valid types for the Size Overlap module are "hist" to display a histogram of the simulated metric values, and "size" to display the observed data matrix and one simulated matrix. 21 | 22 | The "hist" plot type is common to all EcoSimR modules. The blue histogram represents the NRep values of the metric for the simulated assemblages. The red vertical line represents the metric value for the real assemblage. The two pairs of vertical dashed black lines represent the one-tailed (long dash) and two-tailed (short dash) 95% confidence exact confidence intervals of the simulated data. 23 | 24 | The "size" plot type illustrates the trait data (observed = red, simulated = blue). Each circle in the number line represents the trait value of a different species. For the observed and simulated data, a histogram of the ordered size differences is also illustrated. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/ra1.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{ra1} 4 | \alias{ra1} 5 | \title{RA1 Niche Overlap Randomization Algorithm} 6 | \usage{ 7 | ra1(speciesData = matrix(rpois(80, 1), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{speciesData}{a resource utilization matrix (rows = species, columns = discrete 11 | resource states) filled with non-negative real numbers.} 12 | } 13 | \value{ 14 | Returns a random utilization matrix with the same dimensions as the 15 | input matrix. 16 | } 17 | \description{ 18 | Randomizes a numeric utilization matrix speciesData by 19 | replacing all elements with a random uniform [0,1] value. 20 | } 21 | \details{ 22 | The resource utilization matrix (rows = species, columns = discrete 23 | resource categories) may include zeroes, but no negative numbers or missing 24 | values. Relative resource within a species is first calculated, so the rows 25 | need not sum to 1.0. 26 | } 27 | \note{ 28 | Because all matrix elements, including zeroes, are replaced with a 29 | random uniform distribution, the null expectation is based on an assemblage 30 | of generalist species with maximum niche breadth. This algorithm retains 31 | neither the niche breadth of the individuals species nor the placement of 0 32 | values (= unutilized resource states) in the matrix. These assumptions are 33 | unrealistic, and a random matrix with zeroes will generate significantly low 34 | niche overlap values with this metric. It is not recommended for niche 35 | overlap analysis. 36 | } 37 | \examples{ 38 | ranUtil <- ra1(speciesData=matrix(rpois(40,0.5),nrow=8)) 39 | } 40 | \references{ 41 | Kobayashi, S. 1991. Interspecific relations in forest floor 42 | coleopteran assemblages: niche overlap and guild structure. Researches 43 | in Population Ecology 33: 345-360. 44 | } 45 | 46 | -------------------------------------------------------------------------------- /man/ra2.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{ra2} 4 | \alias{ra2} 5 | \title{RA2 Niche Overlap Randomization Algorithm} 6 | \usage{ 7 | ra2(speciesData = matrix(rpois(80, 1), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{speciesData}{a resource utilization matrix (rows = species, columns = discrete 11 | resource states) filled with non-negative real numbers.} 12 | } 13 | \value{ 14 | Returns a random utilization matrix with the same dimensions as the 15 | input matrix. 16 | } 17 | \description{ 18 | Randomizes a numeric utilization matrix speciesData by 19 | replacing all non-zero elements with a random uniform [0,1] value. 20 | } 21 | \details{ 22 | The resource utilization matrix (rows = species, columns = discrete 23 | resource categories) may include zeroes, but no negative numbers or missing 24 | values. Relative resource within a species is first calculated, so the rows 25 | need not sum to 1.0. 26 | } 27 | \note{ 28 | This algorithm retains the number and position of zero states in the 29 | original matrix. However, all non-zero values are again replaced by a random 30 | [0,1] value, which tends to inflate niche breadths of the simulated 31 | assemblage. Although the results are not as severe as for RA1, this 32 | algorithm is still prone to Type I errors, and is not recommended for niche 33 | overlap analysis. 34 | } 35 | \examples{ 36 | ranUtil <- ra2(speciesData=matrix(rpois(40,0.5),nrow=8)) 37 | } 38 | \references{ 39 | Kobayashi, S. 1991. Interspecific relations in forest floor 40 | coleopteran assemblages: niche overlap and guild structure. Researches 41 | in Population Ecology 33: 345-360. 42 | 43 | Winemiller, K.O. and E.R. Pianka. 1990. Organization in natural 44 | assemblages of desert lizards and tropical fishes. Ecological Monographs 45 | 60: 27-55. 46 | } 47 | 48 | -------------------------------------------------------------------------------- /man/ra3.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{ra3} 4 | \alias{ra3} 5 | \title{RA3 Niche Overlap Randomization Algorithm} 6 | \usage{ 7 | ra3(speciesData = matrix(rpois(80, 1), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{speciesData}{a resource utilization matrix (rows = species, columns = discrete 11 | resource states) filled with non-negative real numbers.} 12 | } 13 | \value{ 14 | Returns a random utilization matrix with the same dimensions as the 15 | input matrix. 16 | } 17 | \description{ 18 | Randomizes a numeric utilization matrix speciesData by 19 | reshuffling the elements within each row. 20 | } 21 | \details{ 22 | The resource utilization matrix (rows = species, columns = discrete 23 | resource categories) may include zeroes, but no negative numbers or missing 24 | values. Relative resource within a species is first calculated, so the rows 25 | need not sum to 1.0. 26 | } 27 | \note{ 28 | This algorithm retains the niche breadth and zero states for each 29 | species, but randomizes the assignment of each utilization value to a 30 | different niche category. It performs effectively in simulation studies and 31 | is recommended for analysis of niche overlap patterns. 32 | } 33 | \examples{ 34 | ranUtil <- ra3(speciesData=matrix(rpois(40,0.5),nrow=8)) 35 | } 36 | \references{ 37 | Winemiller, K.O. and E.R. Pianka. 1990. Organization in natural 38 | assemblages of desert lizards and tropical fishes. Ecological Monographs 39 | 60: 27-55. 40 | } 41 | 42 | -------------------------------------------------------------------------------- /man/ra4.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{ra4} 4 | \alias{ra4} 5 | \title{RA4 Niche Overlap Randomization Algorithm} 6 | \usage{ 7 | ra4(speciesData = matrix(rpois(80, 1), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{speciesData}{a resource utilization matrix (rows = species, columns = discrete 11 | resource states) filled with non-negative real numbers.} 12 | } 13 | \value{ 14 | Returns a random utilization matrix with the same dimensions as the 15 | input matrix. 16 | } 17 | \description{ 18 | Randomizes a numeric utilization matrix speciesData by 19 | reshuffling the non-zero elements within each row. 20 | } 21 | \details{ 22 | The resource utilization matrix (rows = species, columns = discrete 23 | resource categories) may include zeroes, but no negative numbers or missing 24 | values. Relative resource within a species is first calculated, so the rows 25 | need not sum to 1.0. 26 | } 27 | \note{ 28 | This algorithm is similar to RA3, but adds the additional constraint of 29 | retaining the positions of all of the zero elements of the matrix, and 30 | reshuffling only the non-zero elements of the matrix within each row. It is 31 | more conservative than RA3, but has a low Type I error rate, and, along with 32 | RA3, is recommended for null model analysis of niche overlap. 33 | } 34 | \examples{ 35 | ranUtil <- ra4(speciesData=matrix(rpois(40,0.5),nrow=8)) 36 | } 37 | \references{ 38 | Winemiller, K.O. and E.R. Pianka. 1990. Organization in natural 39 | assemblages of desert lizards and tropical fishes. Ecological Monographs 40 | 60: 27-55. 41 | } 42 | 43 | -------------------------------------------------------------------------------- /man/ranMatGen.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/randomMatrixGenerator.R 3 | \name{ranMatGen} 4 | \alias{ranMatGen} 5 | \title{Random Matrix Generator} 6 | \usage{ 7 | ranMatGen(aBetaRow = 1, bBetaRow = 1, aBetaCol = 1, bBetaCol = 1, 8 | numRows = 20, numCols = 5, mFill = 0.5, abun = 0, emptyRow = FALSE, 9 | emptyCol = FALSE) 10 | } 11 | \arguments{ 12 | \item{aBetaRow}{parameter shape1 for beta of row marginals} 13 | 14 | \item{bBetaRow}{parameter shape2 for beta of row marginals} 15 | 16 | \item{aBetaCol}{parameter shape1 for beta of column marginals} 17 | 18 | \item{bBetaCol}{parameter shape2 for beta of column marginals} 19 | 20 | \item{numRows}{number of rows in random matrix} 21 | 22 | \item{numCols}{number of columns in random matrix} 23 | 24 | \item{mFill}{proportion of matrix cells to be filled with non-zero elements} 25 | 26 | \item{abun}{expected total abundance (from Poisson distribution) of individuals in the matrix. If set to the default value of 0, abundances are not shown but are replaced by occurrences (1s)} 27 | 28 | \item{emptyRow}{specifies whether empty rows in random matrix will be retained (TRUE) or stripped out (FALSE)} 29 | 30 | \item{emptyCol}{specified wither empty columns will be retained (TRUE) or stripped out (FALSE)} 31 | } 32 | \description{ 33 | Create a random matrix with specified dimensions, percentage fill, marginal distributions, and matrix type (abundance or binary) to test the behavior of null model randomization algorithms. 34 | } 35 | \details{ 36 | Understanding the behavior of null models with artificial data is an essential step before applying them to real data. This function creates stochastic community matrices in which each row is a species, each column is a site or island, and each entry is the occurrence (presence-absence) or abundance of a species in a site. For the analysis of niche overlap, the sites can be treated as unordered niche categories, and the abundances are the utilization values for each species. 37 | 38 | Row and column marginal distributions are described from a beta distribution, with user supplied coefficients. Marginal distributions are rescaled to one, and the conjoint probability of a species occurring in a site is determined with the outer product of the species (=row) and site(= column) marginals. This simple calculation assumes sites and species are independent, and excludes site x species interactions as well as species x species interactions. 39 | 40 | The user specifies the percent fill of the matrix, and this number of cells are randomly selected without replacement using the cojoint probabilities calculated from each marginal distribution. If the user has requested a presence-absence matrix (`abun = 0'), these cells are assigned a value of 1. If the user has reqested an abundance matrix ('abun > 0'), then the value of abundance specifies the summed abundance of all individuals in the matrix. The value of `abun` is used to set the lambda parameter for each occupied cell, and then a single draw from a Poisson distribution is used for the abundance in that cell. Small conjoint marginal probabilities can lead to empty rows or columns and the user can specify whether or not to retain empty rows and columns. The matrix rows and columns are sorted in descending order according to the marginal frequencies, and these are returned (matrix$rowMarg and matrix$colMarg) along with the matrix (matrix$m) in list form. 41 | 42 | `aBetaRow`, `bBetaRow`, `aBetaCol`, and `bBetaCol` specify the two shape parameters for the row and column marginals. The marginal values are created by a single random draw from these beta distributions, and then are rescaled so they sum to 1.0. Thus, the mean parameter value specified by the beta distribution does not matter in the calculation. Instead, it is the size of the variance that determines the amount of heterogeneity among row or column margins. Small values for the two shape parameters generate greater heterogeneity among the rows or columns marginals of the matrix. 43 | 44 | Thus, a distribution with `aBetaRow=1000` and `bBetaRow=1000` will generate marginal probabilities that are virtually identical for the different species (=rows), whereas `aBetaRow=1` and `bBetaRow=1` will generate uniform probabilities. These default values applied to both rows and columns will generate a typical presence-absence matrix, with some common and some sparse species, and some species-rich and species-poor sites. 45 | 46 | Setting `numRows`, `numCols`, and `mFill` allow the test matrix to be tailored to match the observed matrix. However, it may be necessary to increase `numRows` and `nCols` if the parameters often generate empty rows or columns. 47 | 48 | If low values of `abun` are specified, some occupied cells may be set to 0 because of a random draw from the Poisson distribution for that matrix cell. 49 | 50 | Once the test matrix is created, it can be used to explore any of the combinations of algorithm and matrix that are available in EcoSimR. 51 | } 52 | \examples{ 53 | \dontrun{ 54 | ## Create a null matrix similar to MacArthur's warblers 55 | testMatrix <- ranMatGen(aBetaCol=1000,bBetaCol=1000, 56 | aBetaRow=1,bBetaRow=1, 57 | numRows=5,numCols=16, 58 | mFill=0.75, abun=1000, 59 | emptyRow=FALSE,emptyCol=TRUE)$m 60 | 61 | ## Run the null model 62 | testMod <- niche_null_model(testMatrix) 63 | 64 | ## Summary and niche utilization plot 65 | summary(testAnalysis) 66 | plot(testMod,type="niche") 67 | 68 | 69 | ## Create a null matrix similar to West Indies Finches 70 | testMatrix <- ranMatGen(aBetaCol=0.5,bBetaCol=0.5, 71 | aBetaRow=0.5,bBetaRow=0.5, 72 | numRows=30,numCols=30, 73 | mFill=0.25,abun=0,emptyRow=FALSE, 74 | emptyCol=FALSE)$m 75 | 76 | ## Run the null model 77 | testMod <- cooc_null_model(testMatrix$m, 78 | algo="simFast", 79 | burnin=10000,n.reps=1000) 80 | 81 | ## Summary and matrix, burn-in plots 82 | summary(testMod) 83 | plot(testMod,type="cooc") 84 | plot(testMod,type="burnin") 85 | } 86 | } 87 | 88 | -------------------------------------------------------------------------------- /man/reproduce_model.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/reproduce_model.R 3 | \name{reproduce_model} 4 | \alias{reproduce_model} 5 | \title{Reproduce a result} 6 | \usage{ 7 | reproduce_model(model) 8 | } 9 | \arguments{ 10 | \item{model}{the model object containing the result to be reproduced.} 11 | } 12 | \description{ 13 | Helps reproduce the result of a simulation by restoring the RNG to the state of a supplied null model object. 14 | } 15 | \details{ 16 | Works by resetting the RNG state to what it was for a given EcoSimR simulation. This only works if the user saved the seed with the saveSeed parameter. 17 | } 18 | \examples{ 19 | \dontrun{ 20 | finchMod <- cooc_null_model(dataWiFinches, algo="sim1",saveSeed=T) 21 | ## Check model output 22 | mean(finchMod$Sim) 23 | 24 | reproduce_model(finchMod) 25 | 26 | finchMod <- cooc_null_model(dataWiFinches, algo="sim1") 27 | ## Check model output is the same as before 28 | mean(finchMod$Sim) 29 | reproduce_model(finchMod) 30 | } 31 | } 32 | 33 | -------------------------------------------------------------------------------- /man/sim1.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{sim1} 4 | \alias{sim1} 5 | \title{Sim1 Co-occurrence Randomization Algorithm} 6 | \usage{ 7 | sim1(speciesData) 8 | } 9 | \arguments{ 10 | \item{speciesData}{binary presence-absence matrix 11 | (rows = species, columns = sites).} 12 | } 13 | \value{ 14 | Returns a binary presence-absence matrix with the same 15 | dimensions and percent fill as the input matrix. 16 | } 17 | \description{ 18 | Randomizes a binary matrix speciesData by reshuffling 19 | all of its elements equiprobably. 20 | } 21 | \details{ 22 | This algorithm assumes species and sites are equiprobable. 23 | It preserves the total matrix fill, but places no other constraints on 24 | row or column totals. 25 | } 26 | \note{ 27 | This is the simplest of all randomization algorithms for a presence- 28 | absence matrix. However, it assumes that both species and sites are 29 | equiprobable, and has poor Type I error frequencies when tested with 30 | purely random matrices. If the input matrix is sparse, it will often 31 | generate null matrices with empty rows or columns. Not recommended for 32 | co-occurrence analysis. 33 | } 34 | \examples{ 35 | randomMatrix <- sim1(speciesData=matrix(rbinom(40,1,0.5),nrow=8)) 36 | } 37 | \references{ 38 | Gotelli, N.J. 2000. Null model analysis of species co-occurrence 39 | patterns. Ecology 81: 2606-2621. 40 | } 41 | 42 | -------------------------------------------------------------------------------- /man/sim10.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{sim10} 4 | \alias{sim10} 5 | \title{Sim10 Co-occurrence Randomization Algorithm} 6 | \usage{ 7 | sim10(speciesData, rowWeights = runif(dim(speciesData)[1]), 8 | colWeights = runif(dim(speciesData)[2])) 9 | } 10 | \arguments{ 11 | \item{speciesData}{binary presence-absence matrix 12 | (rows = species, columns = sites).} 13 | 14 | \item{rowWeights}{vector of positive values representing species weights.} 15 | 16 | \item{colWeights}{vector of positive values representing site weights.} 17 | } 18 | \value{ 19 | Returns a binary presence-absence matrix with the same 20 | dimensions and fill as the input matrix. 21 | } 22 | \description{ 23 | Randomizes a binary matrix speciesData by reshuffling all 24 | elements. Rows and column probabilities are proportional to user-supplied 25 | row and column weights, which define relative suitability probabilities for 26 | species and sites. Makes a call to the vector_sample function. 27 | } 28 | \details{ 29 | This function incorporates vectors of weights for species and/or 30 | sites to condition the simulation. These two vectors are used as outer 31 | products to set cell probabilities for the entire matrix. Thus: 32 | \deqn{p(cell_{ij})=p(row_i)p(col_j)}{p(cell_ij)=p(row_i)p(col_j)} 33 | Weights must be positive real numbers. The algorithm will scale them so they 34 | sum to 1.0, so they can be used in their natural units (e.g. island area, 35 | species abudance), and will be scaled properly. If all species (or sites) 36 | are assumed to be equally likely, the weight vector should be set to the 37 | same constant for all elements. 38 | } 39 | \note{ 40 | sim10 allows users to incorporate independent data on species 41 | occurrence probabilities and site suitabilities. This represents an 42 | important conceptual advance over standard co-occurrence analyses, which 43 | must infer these probabilities from the matrix itself. sim10 may generate 44 | empty rows or columns, especially if weights are very small for some species 45 | or sites. Also, the results may be sensitive to algebraic transformations 46 | of the weights (x, x^2, log(x), etc.), and these transformations may be hard 47 | to justify biologically. Nevertheless, sim10 is worth exploring for rich 48 | data sets with site and species attributes. 49 | } 50 | \examples{ 51 | randomMatrix <- sim10(speciesData=matrix(rbinom(40,1,0.5),nrow=8)) 52 | } 53 | \references{ 54 | Jenkins, D.G. 2006. In search of quorum effects in metacommunity 55 | structure: species co-occurrence analyses. Ecology 87:1523-1531 56 | 57 | Gotelli, N.J., G.R. Graves, and C. Rahbek. 2010. Macroecological 58 | signals of species interactions in the Danish avifauna. Proceedings of the 59 | National Academy of Sciences, U.S.A. 107: 530-535. 60 | } 61 | \seealso{ 62 | \code{\link{vector_sample}} for weighted vector sampling. 63 | } 64 | 65 | -------------------------------------------------------------------------------- /man/sim2.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{sim2} 4 | \alias{sim2} 5 | \title{Sim2 Co-occurrence Randomization Algorithm} 6 | \usage{ 7 | sim2(speciesData) 8 | } 9 | \arguments{ 10 | \item{speciesData}{binary presence-absence matrix 11 | (rows = species, columns = sites).} 12 | } 13 | \value{ 14 | Returns a binary presence-absence matrix with the same 15 | dimensions and rowsums as the input matrix. 16 | } 17 | \description{ 18 | Randomizes a binary matrix speciesData by reshuffling elements 19 | within each row equiprobably. 20 | } 21 | \details{ 22 | This algorithm assumes sites are equiprobable, but preserves 23 | differences among species (= row sums). 24 | } 25 | \note{ 26 | This algorithm preserves differences in the commonness and rarity of 27 | species (= rowsums), but assumes that all sites are equiprobable. It would 28 | not be appropriate for islands that vary greatly in area, but it would be 29 | appropriate for quadrat censuses in a relatively homogeneous environment. 30 | sim2 can sometimes generate matrices with empty columns, but this is 31 | unlikely unless the matrix is very sparse. sim2 has good Type I error 32 | frequenceis when tested against random matrices. However, if sites do vary 33 | in their suitability or habitat quality, it will often identify aggregated 34 | patterns of species co-occurrence. sim2 and sim9 have the best overall 35 | performance for species co-occurrence analyses. However, because they differ 36 | in their assumptions about site quality, they often differ in their results, 37 | with sim9 often detecting random or segregated patterns for matrices in 38 | which sim2 detects aggregated patterns. 39 | } 40 | \examples{ 41 | randomMatrix <- sim2(speciesData=matrix(rbinom(40,1,0.5),nrow=8)) 42 | } 43 | \references{ 44 | Gotelli, N.J. 2000. Null model analysis of species co-occurrence 45 | patterns. ecology 81: 2606-2621. 46 | } 47 | \seealso{ 48 | \code{\link{sim9}} co-occurrence algorithm. 49 | } 50 | 51 | -------------------------------------------------------------------------------- /man/sim3.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{sim3} 4 | \alias{sim3} 5 | \title{Sim3 Co-occurrence Randomization Algorithm} 6 | \usage{ 7 | sim3(speciesData) 8 | } 9 | \arguments{ 10 | \item{speciesData}{binary presence-absence matrix 11 | (rows = species, columns = sites).} 12 | } 13 | \value{ 14 | Returns a binary presence-absence matrix with the same 15 | dimensions and colsums as the input matrix. 16 | } 17 | \description{ 18 | Randomizes a binary matrix speciesData by reshuffling elements 19 | within each column equiprobably. 20 | } 21 | \details{ 22 | This algorithm assumes species are equiprobable, but preserves 23 | differences among sites (= column sums). 24 | } 25 | \note{ 26 | This algorithm preserves differences in species richness among sites 27 | (= colsums), but assumes that all species are equiprobable. This assumption 28 | is usually unrealistic, and sim3 has a high frequency of Type I errors with 29 | random matrices, so it is not recommended for co-occurrence analysis. 30 | } 31 | \examples{ 32 | randomMatrix <- sim3(speciesData=matrix(rbinom(40,1,0.5),nrow=8)) 33 | } 34 | \references{ 35 | Gotelli, N.J. 2000. Null model analysis of species co-occurrence 36 | patterns. Ecology 81: 2606-2621. 37 | } 38 | 39 | -------------------------------------------------------------------------------- /man/sim4.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{sim4} 4 | \alias{sim4} 5 | \title{Sim4 Co-occurrence Randomization Algorithm} 6 | \usage{ 7 | sim4(speciesData) 8 | } 9 | \arguments{ 10 | \item{speciesData}{binary presence-absence matrix 11 | (rows = species, columns = sites).} 12 | } 13 | \value{ 14 | Returns a binary presence-absence matrix with the same 15 | dimensions and rowsums as the input matrix. 16 | } 17 | \description{ 18 | Randomizes a binary matrix speciesData by reshuffling elements 19 | within each row. Sampling weights for each column are proportional to 20 | column sums. Makes a call to the vector_sample function. 21 | } 22 | \details{ 23 | This algorithm preserves differences among species in occurrence 24 | frequencies, but assumes differences among sites in suitability are 25 | proportional to observed species richness (= column sums). 26 | } 27 | \note{ 28 | This algorithm preserves differences in the commonness and rarity of 29 | species (= rowsums), but assumes differences among sites in suitability are 30 | proportional to observed species richness (= column sums). sim4 has a 31 | somewhat high frequency of Type I errors with random matrices, so it is not 32 | recommended for co-occurrence analysis. 33 | } 34 | \examples{ 35 | randomMatrix <- sim4(speciesData = matrix(rbinom(40,1,0.5),nrow=8)) 36 | } 37 | \references{ 38 | Gotelli, N.J. 2000. Null model analysis of species co-occurrence 39 | patterns. Ecology 81: 2606-2621. 40 | } 41 | 42 | -------------------------------------------------------------------------------- /man/sim5.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{sim5} 4 | \alias{sim5} 5 | \title{Sim5 Co-occurrence Randomization Algorithm} 6 | \usage{ 7 | sim5(speciesData) 8 | } 9 | \arguments{ 10 | \item{speciesData}{binary presence-absence matrix 11 | (rows = species, columns = sites).} 12 | } 13 | \value{ 14 | Returns a binary presence-absence matrix with the same 15 | dimensions and colsums as the input matrix. 16 | } 17 | \description{ 18 | Randomizes a binary matrix speciesData by reshuffling elements 19 | within each column. Sampling weights for each row are proportional to 20 | row sums. Makes a call to the vector_sample function. 21 | } 22 | \details{ 23 | This algorithm preserves differences among sites in species 24 | richness, but assumes differences among species in commonness and rarity 25 | are proportional to observed species occurrences (= row sums). 26 | } 27 | \note{ 28 | This algorithm preserves differences among sites in species richness 29 | (= colsums), but assumes differences among species in commonness and rarity 30 | are proportional to observed species occurrences (= rowsums). sim5 has a 31 | high frequency of Type I errors with random matrices, so it is not 32 | recommended for co-occurrence analysis. 33 | } 34 | \examples{ 35 | randomMatrix <- sim5(speciesData = matrix(rbinom(40,1,0.5),nrow=8)) 36 | } 37 | \references{ 38 | Gotelli, N.J. 2000. Null model analysis of species co-occurrence 39 | patterns. Ecology 81: 2606-2621. 40 | } 41 | 42 | -------------------------------------------------------------------------------- /man/sim6.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{sim6} 4 | \alias{sim6} 5 | \title{Sim6 Co-occurrence Randomization Algorithm} 6 | \usage{ 7 | sim6(speciesData) 8 | } 9 | \arguments{ 10 | \item{speciesData}{binary presence-absence matrix 11 | (rows = species, columns = sites).} 12 | } 13 | \value{ 14 | Returns a binary presence-absence matrix with the same 15 | dimensions and fill as the input matrix. 16 | } 17 | \description{ 18 | Randomizes a binary matrix speciesData by reshuffling all 19 | elements. Rows are equiprobable, and columns are proportional to column sums. 20 | Makes a call to the vector_sample function. 21 | } 22 | \details{ 23 | This algorithm assumes that species are equiprobable, but that 24 | differences in suitability among sites are proportional to observed species 25 | richness (=colsums). 26 | } 27 | \note{ 28 | This algorithm assumes that species are equiprobable, and that 29 | differences among sites are proportional to observed species richness 30 | (=colsums). sim6 has a high frequency of Type I errors with random matrices, 31 | so it is not recommended for co-occurrence analysis. 32 | } 33 | \examples{ 34 | randomMatrix <- sim6(speciesData = matrix(rbinom(40,1,0.5),nrow=8)) 35 | } 36 | \references{ 37 | Gotelli, N.J. 2000. Null model analysis of species co-occurrence 38 | patterns. Ecology 81: 2606-2621. 39 | } 40 | 41 | -------------------------------------------------------------------------------- /man/sim7.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{sim7} 4 | \alias{sim7} 5 | \title{Sim7 Co-occurrence Randomization Algorithm} 6 | \usage{ 7 | sim7(speciesData) 8 | } 9 | \arguments{ 10 | \item{speciesData}{binary presence-absence matrix 11 | (rows = species, columns = sites).} 12 | } 13 | \value{ 14 | Returns a binary presence-absence matrix with the same 15 | dimensions and fill as the input matrix. 16 | } 17 | \description{ 18 | Randomizes a binary matrix speciesData by reshuffling all 19 | elements. Columns are equiprobable, and rows are proportional to row sums. 20 | Makes a call to the vector_sample function. 21 | } 22 | \details{ 23 | This algorithm assumes that sites are equiprobable, but that 24 | differences in frequency of occurrence among species are proportional to 25 | observed species richness (=colsums). 26 | } 27 | \note{ 28 | This algorithm assumes that species are equiprobable, and that 29 | differences among sites are proportional to observed species richness 30 | (=colsums). sim7 has a high frequency of Type I errors with random matrices, 31 | so it is not recommended for co-occurrence analysis. 32 | } 33 | \examples{ 34 | randomMatrix <- sim7(speciesData = matrix(rbinom(40,1,0.5),nrow=8)) 35 | } 36 | \references{ 37 | Gotelli, N.J. 2000. Null model analysis of species co-occurrence 38 | patterns. Ecology 81: 2606-2621. 39 | } 40 | 41 | -------------------------------------------------------------------------------- /man/sim8.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{sim8} 4 | \alias{sim8} 5 | \title{Sim8 Co-occurrence Randomization Algorithm} 6 | \usage{ 7 | sim8(speciesData) 8 | } 9 | \arguments{ 10 | \item{speciesData}{binary presence-absence matrix 11 | (rows = species, columns = sites).} 12 | } 13 | \value{ 14 | Returns a binary presence-absence matrix with the same 15 | dimensions and fill as the input matrix. 16 | } 17 | \description{ 18 | Randomizes a binary matrix speciesData by reshuffling all 19 | elements. Columns are proportional to column sums, and rows are proportional 20 | to row sums. Makes a call to the vector_sample function. 21 | } 22 | \details{ 23 | This algorithm assumes that the probability that a species occurs 24 | in a site is depends on the joint independent probability of randomly 25 | selecting the species and randomly selecting the site, with these 26 | probabilities set proportional to row and column sums of the matrix. 27 | } 28 | \note{ 29 | This algorithm is theoretically attractive because it incorporates 30 | heterogeneity in species occurrences and species richness per site in a 31 | probabilistic way that does not fix row and column frquencies. However, 32 | in spite of its appeal, sim8 does not generate average row and column sums 33 | that match the original matrix, and it is susceptible to Type I errors when 34 | tested with random matrices. It is not recommended for co-occurrence 35 | analysis. See Ulrich and Gotelli (2012) for a more complicated algorithm 36 | for probabilistic row and column totals that has better statistical behavior. 37 | } 38 | \examples{ 39 | randomMatrix <- sim8(speciesData = matrix(rbinom(40,1,0.5),nrow=8)) 40 | } 41 | \references{ 42 | Gotelli, N.J. 2000. Null model analysis of species co-occurrence 43 | patterns. Ecology 81: 2606-2621. 44 | 45 | Ulrich, W. and N.J. Gotelli. 2012. A null model algorithm for presence- 46 | absence matrices based on proportional resampling. Ecological Modelling 47 | 244:20-27. 48 | } 49 | 50 | -------------------------------------------------------------------------------- /man/sim9.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/sim9fast.R 3 | \name{sim9} 4 | \alias{sim9} 5 | \title{Sim9 Co-occurrence Randomization Algorithm} 6 | \usage{ 7 | sim9(speciesData, algo, metric, nReps = 1000, saveSeed = FALSE, 8 | burn_in = 0, algoOpts = list(), metricOpts = list(), 9 | suppressProg = TRUE) 10 | } 11 | \arguments{ 12 | \item{speciesData}{a dataframe in which rows are species, columns are sites, 13 | and the entries indicate the absence (0) or presence (1) of a species in a 14 | site. Empty rows and empty columns should not be included in the matrix.} 15 | 16 | \item{algo}{the algorithm to use, must be "sim1", "sim2", "sim3", "sim4", "sim5", "sim6", "sim7", "sim8", "sim9", "sim10"; default is "sim9".} 17 | 18 | \item{metric}{the metric used to calculate the null model: choices are "species_combo", "checker", "c_score", "c_score_var", "c_score_skew", "v_ratio"; default is "c_score".} 19 | 20 | \item{nReps}{the number of replicate null assemblages to create; default is 1000 replicates.} 21 | 22 | \item{saveSeed}{TRUE or FALSE. If TRUE the current seed is saved so the simulation can be repeated; default is FALSE.} 23 | 24 | \item{burn_in}{The number of burn_in iterations to use with the simFast algorithm; default is 500 burn-in replicates.} 25 | 26 | \item{algoOpts}{a list containing all the options for the specific algorithm you want to use. Must match the algorithm given in the `algo` argument.} 27 | 28 | \item{metricOpts}{a list containing all the options for the specific metric you want to use. Must match the metric given in the `metric` argument.} 29 | 30 | \item{suppressProg}{TRUE or FALSE. If true, display of the progress bar in the console is suppressed; default is FALSE. This setting is useful for creating markdown documents with `knitr`.} 31 | } 32 | \description{ 33 | An improved implementation of the sequential swap algorithm. 34 | } 35 | \details{ 36 | Generating a set of random matrices with fixed row and column sums is a challenging computational problem. In the ecological literature, these matrices have been created by an MCMC "sequential swap" algorithm (Gotelli 2000). Two rows are two columns are chosen randomly ,and if the 4 cells form a 01/10 pattern, the cell values can be swapped to 10/01 and then replaced in the matrix. This generates a slightly different matrix with the same row and column totals. If the cells cannot be swapped, the trial is discarded. Because only 4 cells are reshuffled, it takes many successive swaps to eliminate transient effects as the matrix moves away from the original configuration and approaches a stationary distribution. A second disadvantage of the sequential swap is that all matrices are not sampled equiprobably because the failed swaps are discarded. This bias seems small for binary matrices that are typically generated by ecological studies (< 100 x 100), but could be important for "big data" applications. 37 | 38 | EcoSimR uses an unbiased and more efficient algorithm, which Strona et al. (2014) have recently dubbed the "curveball algorithm". In this algorithm, two rows from the matrix are randomly chosen to create a submatrix. Within the submatrix, columns in which the column sums are equal to zero are randomly swapped. The resulting submatrix is then returned to the full matrix, with modified values in two of the rows. If no swapping is possible (which is an improbable event for most ecological matrices), the unswapped matrix is still retained. The curveball algorithm is much more efficient than the sequential swap because most iterations reshuffle many elements in the matrix simultaneously. Strona et al. (2014) show empirically that this algorithm gives unbiased results. However, the resulting MCMC chains will still exhibit autocorrelation for consecutive matrices, especially if the matrix is very large. Future versions of EcoSimR will allow for a thinning parameter to avoid using every sequential matrix from the MCMC chain. The current version of EcoSimR allows for control over the burn-in period and generates a burn-in plot so the user can see whether stationarity has been achieved. 39 | } 40 | \examples{ 41 | \dontrun{ 42 | 43 | ## Run the null model 44 | finchMod <- cooc_null_model(dataWiFinches, algo="sim1",nReps=1000000,burn_in = 500) 45 | ## Summary and plot info 46 | summary(finchMod) 47 | plot(finchMod,type="burn_in") 48 | plot(finchMod,type="hist") 49 | plot(finchMod,type="cooc") 50 | } 51 | } 52 | \references{ 53 | Chen, Y., P. Diaconis, S.P. Holmes, and J.S. Liu. 2005. Sequential Monte Carlo methods for statistical analysis of tables. JASA 100: 109-120. 54 | 55 | Cobb, G. W., and Chen, Y.-P. 2003. An Application of Markov Chain Monte Carlo to Community Ecology. American Mathematical Monthly 110: 265-288. 56 | 57 | Gotelli, N.J. 2000. Null model analysis of species co-occurrence patterns. Ecology 81: 2606-2621. 58 | 59 | Strona. G., D. Nappo, F. Boccacci, S. Fattorini, and J. San-Miguel-Ayanz. 2014. A fast and unbiased procedure to randomize ecological binary matrices with fixed row and column totals. Nature Communications 5:4114 | DOI: 10.1038/ncomms5114. 60 | } 61 | 62 | -------------------------------------------------------------------------------- /man/sim9_single.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/sim9fast.R 3 | \name{sim9_single} 4 | \alias{sim9_single} 5 | \title{sim9_single} 6 | \usage{ 7 | sim9_single(speciesData = matrix(rbinom(100, 1, 0.5), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{speciesData}{binary presence-absence matrix.} 11 | } 12 | \description{ 13 | Function for a single iteration of the sequential swap. 14 | } 15 | \details{ 16 | See details for sim9. 17 | } 18 | 19 | -------------------------------------------------------------------------------- /man/size_gamma.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{size_gamma} 4 | \alias{size_gamma} 5 | \title{SizeGamma Size Overlap Randomization Algorithm} 6 | \usage{ 7 | size_gamma(speciesData = rnorm(50, mean = 100, sd = 1)) 8 | } 9 | \arguments{ 10 | \item{speciesData}{a vector of body sizes or other trait measurements of 11 | species. All values must be positive real numbers.} 12 | } 13 | \value{ 14 | Returns a vector of simulated body sizes as the same length as speciesData. 15 | } 16 | \description{ 17 | Function to generate a random distribution of body sizes by 18 | drawing from a gamma distribution. Shape and rate parameters of the gamma 19 | are estimated from the empirical data. 20 | } 21 | \note{ 22 | The shape and rate parameters are estimated from the real data using 23 | the maximum likelihood estimators generated from the fitdr function in 24 | the MASS library. The flexible gamma distribution can be fit to a variety of 25 | normal, log-normal, and exponential distributions that are typical for trait 26 | data measured on a continuous non-negative scale. 27 | } 28 | \examples{ 29 | obsOverlap <- size_gamma(speciesData=rnorm(50,mean=100,sd=1)) 30 | } 31 | \seealso{ 32 | \code{\link{fitdistr}} in the MASS library. 33 | } 34 | 35 | -------------------------------------------------------------------------------- /man/size_null_model.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/sizeratio_null.R 3 | \name{size_null_model} 4 | \alias{size_null_model} 5 | \title{Size Ratio} 6 | \usage{ 7 | size_null_model(speciesData, algo = "size_uniform", metric = "var_ratio", 8 | nReps = 1000, saveSeed = FALSE, algoOpts = list(), 9 | metricOpts = list(), suppressProg = FALSE) 10 | } 11 | \arguments{ 12 | \item{speciesData}{a data vector in which each entry is the measured trait (such as body size or flowering date) for each species in the assemblage.} 13 | 14 | \item{algo}{the algorithm to use, must be "size_uniform", "size_uniform_user", "size_source_pool", "size_gamma".} 15 | 16 | \item{metric}{the metric used to caluclate the null model: choices are "min_diff", "min_ratio", "var_diff", "var_ratio"; default is "var_ratio".} 17 | 18 | \item{nReps}{the number of replicate null assemblages to create; default is 1000 replicates.} 19 | 20 | \item{saveSeed}{TRUE or FALSE. If TRUE the current seed is saved so the simulation can be repeated; default is FALSE.} 21 | 22 | \item{algoOpts}{a list containing all the options for the specific algorithm you want to use. Must match the algorithm given in the `algo` argument.} 23 | 24 | \item{metricOpts}{a list containing all the options for the specific metric you want to use. Must match the metric given in the `metric` argument.} 25 | 26 | \item{suppressProg}{TRUE or FALSE. If true, display of the progress bar in the console is suppressed; default is FALSE. This setting is useful for creating markdown documents with `knitr`.} 27 | } 28 | \description{ 29 | Create a Size Ratio null model 30 | } 31 | \examples{ 32 | \dontrun{ 33 | ## Run the null model 34 | rodentMod <- size_null_model(dataRodents) 35 | ## Summary and plot info 36 | summary(rodentMod) 37 | plot(rodentMod,type="hist") 38 | plot(rodentMod,type="size") 39 | 40 | ## Uniform Size model with user inputs 41 | rodentMod2 <- size_null_model(dataRodents,algo="size_uniform_user", 42 | algoOpts = list(userLow = 3,userHigh=15)) 43 | summary(rodentMod2) 44 | plot(rodentMod2,type="hist") 45 | plot(rodentMod2,type="size") 46 | 47 | ### Source pool model 48 | 49 | rodentMod_sp <- size_null_model(dataRodents,algo="size_source_pool", 50 | algoOpts = list(sourcePool = runif(dim(dataRodents)[1],1,15))) 51 | 52 | summary(rodentMod_sp) 53 | plot(rodentMod_sp,type="hist") 54 | plot(rodentMod_sp,type="size") 55 | 56 | } 57 | } 58 | 59 | -------------------------------------------------------------------------------- /man/size_source_pool.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{size_source_pool} 4 | \alias{size_source_pool} 5 | \title{SizeSourcePoolDraw Size Overlap Randomization Algorithm} 6 | \usage{ 7 | size_source_pool(speciesData = 21:30, sourcePool = runif(n = 2 * 8 | length(speciesData), min = 10, max = 50), speciesProbs = rep(1, 9 | length(sourcePool))) 10 | } 11 | \arguments{ 12 | \item{speciesData}{a vector of observed body sizes.} 13 | 14 | \item{sourcePool}{a vector of body sizes of species in the user-defined 15 | pool of potential colonists.} 16 | 17 | \item{speciesProbs}{a vector of relative colonization weights of 18 | length 'sourcePool'.} 19 | } 20 | \value{ 21 | Returns a vector of body sizes of an assemblage randomly drawn 22 | from a user-defined source pool. 23 | } 24 | \description{ 25 | Function to randomize body sizes by drawing species from a 26 | user-defined source pool. Species are drawn without replacement, 27 | and there is a specified probability vector for the source pool species 28 | } 29 | \note{ 30 | Although delineating a source pool of species and estimating their 31 | relative colonization probabilities is difficult, this is the most realistic 32 | approach to constructing a null distribution. 33 | } 34 | \examples{ 35 | obsOverlap <- size_source_pool(dataRodents$Sonoran) 36 | } 37 | \references{ 38 | Strong, D.R. Jr., L.A. Szyska, and D. Simberloff. 1979. Tests of 39 | community-wide character displacement against null hypotheses. Evolution 33: 40 | 897-913. 41 | Schluter, D. and P.R. Grant. 1984. Determinants of morphological patterns in 42 | communities of Darwin's finches. American Naturalist 123: 175-196. 43 | } 44 | 45 | -------------------------------------------------------------------------------- /man/size_uniform.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{size_uniform} 4 | \alias{size_uniform} 5 | \title{SizeUniform Size Overlap Randomization Algorithm} 6 | \usage{ 7 | size_uniform(speciesData = runif(20)) 8 | } 9 | \arguments{ 10 | \item{speciesData}{a vector of positive real values representing the body 11 | sizes or trait values for each species.} 12 | } 13 | \value{ 14 | Returns a vector of body sizes that have been randomly assigned. The 15 | largest and smallest body sizes in the randomized assemblage match those in 16 | the empirical data. 17 | } 18 | \description{ 19 | Function to randomize body sizes within a uniform distribution 20 | with boundaries set by the largest and smallest species in the assemblage. 21 | } 22 | \details{ 23 | If the assemblage contains n species, 24 | only the body sizes of the inner n - 2 species are randomized. 25 | } 26 | \note{ 27 | Although the distribution of body sizes may not be truly uniform, 28 | it may be approximately uniform within the range of observed values, 29 | particularly for small assemblages. 30 | } 31 | \examples{ 32 | nullSizes <-size_uniform(speciesData=runif(20)) 33 | } 34 | \references{ 35 | Simberloff, D. and W. Boecklen. 1981. Santa Rosalia 36 | reconsidered: size ratios and competition. Evolution 35: 1206-1228. 37 | 38 | Tonkyn, D.W. and B.J. Cole. 1986. The statistical analysis of size ratios. 39 | American Naturalist 128: 66-81. 40 | } 41 | \seealso{ 42 | \code{\link{size_gamma}} size distribution function. 43 | } 44 | 45 | -------------------------------------------------------------------------------- /man/size_uniform_user.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{size_uniform_user} 4 | \alias{size_uniform_user} 5 | \title{SizeUser Size Overlap Randomization Algorithm} 6 | \usage{ 7 | size_uniform_user(speciesData = runif(n = 20), userLow = 0.9 * 8 | min(speciesData), userHigh = 1.1 * max(speciesData)) 9 | } 10 | \arguments{ 11 | \item{speciesData}{a vector of observed body sizes.} 12 | 13 | \item{userLow}{a user-defined lower limit.} 14 | 15 | \item{userHigh}{a user-defined upper limit.} 16 | } 17 | \value{ 18 | Returns a vector of randomized body sizes. 19 | } 20 | \description{ 21 | Observed body sizes are randomized with a uniform distribution 22 | for which the user has defined the minimum and maximum possible body size. 23 | } 24 | \details{ 25 | Within the user-defined limits, body sizes of all n species are 26 | randomized, whereas uniform_size randomizes only n - 2 of the body 27 | sizes and uses the extreme values to set the endpoints. 28 | } 29 | \note{ 30 | As the difference between the lower and upper boundaries is increased 31 | the test will yield results that are random or aggregated, even though the 32 | same data might yield a segregated pattern when the uniform_size algorithm 33 | is used. For this reason, this algorithm is not recommended for size ratio 34 | analyses. 35 | } 36 | \examples{ 37 | nullSizes <- size_uniform_user(speciesData=runif(20,min=10,max=20),userLow=8,userHigh=24) 38 | } 39 | \seealso{ 40 | \code{\link{size_uniform}} size distribution algorithm. 41 | } 42 | 43 | -------------------------------------------------------------------------------- /man/species_combo.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{species_combo} 4 | \alias{species_combo} 5 | \title{SpeciesCombo Co-occurrence Metric} 6 | \usage{ 7 | species_combo(m = matrix(rbinom(100, 1, 0.5), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{m}{a binary presence-absence matrix in which rows are species and columns 11 | are sites.} 12 | } 13 | \value{ 14 | Returns the number of unique species combinations represented by 15 | the different columns (= sites) in the matrix. 16 | } 17 | \description{ 18 | Function to calculate number of unique species combinations in a matrix 19 | } 20 | \details{ 21 | In Diamond's (1975) assembly rules model, species interactions lead to 22 | certain "forbidden combinations" of species. A set of communities structured 23 | this way should contain fewer species combinations than expected by chance. 24 | } 25 | \note{ 26 | This metric is most useful when the number of sites (= columns) is relatively 27 | large compared to the number of species (= rows). Empty sites are excluded 28 | from the matrix and are not counted as a unique species combination. 29 | } 30 | \examples{ 31 | obsCombo <- species_combo(m=matrix(rbinom(100,1,0.5),nrow=10)) 32 | } 33 | \references{ 34 | Diamond, J.M. 1975. Assembly of species communities. p. 342-444 in: 35 | Ecology and Evolutoin of Communities. M.L. Cody and J.M. Diamond (eds.). 36 | Harvard University Press, Cambridge. 37 | 38 | Pielou, D.P. and E.C. Pielou. 1968. Association among species of infrequent 39 | occurrence: the insect and spider fauna of Polyporus betulinus (Bulliard) Fries. 40 | Journal of Theoretical Biology 21: 202-216. 41 | } 42 | 43 | -------------------------------------------------------------------------------- /man/summary.coocnullmod.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/coccurrence_null.R 3 | \name{summary.coocnullmod} 4 | \alias{summary.coocnullmod} 5 | \title{Generic function for calculating null model summary statistics.} 6 | \usage{ 7 | \method{summary}{coocnullmod}(object, ...) 8 | } 9 | \arguments{ 10 | \item{object}{the null model object to print a summary.} 11 | 12 | \item{...}{extra parameters} 13 | } 14 | \description{ 15 | Takes as input a list of Null.Model.Out, with Obs, Sim, Elapsed Time, and Time Stamp values. 16 | } 17 | \details{ 18 | The summary output includes a timestamp and complete statistics on the simulated values of the metric, including the mean, variance, and one and two-tailed 95% confidence intervals. The lower and upper tails for the observed value are given, as is the standardized effect size (SES), which is calculated as the (Metric(obs) - average(Metric(sim)))/(standard deviation(Metric(sim))). Large positive values (or negative) values indicate that the observed metric is significantly larger (or smaller) than predicted by the null model. If the distribution of errors is approximately normal, then non-significant values will fall roughly within +- two SES values. 19 | } 20 | 21 | -------------------------------------------------------------------------------- /man/summary.nichenullmod.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/niche_overlap_null.R 3 | \name{summary.nichenullmod} 4 | \alias{summary.nichenullmod} 5 | \title{Generic function for calculating null model summary statistics} 6 | \usage{ 7 | \method{summary}{nichenullmod}(object, ...) 8 | } 9 | \arguments{ 10 | \item{object}{the null model object to print a summary of.} 11 | 12 | \item{...}{Extra parameters for summary .} 13 | } 14 | \description{ 15 | Takes as input a list of Null.Model.Out, with Obs, Sim, Elapsed Time, and Time Stamp values 16 | } 17 | \details{ 18 | The summary output includes a timestamp and complete statistics on the simulated values of the metric, including the mean, variance, and one and two-tailed 95% confidence intervals. The lower and upper tails for the observed value are given, as is the standardized effect size (SES), which is calculated as the (Metric(obs) - average(Metric(sim)))/(standard deviation(Metric(sim))). Large positive values (or negative) values indicate that the observed metric is significantly larger (or smaller) than predicted by the null model. If the distribution of errors is approximately normal, then non-significant values will fall roughly within +- two SES values. 19 | } 20 | 21 | -------------------------------------------------------------------------------- /man/summary.nullmod.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/null_model_engine.R 3 | \name{summary.nullmod} 4 | \alias{summary.nullmod} 5 | \title{Generic function for calculating null model summary statistics} 6 | \usage{ 7 | \method{summary}{nullmod}(object, ...) 8 | } 9 | \arguments{ 10 | \item{object}{the null model object to print a summary of.} 11 | 12 | \item{...}{Extra parameters for summary.} 13 | } 14 | \description{ 15 | Takes as input a list of Null.Model.Out, with Obs, Sim, Elapsed Time, and Time Stamp values 16 | } 17 | \details{ 18 | The summary output includes a timestamp and complete statistics on the simulated values of the metric, including the mean, variance, and one and two-tailed 95% confidence intervals. The lower and upper tails for the observed value are given, as is the standardized effect size (SES), which is calculated as the (Metric(obs) - average(Metric(sim)))/(standard deviation(Metric(sim))). Large positive values (or negative) values indicate that the observed metric is significantly larger (or smaller) than predicted by the null model. If the distribution of errors is approximately normal, then non-significant values will fall roughly within +- two SES values. 19 | } 20 | 21 | -------------------------------------------------------------------------------- /man/summary.sizenullmod.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/sizeratio_null.R 3 | \name{summary.sizenullmod} 4 | \alias{summary.sizenullmod} 5 | \title{Generic function for calculating null model summary statistics} 6 | \usage{ 7 | \method{summary}{sizenullmod}(object, ...) 8 | } 9 | \arguments{ 10 | \item{object}{the null model object to print a summary of.} 11 | 12 | \item{...}{Extra parameters for summary.} 13 | } 14 | \description{ 15 | Takes as input a list of Null.Model.Out, with Obs, Sim, Elapsed Time, and Time Stamp values 16 | } 17 | \details{ 18 | The summary output includes a timestamp and complete statistics on the simulated values of the metric, including the mean, variance, and one and two-tailed 95% confidence intervals. The lower and upper tails for the observed value are given, as is the standardized effect size (SES), which is calculated as the (Metric(obs) - average(Metric(sim)))/(standard deviation(Metric(sim))). Large positive values (or negative) values indicate that the observed metric is significantly larger (or smaller) than predicted by the null model. If the distribution of errors is approximately normal, then non-significant values will fall roughly within +- two SES values. 19 | } 20 | 21 | -------------------------------------------------------------------------------- /man/v_ratio.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{v_ratio} 4 | \alias{v_ratio} 5 | \title{SchlutersVRatio Co-occurrence Metric} 6 | \usage{ 7 | v_ratio(m = matrix(rbinom(100, 1, 0.5), nrow = 10)) 8 | } 9 | \arguments{ 10 | \item{m}{a binary presence-absence matrix in which rows are species and columns 11 | are sites. The entries may be either abundances or occurrences of indivdual species.} 12 | } 13 | \value{ 14 | Returns the variance ratio of the matrix. 15 | } 16 | \description{ 17 | Takes a binary presence-absence matrix or a matrix of 18 | abundances and returns Schluter's (1984) variance ratio. 19 | } 20 | \details{ 21 | The variance ratio is the ratio of the variance in species number 22 | among sites to the sum of the variance of the species occurrences. If the average 23 | covariation in abundance (or occurrence) of each species pair is close to zero, 24 | the expected value for this ratio is approximately 1.0. V-ratios larger than 1.0 25 | imply positive average covariation in the abundance of species pairs, whereas V-ratios 26 | significantly smaller than 1.0 imply negative average covariation. 27 | } 28 | \note{ 29 | This index is determined exclusively by the row and column sums of the 30 | matrix, so it cannot be used with null model algorithms that hold both of those 31 | elements fixed. A simple randomization of the rows of the matrix (see sim2) 32 | assumes that all sites are equiprobable, so it may generate large values (= 33 | positive covariance) that reflect heterogeneity among sites. 34 | } 35 | \examples{ 36 | varCScore <- v_ratio(m=matrix(rbinom(100,1,0.5),nrow=10)) 37 | } 38 | \references{ 39 | Schluter, D. 1984. A variance test for detecting species associations, 40 | with some example applications. Ecology 65: 998-1005. 41 | 42 | McCulloch, C.E. 1985. Variance tests for species association. Ecology 66: 1676-1681. 43 | } 44 | 45 | -------------------------------------------------------------------------------- /man/var_diff.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{var_diff} 4 | \alias{var_diff} 5 | \title{VarDiff Size Overlap Ratio Metric} 6 | \usage{ 7 | var_diff(m = runif(20)) 8 | } 9 | \arguments{ 10 | \item{m}{a vector of non-negative trait measures, one for each species} 11 | } 12 | \value{ 13 | Returns the variance of the absolute difference between adjacent, ordered values. 14 | } 15 | \description{ 16 | Function to calculate the variance in size differences 17 | between adjacent, ordered species. If there is a tendency towards a 18 | constant absolute size difference between adjacent species, this 19 | variance will be relatively small. Alternatively, if some adjacent species 20 | are close in size, but others are very distant, this variance will be 21 | large. Small variances might be indicative of assemblages in which 22 | there is a competitively-based limit to similarity. 23 | } 24 | \examples{ 25 | SizeDifVar <- var_diff(rgamma(20,shape=3,scale=2)) 26 | } 27 | \references{ 28 | Poole, R.W. and B.J. Rathcke. 1979. Regularity, randomness, 29 | and aggregation in flowering phenologies. Science 203:470-471. 30 | 31 | Simberloff, D. and W.J. Boecklen. 1981. Santa Rosalia reconsidered: size 32 | ratios and competition. Evolution 35: 1206-1228. 33 | } 34 | 35 | -------------------------------------------------------------------------------- /man/var_ratio.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/metrics.R 3 | \name{var_ratio} 4 | \alias{var_ratio} 5 | \title{VarRatio Size Overlap Ratio Metric} 6 | \usage{ 7 | var_ratio(m = runif(20)) 8 | } 9 | \arguments{ 10 | \item{m}{a vector of non-negative trait measures, one for each species} 11 | } 12 | \value{ 13 | Returns the variance of the size ratios between adjacent, ordered values. 14 | } 15 | \description{ 16 | Function to calculate the variance in size ratios 17 | between adjacent, ordered species. If there is a tendency towards a 18 | constant size ratio between adjacent species, this 19 | variance will be relatively small. Alternatively, if some adjacent species 20 | are close in size, but others are very distant, this variance will be 21 | large. Small variances might be indicative of assemblages in which 22 | there is a competitively-based limit to similarity. 23 | } 24 | \examples{ 25 | SizeRatioVar <- var_ratio(rgamma(20,shape=3,scale=2)) 26 | } 27 | \references{ 28 | Poole, R.W. and B.J. Rathcke. 1979. Regularity, randomness, 29 | and aggregation in flowering phenologies. Science 203:470-471. 30 | 31 | Simberloff, D. and W.J. Boecklen. 1981. Santa Rosalia reconsidered: size 32 | ratios and competition. Evolution 35: 1206-1228. 33 | } 34 | 35 | -------------------------------------------------------------------------------- /man/vector_sample.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/algorithms.R 3 | \name{vector_sample} 4 | \alias{vector_sample} 5 | \title{Vector Sample Function} 6 | \usage{ 7 | vector_sample(speciesData, weights) 8 | } 9 | \arguments{ 10 | \item{speciesData}{binary vector representing species presences and 11 | absences.} 12 | 13 | \item{weights}{a vector of non-negative read numbers representing 14 | probabilistic weights for species occurrencs of the same length 15 | as speciesData.} 16 | } 17 | \value{ 18 | Returns a re-ordered binary vector in which the occurrences 19 | are placed in cells with probabilities proportional to values given 20 | in weights. 21 | } 22 | \description{ 23 | Takes an input binary vector and a weight vector. 24 | Reassigns 1s randomly in proportion to vector weights. 25 | } 26 | \details{ 27 | This function takes an input vector of binary presence-absence 28 | values and a vector of non-negative probability weights. Both vectors 29 | must be of identical length. 30 | } 31 | \note{ 32 | Several of the randomization algorithms use this function 33 | to assign species occurrences with probabilities that reflect 34 | species or site differences. It is an effective method for 35 | conditioning the marginal probabilities of a null matrix on 36 | independent measurements of site or species characteristics. 37 | } 38 | \examples{ 39 | myColonizer <- vector_sample(speciesData=rbinom(10,1,0.5),weights=runif(10)) 40 | } 41 | \references{ 42 | Gotelli, N.J., G.R. Graves, and C. Rahbek. 2010. Macroecological 43 | signals of species interactions in the Danish avifauna. Proceedings of the 44 | National Academy of Sciences, U.S.A. 107: 530-535. 45 | } 46 | \seealso{ 47 | \code{\link{sim10}} randomization algorithm. 48 | } 49 | 50 | -------------------------------------------------------------------------------- /tests/testthat.R: -------------------------------------------------------------------------------- 1 | library(testthat) 2 | test_check('EcoSimR') 3 | -------------------------------------------------------------------------------- /tests/testthat/test_cooccurrence.R: -------------------------------------------------------------------------------- 1 | library(EcoSimR) 2 | context("Co-occurrence null model tests") 3 | tmat <- testMatrix <- ranMatGen(aBetaCol=0.5,bBetaCol=0.5, aBetaRow=0.5,bBetaRow=0.5,numRows=30,numCols=30, 4 | mFill=0.25,abun=0,emptyRow=FALSE,emptyCol=FALSE)$m 5 | 6 | tmatW0 <- tmat 7 | tmatW0[10,] <- rep(0,dim(tmat)[2]) 8 | 9 | realData <- as.matrix(dataWiFinches[,2:20]) 10 | 11 | test_that("vector_sample algorithm works",{ 12 | expect_true(is.vector(vector_sample(speciesData=rbinom(10,1,0.5),weights=runif(10)))) 13 | }) 14 | 15 | test_that("sim1 algorithm works",{ 16 | expect_true(is.matrix(sim1(tmat))) 17 | expect_true(is.matrix(sim1(realData))) 18 | }) 19 | 20 | test_that("sim2 algorithm works",{ 21 | expect_true(is.matrix(sim2(tmat))) 22 | expect_true(is.matrix(sim2(realData))) 23 | ### Test that row sums are preserved 24 | expect_equal(apply(sim2(tmat),1,sum),apply(tmat,1,sum)) 25 | }) 26 | 27 | test_that("sim3 algorithm works",{ 28 | expect_true(is.matrix(sim3(tmat))) 29 | expect_true(is.matrix(sim3(realData))) 30 | ### Test that row sums are preserved 31 | expect_equal(apply(sim3(tmat),2,sum),apply(tmat,2,sum)) 32 | }) 33 | 34 | 35 | test_that("sim4 algorithm works",{ 36 | expect_true(is.matrix(sim4(tmat))) 37 | expect_true(is.matrix(sim4(realData))) 38 | ### Test that row sums are preserved 39 | expect_equal(apply(sim4(tmat),1,sum),apply(tmat,1,sum)) 40 | }) 41 | 42 | test_that("sim5 algorithm works",{ 43 | expect_true(is.matrix(sim5(tmat))) 44 | expect_true(is.matrix(sim5(realData))) 45 | ### Test that row sums are preserved 46 | expect_equal(apply(sim5(tmat),2,sum),apply(tmat,2,sum)) 47 | }) 48 | 49 | test_that("sim6 algorithm works",{ 50 | expect_true(is.matrix(sim6(tmat))) 51 | expect_true(is.matrix(sim6(realData))) 52 | }) 53 | 54 | test_that("sim7 algorithm works",{ 55 | expect_true(is.matrix(sim7(tmat))) 56 | expect_true(is.matrix(sim7(realData))) 57 | }) 58 | 59 | 60 | test_that("sim8 algorithm works",{ 61 | expect_true(is.matrix(sim8(tmat))) 62 | expect_true(is.matrix(sim8(realData))) 63 | }) 64 | 65 | test_that("sim10 algorithm works",{ 66 | mopts <- list() 67 | mopts[["speciesData"]] <- tmat 68 | mopts[["rowWeights"]] <- runif(dim(tmat)[1]) 69 | mopts[["colWeights"]] <- runif(dim(tmat)[2]) 70 | 71 | 72 | expect_true(is.matrix(do.call(sim10,mopts))) 73 | mopts[["speciesData"]] <- realData 74 | mopts[["rowWeights"]] <- runif(dim(realData)[1]) 75 | mopts[["colWeights"]] <- runif(dim(realData)[2]) 76 | 77 | expect_true(is.matrix(do.call(sim10,mopts))) 78 | expect_true(is.matrix(sim10(tmat))) 79 | }) 80 | 81 | test_that("species_combo metric works",{ 82 | expect_equal(species_combo(realData),10) 83 | expect_true(species_combo(tmat) > 0) 84 | }) 85 | 86 | 87 | test_that("checker metric works",{ 88 | expect_equal(checker(realData),91) 89 | expect_true(is.numeric(checker(tmat))) 90 | }) 91 | 92 | 93 | test_that("c_score metric works",{ 94 | expect_equal(round(c_score(realData)), 4) 95 | expect_true(is.numeric(c_score(tmat))) 96 | expect_true(is.numeric(c_score(tmatW0))) 97 | 98 | }) 99 | 100 | test_that("c_score_var metric works",{ 101 | expect_equal(round(c_score_var(realData)), 64) 102 | expect_true(is.numeric(c_score_var(tmat))) 103 | expect_true(is.numeric(c_score_var(tmatW0))) 104 | 105 | }) 106 | 107 | test_that("c_score_skew metric works",{ 108 | expect_equal(round(c_score_skew(realData)), 4) 109 | expect_true(is.numeric(c_score_skew(tmat))) 110 | expect_true(is.numeric(c_score_skew(tmatW0))) 111 | 112 | }) 113 | 114 | test_that("v_ratio metric works",{ 115 | expect_equal(round(v_ratio(realData)), 1) 116 | expect_true(is.numeric(v_ratio(tmat))) 117 | expect_true(is.numeric(v_ratio(tmatW0))) 118 | }) 119 | 120 | test_that("All combinations of co-occurrence models work",{ 121 | 122 | 123 | 124 | expect_is(cooc_null_model(dataWiFinches, algo="sim1",metric="species_combo",nRep=10),"coocnullmod") 125 | expect_is(cooc_null_model(dataWiFinches, algo="sim2",metric="species_combo",nRep=10),"coocnullmod") 126 | expect_is(cooc_null_model(dataWiFinches, algo="sim3",metric="species_combo",nRep=10),"coocnullmod") 127 | expect_is(cooc_null_model(dataWiFinches, algo="sim4",metric="species_combo",nRep=10),"coocnullmod") 128 | expect_is(cooc_null_model(dataWiFinches, algo="sim5",metric="species_combo",nRep=10),"coocnullmod") 129 | expect_is(cooc_null_model(dataWiFinches, algo="sim6",metric="species_combo",nRep=10),"coocnullmod") 130 | expect_is(cooc_null_model(dataWiFinches, algo="sim7",metric="species_combo",nRep=10),"coocnullmod") 131 | expect_is(cooc_null_model(dataWiFinches, algo="sim8",metric="species_combo",nRep=10),"coocnullmod") 132 | expect_is(cooc_null_model(dataWiFinches, algo="sim10",metric="species_combo",nRep=10,algoOpts=list(rowWeights=runif(dim(dataWiFinches)[1]) ,colWeights=runif(dim(dataWiFinches)[2]-1))),"coocnullmod") 133 | 134 | expect_is(cooc_null_model(dataWiFinches, algo="sim1",metric="checker",nRep=10),"coocnullmod") 135 | expect_is(cooc_null_model(dataWiFinches, algo="sim2",metric="checker",nRep=10),"coocnullmod") 136 | expect_is(cooc_null_model(dataWiFinches, algo="sim3",metric="checker",nRep=10),"coocnullmod") 137 | expect_is(cooc_null_model(dataWiFinches, algo="sim4",metric="checker",nRep=10),"coocnullmod") 138 | expect_is(cooc_null_model(dataWiFinches, algo="sim5",metric="checker",nRep=10),"coocnullmod") 139 | expect_is(cooc_null_model(dataWiFinches, algo="sim6",metric="checker",nRep=10),"coocnullmod") 140 | expect_is(cooc_null_model(dataWiFinches, algo="sim7",metric="checker",nRep=10),"coocnullmod") 141 | expect_is(cooc_null_model(dataWiFinches, algo="sim8",metric="checker",nRep=10),"coocnullmod") 142 | expect_is(cooc_null_model(dataWiFinches, algo="sim10",metric="checker",nRep=10,algoOpts=list(rowWeights=runif(dim(dataWiFinches)[1]) ,colWeights=runif(dim(dataWiFinches)[2]-1))),"coocnullmod") 143 | 144 | expect_is(cooc_null_model(dataWiFinches, algo="sim1",metric="c_score",nRep=10),"coocnullmod") 145 | expect_is(cooc_null_model(dataWiFinches, algo="sim2",metric="c_score",nRep=10),"coocnullmod") 146 | expect_is(cooc_null_model(dataWiFinches, algo="sim3",metric="c_score",nRep=10),"coocnullmod") 147 | expect_is(cooc_null_model(dataWiFinches, algo="sim4",metric="c_score",nRep=10),"coocnullmod") 148 | expect_is(cooc_null_model(dataWiFinches, algo="sim5",metric="c_score",nRep=10),"coocnullmod") 149 | expect_is(cooc_null_model(dataWiFinches, algo="sim6",metric="c_score",nRep=10),"coocnullmod") 150 | expect_is(cooc_null_model(dataWiFinches, algo="sim7",metric="c_score",nRep=10),"coocnullmod") 151 | expect_is(cooc_null_model(dataWiFinches, algo="sim8",metric="c_score",nRep=10),"coocnullmod") 152 | expect_is(cooc_null_model(dataWiFinches, algo="sim10",metric="c_score",nRep=10,algoOpts=list(rowWeights=runif(dim(dataWiFinches)[1]) ,colWeights=runif(dim(dataWiFinches)[2]-1))),"coocnullmod") 153 | 154 | expect_is(cooc_null_model(dataWiFinches, algo="sim1",metric="c_score_var",nRep=10),"coocnullmod") 155 | expect_is(cooc_null_model(dataWiFinches, algo="sim2",metric="c_score_var",nRep=10),"coocnullmod") 156 | expect_is(cooc_null_model(dataWiFinches, algo="sim3",metric="c_score_var",nRep=10),"coocnullmod") 157 | expect_is(cooc_null_model(dataWiFinches, algo="sim4",metric="c_score_var",nRep=10),"coocnullmod") 158 | expect_is(cooc_null_model(dataWiFinches, algo="sim5",metric="c_score_var",nRep=10),"coocnullmod") 159 | expect_is(cooc_null_model(dataWiFinches, algo="sim6",metric="c_score_var",nRep=10),"coocnullmod") 160 | expect_is(cooc_null_model(dataWiFinches, algo="sim7",metric="c_score_var",nRep=10),"coocnullmod") 161 | expect_is(cooc_null_model(dataWiFinches, algo="sim8",metric="c_score_var",nRep=10),"coocnullmod") 162 | expect_is(cooc_null_model(dataWiFinches, algo="sim10",metric="c_score_var",nRep=10,algoOpts=list(rowWeights=runif(dim(dataWiFinches)[1]) ,colWeights=runif(dim(dataWiFinches)[2]-1))),"coocnullmod") 163 | 164 | expect_is(cooc_null_model(dataWiFinches, algo="sim1",metric="c_score_skew",nRep=10),"coocnullmod") 165 | expect_is(cooc_null_model(dataWiFinches, algo="sim2",metric="c_score_skew",nRep=10),"coocnullmod") 166 | expect_is(cooc_null_model(dataWiFinches, algo="sim3",metric="c_score_skew",nRep=10),"coocnullmod") 167 | expect_is(cooc_null_model(dataWiFinches, algo="sim4",metric="c_score_skew",nRep=10),"coocnullmod") 168 | expect_is(cooc_null_model(dataWiFinches, algo="sim5",metric="c_score_skew",nRep=10),"coocnullmod") 169 | expect_is(cooc_null_model(dataWiFinches, algo="sim6",metric="c_score_skew",nRep=10),"coocnullmod") 170 | expect_is(cooc_null_model(dataWiFinches, algo="sim7",metric="c_score_skew",nRep=10),"coocnullmod") 171 | expect_is(cooc_null_model(dataWiFinches, algo="sim8",metric="c_score_skew",nRep=10),"coocnullmod") 172 | expect_is(cooc_null_model(dataWiFinches, algo="sim10",metric="c_score_skew",nRep=10,algoOpts=list(rowWeights=runif(dim(dataWiFinches)[1]) ,colWeights=runif(dim(dataWiFinches)[2]-1))),"coocnullmod") 173 | 174 | expect_is(cooc_null_model(dataWiFinches, algo="sim1",metric="v_ratio",nRep=10),"coocnullmod") 175 | expect_is(cooc_null_model(dataWiFinches, algo="sim2",metric="v_ratio",nRep=10),"coocnullmod") 176 | expect_is(cooc_null_model(dataWiFinches, algo="sim3",metric="v_ratio",nRep=10),"coocnullmod") 177 | expect_is(cooc_null_model(dataWiFinches, algo="sim4",metric="v_ratio",nRep=10),"coocnullmod") 178 | expect_is(cooc_null_model(dataWiFinches, algo="sim5",metric="v_ratio",nRep=10),"coocnullmod") 179 | expect_is(cooc_null_model(dataWiFinches, algo="sim6",metric="v_ratio",nRep=10),"coocnullmod") 180 | expect_is(cooc_null_model(dataWiFinches, algo="sim7",metric="v_ratio",nRep=10),"coocnullmod") 181 | expect_is(cooc_null_model(dataWiFinches, algo="sim8",metric="v_ratio",nRep=10),"coocnullmod") 182 | expect_is(cooc_null_model(dataWiFinches, algo="sim10",metric="v_ratio",nRep=10,algoOpts=list(rowWeights=runif(dim(dataWiFinches)[1]) ,colWeights=runif(dim(dataWiFinches)[2]-1))),"coocnullmod") 183 | 184 | smod <- cooc_null_model(dataWiFinches, algo="sim8",metric="v_ratio",nRep=10) 185 | 186 | 187 | expect_output(summary(smod),"Metric: v_ratio") 188 | expect_true(is.null(plot(smod,type="hist"))) 189 | expect_true(is.null(plot(smod,type="cooc"))) 190 | 191 | }) 192 | 193 | test_that("all text data frames are handled proprely",{ 194 | textMat <- cbind(letters[1:dim(tmat)[1]],tmat) 195 | expect_is(cooc_null_model(textMat, algo="sim8",metric="v_ratio",nRep=10),"coocnullmod") 196 | 197 | 198 | }) 199 | 200 | test_that("Reproduce model works",{ 201 | smod <- cooc_null_model(dataWiFinches, algo="sim8",metric="v_ratio",nRep=10,saveSeed = T) 202 | reproduce_model(smod) 203 | smod2 <- cooc_null_model(dataWiFinches, algo="sim8",metric="v_ratio",nRep=10) 204 | expect_equal(sum(smod2$Sim-smod$Sim),0) 205 | smod <- cooc_null_model(dataWiFinches, algo="sim8",metric="v_ratio",nRep=10) 206 | expect_error(reproduce_model(smod)) 207 | 208 | 209 | }) 210 | 211 | test_that("testing for sim9_single",{ 212 | expect_true(is.matrix(sim9_single())) 213 | expect_true(is.matrix(sim9_single(tmat))) 214 | expect_equal(sum(rowSums(tmat)-rowSums(sim9_single(tmat))),0) 215 | expect_equal(sum(colSums(tmat)-colSums(sim9_single(tmat))),0) 216 | 217 | }) 218 | 219 | test_that("testing for sim9",{ 220 | expect_is( cooc_null_model(dataWiFinches, algo="sim9",metric="species_combo",nReps=10,burn_in=10),"coocnullmod") 221 | expect_is( cooc_null_model(dataWiFinches, algo="sim9",metric="checker",nReps=10,burn_in=10),"coocnullmod") 222 | expect_is( cooc_null_model(dataWiFinches, algo="sim9",metric="c_score",nReps=10,burn_in=10),"coocnullmod") 223 | expect_is( cooc_null_model(dataWiFinches, algo="sim9",metric="c_score_var",nReps=10,burn_in=10),"coocnullmod") 224 | expect_is( cooc_null_model(dataWiFinches, algo="sim9",metric="c_score_skew",nReps=10,burn_in=10),"coocnullmod") 225 | expect_is( cooc_null_model(dataWiFinches, algo="sim9",metric="v_ratio",nReps=10,burn_in=10),"coocnullmod") 226 | 227 | smod <- cooc_null_model(dataWiFinches, algo="sim9",metric="v_ratio",nReps=10,burn_in=10) 228 | expect_output(summary(smod),"Algorithm: sim9") 229 | expect_true(is.null(plot(smod,type="hist"))) 230 | expect_true(is.null(plot(smod,type="cooc"))) 231 | expect_true(is.null(plot(smod,type="burn_in"))) 232 | 233 | 234 | }) 235 | 236 | -------------------------------------------------------------------------------- /tests/testthat/test_nichebreadth.R: -------------------------------------------------------------------------------- 1 | library(EcoSimR) 2 | context("Niche overlap null model tests") 3 | 4 | nicheTmat <- matrix(rnorm(100),ncol=10,nrow=10) 5 | 6 | nicheTmat[c(1,19,13,23,42,90)] <- 0 7 | uval <- length(unique(nicheTmat)) 8 | 9 | 10 | 11 | test_that("ra1 algorithm works:",{ 12 | expect_true(is.matrix(ra1())) 13 | expect_true(is.matrix(ra1(dataMacWarb[,2:5]))) 14 | 15 | } 16 | ) 17 | 18 | 19 | test_that("ra2 algorithm works:",{ 20 | expect_true(is.matrix(ra2())) 21 | expect_true(is.matrix(ra2(as.matrix(dataMacWarb[,2:5])))) 22 | expect_equal(length(which(ra2(nicheTmat)==0)),6) 23 | } 24 | ) 25 | 26 | test_that("ra3 algorithm works:",{ 27 | expect_true(is.matrix(ra3())) 28 | expect_true(is.matrix(ra3(dataMacWarb[,2:5]))) 29 | expect_equal(length(unique(ra3(nicheTmat))),uval) 30 | } 31 | ) 32 | 33 | 34 | test_that("ra4 algorithm works:",{ 35 | expect_true(is.matrix(ra4())) 36 | expect_true(is.matrix(ra4(dataMacWarb[,2:5]))) 37 | expect_equal(sum(apply(ra4(nicheTmat),2,function(x){sum(x==0)}) - apply(nicheTmat,2,function(x){sum(x==0)})), 0) 38 | expect_equal(sum(apply(ra4(nicheTmat),1,function(x){sum(x==0)}) - apply(nicheTmat,1,function(x){sum(x==0)})), 0) 39 | } 40 | ) 41 | 42 | test_that("pianka metric works:",{ 43 | expect_true(is.numeric(pianka(ra1()))) 44 | expect_true(is.numeric(pianka(ra4(dataMacWarb[,2:5])))) 45 | expect_true(pianka(ra4(dataMacWarb[,2:5])) > .5 ) 46 | 47 | }) 48 | 49 | test_that("czekanowski metric works:",{ 50 | expect_true(is.numeric(czekanowski(ra1()))) 51 | expect_true(is.numeric(czekanowski(ra4(dataMacWarb[,2:5])))) 52 | expect_true(czekanowski(ra4(dataMacWarb[,2:5])) > .5 ) 53 | 54 | }) 55 | 56 | test_that("pianka_var metric works:",{ 57 | expect_true(is.numeric(pianka_var(ra1()))) 58 | expect_true(is.numeric(pianka_var(ra4(dataMacWarb[,2:5])))) 59 | expect_true(pianka_var(ra4(dataMacWarb[,2:5])) < .5 ) 60 | 61 | }) 62 | 63 | 64 | test_that("czekanowski_var metric works:",{ 65 | expect_true(is.numeric(czekanowski_var(ra1()))) 66 | expect_true(is.numeric(czekanowski_var(ra4(dataMacWarb[,2:5])))) 67 | expect_true(czekanowski_var(ra4(dataMacWarb[,2:5])) < .5 ) 68 | 69 | }) 70 | 71 | test_that("pianka_skew metric works:",{ 72 | expect_true(is.numeric(pianka_skew(ra1()))) 73 | expect_true(is.numeric(pianka_skew(ra4(dataMacWarb[,2:5])))) 74 | 75 | }) 76 | 77 | 78 | test_that("czekanowski_skew metric works:",{ 79 | expect_true(is.numeric(czekanowski_skew(ra1()))) 80 | expect_true(is.numeric(czekanowski_skew(ra4(dataMacWarb[,2:5])))) 81 | }) 82 | 83 | 84 | test_that("niche_null_model works with all combinations of metrics and algorithms",{ 85 | ### Test that proper object is returned 86 | expect_is(niche_null_model(dataMacWarb,metric ="pianka" ,algo = "ra1",nRep=10),"nichenullmod") 87 | expect_is(niche_null_model(dataMacWarb,metric ="pianka_var" ,algo = "ra1",nRep=10),"nichenullmod") 88 | expect_is(niche_null_model(dataMacWarb,metric ="pianka_skew" ,algo = "ra1",nRep=10),"nichenullmod") 89 | expect_is(niche_null_model(dataMacWarb,metric ="czekanowski" ,algo = "ra1",nRep=10),"nichenullmod") 90 | expect_is(niche_null_model(dataMacWarb,metric ="czekanowski_var" ,algo = "ra1",nRep=10),"nichenullmod") 91 | expect_is(niche_null_model(dataMacWarb,metric ="czekanowski_skew" ,algo = "ra1",nRep=10),"nichenullmod") 92 | 93 | expect_is(niche_null_model(dataMacWarb,metric ="pianka" ,algo = "ra2",nRep=10),"nichenullmod") 94 | expect_is(niche_null_model(dataMacWarb,metric ="pianka_var" ,algo = "ra2",nRep=10),"nichenullmod") 95 | expect_is(niche_null_model(dataMacWarb,metric ="pianka_skew" ,algo = "ra2",nRep=10),"nichenullmod") 96 | expect_is(niche_null_model(dataMacWarb,metric ="czekanowski" ,algo = "ra2",nRep=10),"nichenullmod") 97 | expect_is(niche_null_model(dataMacWarb,metric ="czekanowski_var" ,algo = "ra2",nRep=10),"nichenullmod") 98 | expect_is(niche_null_model(dataMacWarb,metric ="czekanowski_skew" ,algo = "ra2",nRep=10),"nichenullmod") 99 | 100 | 101 | expect_is(niche_null_model(dataMacWarb,metric ="pianka" ,algo = "ra3",nRep=10),"nichenullmod") 102 | expect_is(niche_null_model(dataMacWarb,metric ="pianka_var" ,algo = "ra3",nRep=10),"nichenullmod") 103 | expect_is(niche_null_model(dataMacWarb,metric ="pianka_skew" ,algo = "ra3",nRep=10),"nichenullmod") 104 | expect_is(niche_null_model(dataMacWarb,metric ="czekanowski" ,algo = "ra3",nRep=10),"nichenullmod") 105 | expect_is(niche_null_model(dataMacWarb,metric ="czekanowski_var" ,algo = "ra3",nRep=10),"nichenullmod") 106 | expect_is(niche_null_model(dataMacWarb,metric ="czekanowski_skew" ,algo = "ra3",nRep=10),"nichenullmod") 107 | 108 | 109 | expect_is(niche_null_model(dataMacWarb,metric ="pianka" ,algo = "ra4",nRep=10),"nichenullmod") 110 | expect_is(niche_null_model(dataMacWarb,metric ="pianka_var" ,algo = "ra4",nRep=10),"nichenullmod") 111 | expect_is(niche_null_model(dataMacWarb,metric ="pianka_skew" ,algo = "ra4",nRep=10),"nichenullmod") 112 | expect_is(niche_null_model(dataMacWarb,metric ="czekanowski" ,algo = "ra4",nRep=10),"nichenullmod") 113 | expect_is(niche_null_model(dataMacWarb,metric ="czekanowski_var" ,algo = "ra4",nRep=10),"nichenullmod") 114 | expect_is(niche_null_model(dataMacWarb,metric ="czekanowski_skew" ,algo = "ra4",nRep=10),"nichenullmod") 115 | 116 | 117 | nmod <- niche_null_model(dataMacWarb,metric ="czekanowski" ,algo = "ra1",nRep=10) 118 | 119 | expect_output(summary(nmod),"Metric: czekanowski") 120 | expect_true(is.null(plot(nmod,type="hist"))) 121 | expect_true(is.list(plot(nmod,type="niche"))) 122 | }) 123 | 124 | 125 | 126 | test_that("all text data frames are handled proprely",{ 127 | textMat <- cbind(letters[1:dim(nicheTmat)[1]],nicheTmat) 128 | expect_is(niche_null_model(textMat,metric ="czekanowski_skew" ,algo = "ra4",nRep=10),"nichenullmod") 129 | 130 | }) 131 | 132 | 133 | 134 | 135 | 136 | -------------------------------------------------------------------------------- /tests/testthat/test_sizeratio.R: -------------------------------------------------------------------------------- 1 | library(EcoSimR) 2 | context("Size ratio null model tests") 3 | test_that("size_uniform algorithm works:",{ 4 | expect_true(is.vector(size_uniform())) 5 | expect_true(is.vector(size_uniform(dataRodents$Sonoran))) 6 | 7 | } 8 | ) 9 | 10 | test_that("size_uniform_user algorithm works:",{ 11 | expect_true(is.vector(size_uniform_user())) 12 | expect_true(is.vector(size_uniform_user(dataRodents$Sonoran))) 13 | expect_true(is.vector(do.call(size_uniform_user,list(speciesData = dataRodents$Sonoran,userLow=4,userHigh=20)))) 14 | expect_true(min(do.call(size_uniform_user,list(speciesData = dataRodents$Sonoran,userLow=4,userHigh=20))) > 4) 15 | expect_true(max(do.call(size_uniform_user,list(speciesData = dataRodents$Sonoran,userLow=4,userHigh=20))) < 20) 16 | } 17 | ) 18 | 19 | test_that("size_source_pool algorithm works:",{ 20 | expect_true(is.vector(size_source_pool())) 21 | expect_true(is.vector(size_source_pool(dataRodents$Sonoran))) 22 | expect_true(is.vector(do.call(size_source_pool,list(speciesData = dataRodents$Sonoran, 23 | sourcePool = runif(1000,min(dataRodents$Sonoran),max(dataRodents$Sonoran)), 24 | speciesProbs = rbeta(1000,1,1) )))) 25 | } 26 | ) 27 | 28 | test_that("size_size_gamma algorithm works:",{ 29 | expect_true(is.vector(size_gamma())) 30 | expect_true(is.vector(size_gamma(dataRodents$Sonoran))) 31 | } 32 | ) 33 | 34 | 35 | test_that("min_diff metric works",{ 36 | ### Test that proper object is returned 37 | expect_true(is.numeric(min_diff())) 38 | ### Test that minimum difference is accurate 39 | expect_equal(min_diff(c(1,1.2,-3,3)),.2) 40 | }) 41 | 42 | test_that("min_diff metric works",{ 43 | ### Test that proper object is returned 44 | expect_true(is.numeric(min_diff())) 45 | ### Test that minimum difference is accurate 46 | expect_equal(min_diff(c(1,1.2,-3,3)),.2) 47 | expect_equal(min_diff(c(1,1.2,1.1,-3,3)),.1) 48 | 49 | 50 | }) 51 | 52 | test_that("min_ratio metric works",{ 53 | ### Test that proper object is returned 54 | expect_true(is.numeric(min_ratio())) 55 | ### Test that minimum ratio is accurate 56 | expect_equal(min_ratio(c(1,2,3,4,5,6)),(6/5)) 57 | 58 | }) 59 | 60 | 61 | test_that("var_diff metric works",{ 62 | ### Test that proper object is returned 63 | expect_true(is.numeric(var_diff())) 64 | }) 65 | 66 | 67 | test_that("var_ratio metric works",{ 68 | ### Test that proper object is returned 69 | expect_true(is.numeric(var_ratio())) 70 | }) 71 | 72 | test_that("size_null_model works with all combinations of metrics and algorithms",{ 73 | ### Test that proper object is returned 74 | expect_is(size_null_model(dataRodents,metric ="min_diff" ,algo = "size_uniform",nRep=10),"sizenullmod") 75 | expect_is(size_null_model(dataRodents,metric ="min_ratio" ,algo = "size_uniform",nRep=10),"sizenullmod") 76 | expect_is(size_null_model(dataRodents,metric ="var_diff" ,algo = "size_uniform",nRep=10),"sizenullmod") 77 | expect_is(size_null_model(dataRodents,metric ="var_ratio" ,algo = "size_uniform",nRep=10),"sizenullmod") 78 | 79 | expect_is(size_null_model(dataRodents,metric ="min_diff" ,algo = "size_uniform_user",algoOpts = list(userLow = 3,userHigh=15),nRep=10),"sizenullmod") 80 | expect_is(size_null_model(dataRodents,metric ="min_ratio" ,algo = "size_uniform_user",algoOpts = list(userLow = 3,userHigh=15),nRep=10),"sizenullmod") 81 | expect_is(size_null_model(dataRodents,metric ="var_diff" ,algo = "size_uniform_user",algoOpts = list(userLow = 3,userHigh=15),nRep=10),"sizenullmod") 82 | expect_is(size_null_model(dataRodents,metric ="var_ratio" ,algo = "size_uniform_user",algoOpts = list(userLow = 3,userHigh=15),nRep=10),"sizenullmod") 83 | 84 | 85 | expect_is(size_null_model(dataRodents,metric ="min_diff" ,algo = "size_source_pool",algoOpts = list(sourcePool = runif(1000,min(dataRodents$Sonoran),max(dataRodents$Sonoran)), 86 | speciesProbs = rbeta(1000,1,1) ),nRep=10),"sizenullmod") 87 | expect_is(size_null_model(dataRodents,metric ="min_ratio" ,algo = "size_source_pool",algoOpts = list(sourcePool = runif(1000,min(dataRodents$Sonoran),max(dataRodents$Sonoran)), 88 | speciesProbs = rbeta(1000,1,1) ),nRep=10),"sizenullmod") 89 | expect_is(size_null_model(dataRodents,metric ="var_diff" ,algo = "size_source_pool",algoOpts = list(sourcePool = runif(1000,min(dataRodents$Sonoran),max(dataRodents$Sonoran)), 90 | speciesProbs = rbeta(1000,1,1) ),nRep=10),"sizenullmod") 91 | expect_is(size_null_model(dataRodents,metric ="var_ratio" ,algo = "size_source_pool",algoOpts = list(sourcePool = runif(1000,min(dataRodents$Sonoran),max(dataRodents$Sonoran)), 92 | speciesProbs = rbeta(1000,1,1) ),nRep=10),"sizenullmod") 93 | 94 | expect_is(size_null_model(dataRodents,metric ="min_diff" ,algo = "size_gamma",nRep=10),"sizenullmod") 95 | expect_is(size_null_model(dataRodents,metric ="min_ratio" ,algo = "size_gamma",nRep=10),"sizenullmod") 96 | expect_is(size_null_model(dataRodents,metric ="var_diff" ,algo = "size_gamma",nRep=10),"sizenullmod") 97 | expect_is(size_null_model(dataRodents,metric ="var_ratio" ,algo = "size_gamma",nRep=10),"sizenullmod") 98 | 99 | smod <- size_null_model(dataRodents,metric ="var_diff" ,algo = "size_gamma",nRep=100) 100 | 101 | expect_output(summary(smod),"Metric: var_diff") 102 | expect_true(is.null(plot(smod,type="hist"))) 103 | expect_true(is.list(plot(smod,type="size"))) 104 | 105 | 106 | }) 107 | 108 | test_that("all text data frames are handled proprely",{ 109 | expect_is(size_null_model(dataRodents,metric ="var_ratio" ,algo = "size_gamma",nRep=10),"sizenullmod") 110 | 111 | 112 | 113 | 114 | }) 115 | 116 | 117 | -------------------------------------------------------------------------------- /vignettes/SizeRatioVignette.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Size Ratios" 3 | author: "Nicholas J. Gotelli, Edmund M. Hart, and Aaron M. Ellison" 4 | date: "16 March 2015" 5 | output: rmarkdown::html_vignette 6 | vignette: > 7 | %\VignetteIndexEntry{Size Ratio null models} 8 | %\VignetteEngine{knitr::rmarkdown} 9 | \usepackage[utf8]{inputenc} 10 | --- 11 | 12 | --- 13 | ```{r, warning=FALSE, message=FALSE} 14 | library(EcoSimR) # load EcoSimR library 15 | set.seed(56) # for reproducible results 16 | ``` 17 | 18 | ## Theory 19 | In his seminal paper "Homage To Santa Rosalia or why are there so many kinds of animals?", Hutchinson (1959) noted that, if the species in an assemblage are ordered from smallest to largest, the average body size ratios of adjacent species varied between 1.1 and 1.4 for several bird and mammal assemblages. Hutchinson speculated that the mean ratio, roughly 1.3, could be "tentatively" interpreted as the amount of separation necessary for species to coexist at the same trophic level. This modest suggestion spawned a vast amount of research, as ecologists sought to confirm or refute this "1.3 rule" for different assemblages. 20 | 21 | For animal assemblages, constancy in the ratios of body sizes or feeding appendages might result either from character displacement or colonization extinction dynamics. For plants, similar effects of competition for pollinators might lead to a constant difference in flowering times, rather than a constant ratio. Even if differences or ratios were not unusually constant, there might still be some minimum spacing or ratio that was necessary to permit coexistence. Important null model tests by Poole and Rathcke (1979) for even spacing of plant flowering phenologies, and by Simberloff and Boecklen (1981) for constancy of animal body size ratios found little support for these generalities. 22 | 23 | This module of EcoSimR includes metrics and algorithms for constant size ratios or size differences, as well as for critical minimum size ratios or size differences. Although the module is described in terms of animal body size, any morphological trait could be analyzed for constancy in size ratios. Flowering or activity times can also be tested for evidence of regular or minimum spacing. These analyses do not take into account intraspecific variation, and instead summarize body size or other traits as a single number for each species. 24 | 25 | ## Data 26 | The data for a size ratio analysis consists of a vector of species body sizes. Each entry represents the average body size or trait value for a species in an assemblage. These values must be non-negative real or integer values. Negative numbers are `NA` values are not allowed. 27 | 28 | The sample data set for this analysis is `dataRodents`, the body size in grams of 6 coexisting rodent species in the Sonoran desert (Brown 1975). Brown and his colleagues have studied competitive interactions among desert rodents (and among rodents and ants) for many years at these sites (see Brown 1998 for a summary of this work). Experimental studies have established that, in some locations, rodents compete for seed resources (Brown et al. 1986). We can use EcoSimR to test for any non-randomness in the body size pattern of these species. 29 | 30 | ```{r, echo=FALSE, results='asis'} 31 | knitr::kable(dataRodents, caption='Average body sizes of Sonoran desert rodents. Data from Brown (1975)') 32 | ``` 33 | 34 | ## Metrics 35 | The Size Ratio module of EcoSimR offers four metrics for analysis. Prior to calculation of these metrics, the body sizes (or trait values) are ordered from smallest to largest. 36 | 37 | - `var_ratio` calculates the variance in the size ratios of consecutively ordered body sizes. Ratios are always calculated as (larger/next larger). so they must be $\ge 1$. If this variance is unusually small, there is evidence of constancy in size ratios for the assemblage. In the extreme case, if the size ratio between adjacent species is a constant, the variance in these ratios will be 0.0. 38 | 39 | - `var_diff` calculates the variance of the absolute size differences between adjacent species. A small variance indicates a regular spacing of observations. In the extreme case, if the spacing between adjacent species is a constant, the variance in these differences will be zero. Note that if `var_diff` is very small, `var_ratio` will not be, and vice-versa. This metric was introduced by Poole and Rathcke (1979) to test for regular spacing of flowering phenologies. 40 | 41 | - `min_ratio` calculates the minimum size ratio between adjacent pairs of species. If there are ties in the data, then `min_ratio` will equal 1.0. 42 | 43 | - `min_diff` calculates the absolute minimum size difference between adjacent pairs of species. If there are ties in the data, then `min_diff` will equal 0.0. 44 | 45 | ## Algorithms 46 | The Size Ratio module of EcoSimR offers four algorithms for randomizing a set of body size or trait values: 47 | 48 | - `size_uniform` simulates a uniform distribution of body sizes within the limits defined by the largest and smallest species in the assemblage. Thus, if there are *n* species in the assemblage, the two endpoints are fixed at the largest and smallest observed values, and the remaining *n* - 1 values are randomly assigned. Although the true distribution of body sizes may not be uniform, it may be approximately uniform within the observed limits of the data, particularly for small sample sizes. This is the default algorithm and corresponds to the tests used in Simberloff and Boecklen (1981). 49 | 50 | - `size_uniform_user` also simulates a uniform distribution of body sizes, but in this case, the user specifies the maximum and minimum body sizes possible. These limits must encompass the largest and smallest body sizes in the data set. Because the extreme values in the data are not used to set the limits of the distribution, all *n* of the species in each null assemblage are randomly assigned. The more extreme the endpoints, the more the observed distribution will show significant aggregation or clumping. The same data set might exhibit a pattern of randomness or segregation when tested with the `size_uniform` distribution. For this reason, the `size_uniform_user` is not the preferred algorithm because the degree of clumping will depend entirely on how widely spaced the boundaries are. 51 | 52 | - `size_gamma` is a more realistic way to simulate a distribution of body sizes that is not a simple uniform bounded by the data. The gamma distribution is appropriate for positive real values that may have a long right hand tail (such as the distribution of animal body sizes). Depending on the two parameters of the distribution, the gamma can resemble the profile of a normal, exponential or log-normal distribution (see also Tonkyn and Cole 1986). EcoSimR uses the `fitdr()` function in the MASS library to first obtain maximum likelihood estimates for the shape and scale paramters of the gamma distribution fitted to the observed data. Those parameters are then used to simulate a sample of *n* species for each null assemblage. Note that the null assemblage may include some species that are larger or smaller than any of the empirical observations. For small assemblages, the `size_gamma` algorithm may not give results that differ from the default `size_uniform`. However, for species-rich assemblages, it may be be a more realistic function to use. 53 | 54 | - `size_source_pool` offers a realistic alternative to the parametric distributions of body size available from the `size_uniform`, `size_uniform_user` and `size_gamma` algorithms. For the `size_source_pool` algorithm, the user provides an explicit source pool: a vector of the body sizes of all species in the source pool (=sourcePool). We assume that the species represented in the actual assemblage (=speciesData) are a proper subset of the species in this source pool (Graves and Gotelli 1983). The user also can provide a vector of relative colonization weights (positive real numbers). These weights (= speciesProbs) determine the probability that each species is drawn without replacement every time a null assemblage is created. If these weights are not provided, the default weight of 1 for every source pool species means they are all drawn equiprobably. 55 | 56 | ## Graphics 57 | The size-ratio module offers two graphic outputs. `plot(myModel, type="hist")` generates a standard histogram of simulated metric values (blue bars) based on the selected algorithm and metric. The vertical red line indicates the observed metric for the original data, the pair of vertical long-dash lines indicate the 95% one-tailed cutpoints, and the short-dash lines indicate the 95% two-tailed cutpoints. The latter would constitute a proper 95% confidence interval for the null distribution. Note that these intervals are not based on a normal or other parametric distribution. Instead, they are always estimated directly from the histogram, which means they could be asymmetric, and will be sensitive to the number of replicates used. 58 | ```{r, echo=FALSE, fig.height=4,fig.width=4,fig.align='center'} 59 | myModel <- cooc_null_model(dataWiFinches,suppressProg=TRUE) 60 | plot(myModel,type="hist") 61 | 62 | ``` 63 | 64 | 65 | The second graphic, `plot(myModel,type="size")`, illustrates graphically the body sizes of one simulated assemblage (blue points) and the observed body sizes (red points). These same data are portrayed as histograms (red and blue) of the ordered size differences between adjacent species pairs. A careful comparison of the observed and simulated data should confirm the behavior of the chosen randomization algorithm. 66 | 67 | ```{r, fig.height=8,fig.width=4,fig.align='center'} 68 | myModel <- size_null_model(dataRodents,suppressProg=TRUE) 69 | plot(myModel,type="size") 70 | ``` 71 | 72 | 73 | 74 | ## Defaults 75 | 76 | ```{r, eval=FALSE} 77 | 78 | speciesData # user must supply a data frame; speciesData=dataWiFinches for default run 79 | algo = "size_uniform" # randomize interior species with a uniform distribution 80 | metric = "var_ratio" # variance of size ratios of adjacent species 81 | nReps = 1000 # number of null assemblage created 82 | rowNames=TRUE # reads speciesData as a data frame wtih row labels in the first column 83 | saveSeed=FALSE # if TRUE, saves random number seed 84 | burn_in=500 # number of burn-in iterations for sim9 85 | algoOpts=list() # list of other specific options for the algorithm (used for size_source_pool) 86 | metricOpts=list() # list of other specific options for the metric 87 | suppressProg= FALSE # suppress printing of progress bar (for creating markdown files) 88 | ``` 89 | 90 | ## Examples 91 | ```{r, fig.height=4,fig.width=4,fig.align='center'} 92 | # run default settings and show all output 93 | myModel <- size_null_model(speciesData=dataRodents,suppressProg=TRUE) 94 | summary(myModel) 95 | plot(myModel,type = "hist") 96 | ``` 97 | ```{r,fig.height=8,fig.width=4,fig.align='center'} 98 | plot(myModel,type="size") # throws error in vignette: figure margins too large 99 | ``` 100 | 101 | ```{r, fig.height=4,fig.width=4,fig.align='center'} 102 | # test for minimum size differences with a source pool model 103 | 104 | # create a source pool of the rodent body sizes plus 20 other species 105 | mySource <-c(dataRodents$Sonoran,as.double(sample(150,20))) 106 | 107 | # create an arbitrary set of probabilty weights 108 | myProbs <- runif(26) 109 | 110 | # run the model 111 | myModel <- size_null_model(speciesData=dataRodents,suppressProg=TRUE, 112 | metric="min_diff",algo="size_source_pool", 113 | algoOpts=list(sourcePool=mySource,speciesProbs=myProbs)) 114 | 115 | # show the results 116 | summary(myModel) 117 | plot(myModel,type="hist") 118 | ``` 119 | 120 | ```{r, fig.height=8,fig.width=4,fig.align='center'} 121 | plot(myModel,type="size") 122 | ``` 123 | 124 | 125 | ## Caveats 126 | These models carry the usual restrictions on the analysis of body size patterns as they relate to competition and resource use: 1) body size or morphology are related to resource use; 2) the underlying resource spectrum is symmetric; 3) competition occurs primarily among adult organisms; 4) sexual size dimorphism and intraspecific variation in body size are ignored; 5) abundances of all species are approximately equal (Gotelli and Graves 1996). These models also treat each species as an independent data point and do not explicitly incorporate effects of phylogenetic inertia (Losos 1990). 127 | 128 | 129 | ## Literature 130 | 131 | Brown, J.H. 1975. Geographical ecology of desert rodents. p. 314-341 in: Ecology and Evolution of Communities. M.L. Cody and J.M. Diamond (eds.). Harvard University Press, Cambridge. 132 | 133 | Brown, J.H. 1998. The desert granivory experiments at Portal. Pages 71-95 in W.J. Resetarits, Jr. and J. Bernardo, eds. Experimental ecology: issues and perspectives. Oxford University Press, New York. 134 | 135 | Brown, J.H., D.W. Davidson, J.C. Munger, and R.S. Inouye. 1986. Experimental community ecology: the desert granivore system. Pages 41-61 in J. Diamond and T. J. Case, eds. Community ecology. Harper and Row, New York. 136 | 137 | Gotelli, N.J. and G.R. Graves. 1996. Null models in ecology. Smithsonian Institution Press, Washington DC. 138 | 139 | Graves, G.R. and N.J. Gotelli. 1983. Neotropical land-bridge avifaunas: new approaches to null hypotheses in biogeography. Oikos 41: 322-333. 140 | 141 | Hutchinson, G.E. 1959. Homage to Santa Rosalia or why are there so many kinds of animals? The American Naturalist 93: 145-159. 142 | 143 | Losos, J.B. 1990. A phylogenetic analysis of character displacement in Caribbean Anolis lizards. Evolution 44: 558-569. 144 | 145 | Poole R.W. and B.J. Rathcke. 1979. Regularity, randomness, and aggregation in flowering phenologies. Science 203: 470-471. 146 | 147 | Simberloff, D., and W. Boecklen. 1981. Santa Rosalia reconsidered: size ratios and competition. Evolution 35: 1206-1228. 148 | 149 | Tonkyn, D.W., and B.J. Cole. 1986. The statistical analysis of size ratios. The American Naturalist 128: 66-81. 150 | 151 | 152 | 153 | 154 | 155 | -------------------------------------------------------------------------------- /vignettes/nicheOverlapVignette.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Niche Overlap" 3 | author: "Nicholas J. Gotelli, Edmund M. Hart, Aaron M. Ellison " 4 | date: "13 March 2015" 5 | output: 6 | rmarkdown::html_vignette: 7 | toc: true 8 | fig_caption: yes 9 | vignette: > 10 | %\VignetteIndexEntry{Niche Overlap} 11 | %\VignetteEngine{knitr::rmarkdown} 12 | \usepackage[utf8]{inputenc} 13 | --- 14 | 15 | ## Theory 16 | 17 | Based in part on Gause's (1934) classic laboratory experiments, the competitive exclusion principle (Hardin 1960) is that coexisting species must differ in some aspect of their resource utilization. The idea was expanded into mathematical theories of limiting similarity (MacArthur and Levins 1967) and more recent treatments of the ecological niche (Chase and Leibold 2003). Ecologists have spent a lot of time measuring niche axes of potential resource competition, especially those related to the utilization of food, space, or time (Schoener 1974). The ?ghost of competition past? predicts that species currently coexisting should exhibit relatively low overlap in resource utilization (Connell 1980). Alternatively, if competition for limited resources is current, there should be high overlap in the niches of two species. 18 | 19 | Whether niche overlap is high or low has to first be measured relative to some null expectation. This module of `EcoSimR` tests for overlap in resource use among a set of coexisting species using a set of unordered, discrete resource categories. The analysis reveals whether the average niche overlap, calculated among all unique pairs of species, is more or less than would be expected if species used resource categories independently of one another. If the resources are measured on an ordered scale (such as prey size) or even a circular scale (such as time of day), then other kinds of null models are more appropriate (Castro-Arellano *et al*. 2010). Different algorithms are also needed if the utilization data are collected on a continuous scale (prey body size measured in g) versus a set of discrete categories (prey classified as invertebrates, small fish, or large fish). 20 | 21 | ## Data 22 | 23 | The data for a niche overlap analysis consists of a data frame in which each row is a species and each column is a discrete, unordered resource category (such as host plant species, diet categories, or microhabitats). The first column of the data frame optionally contains the species names. Each entry is the utilization (measured in appropriate units) of a particular resource category by a particular species. Entries must be non-negative real numbers. Zero values are allowed (some species may not use certain resource categories), but missing `NA` values are not allowed. All entries must be in the same units, but they do not have to be proportions or percentages. All of the niche overlap metrics first scale the data to proportions by dividing each entry by its row sum. 24 | 25 | The supplied data set `macwarb` for niche overlap analysis is taken from Table 2 of MacArthur's (1958) classic study on niche overlap of coexisting warblers. Each row represents one of 5 species of warbler that coexist in northern New England. Each column represents one of 16 subregions of an idealized coniferous tree. The entries are the percentage of time that each species was observed foraging in a different subregion of a (hypothetical) tree. MacArthur (1958) proposed that the species specialized on different subregions, and that this specialization was the basis for resource partitioning and coexistence. As we will see, the null model analysis provides a different perspective on this classic data set. 26 | 27 | ```{r,echo=FALSE,warning=FALSE,message=FALSE} 28 | library(EcoSimR) 29 | ``` 30 | ```{r, echo=FALSE, results='asis'} 31 | knitr::kable(dataMacWarb,caption="MacArthur's (1958) warbler data.") 32 | ``` 33 | 34 | ## Metrics 35 | 36 | The basic metrics for niche overlap are either the `pianka` or the `czekanowski` index. The `pianka` index is similar to the competition coefficient $\alpha$ in the Lotka-Volterra equations, and the `czekanowski` index is the area of intersection of two resource utilization histograms. These indices are calculated for an individual species pair, and are then averaged over all possible pairs of species in the assemblage. Both indices range from 0.0 (no overlap) to 1.0 (complete overlap). They are highly correlated with one another, and it makes little difference which one you use. 37 | 38 | The basic `pianka` and `czekanowski` indices give an index that is the mean overlap of all possible species pairs. You can also analyze the variance of pairwise overlap with `pianka_var` and `czekanowski_var`, and the skewness of pairwise overlap with `pianka_skew` and `czekanowski_skew`. A large value of the variance indicates that some species pairs have very high overlap and others have very overlap, relative to the null model. A large positive value of skewness indicates asymmetry with some strong high-overlap species pairs in the data matrix. A large negative value of skewness indicates asymmetry with some strong low-overlap species pairs in the matrix. As with all higher moments of a distribution, the variance and skewness can be very sensitive to outliers in the data, although the randomization test controls for this to some extent. The variance and skew functions have not been well-tested, but they may provide some additional insight into the niche overlap patterns. 39 | 40 | ## Algorithms 41 | 42 | Following the terminology of Lawlor (1980a) and the benchmark testing of Winemiller and Pianka (1990), EcoSimR provides four randomization algorithm. We recommend the default `ra3` or the slightly more conservative `ra4`. 43 | 44 | In brief, `ra3` reshuffles the row values, and `ra4` reshuffles the non-zero row values. Both of these algorithms retain the observed ?niche breadth? of each species- that is the relative degree of specialization, but they randomly alter which particular resource categories are used. 45 | 46 | `ra2` preserves the non-zero elements, but replaces the non-zero elements by a (0,1) random uniform value. `ra1` replaces all matrix entries by a random (0,1) uniform value, so the null hypothesis is that each species is an isotropic super-generalist. 47 | 48 | `ra1` and `ra2` are too liberal and do not give good results with artificial test matrices (Winemiller and Pianka 1990). For the `dataMacWarb`, try running these variations. Compared to `ra1`, the observed (Pianka) niche overlap is significantly greater than expected. Compared to `ra2`, the observed (Pianka) niche overlap is not different from random, and compared to `ra3` and `ra4`, the observed (Pianka) niche overlap is significantly greater than expected. Run these options yourself in EcoSimR to confirm these patterns. 49 | 50 | The statistical properties of `ra3` and `ra4` are good, although it is an open question whether resource categories that were never utilized by a species might have been utilized in a null assemblage. All four of the algorithms assume that all resource categories are equally abundant, which is often not the case. 51 | 52 | If independent data on resource abundance are available, the observed utilization can be divided by resource abundance to create an "electivity" index (Lawlor 1980b). This index effectively provides more weight for resource categories that are rare. Such a weighting is useful because we expect high overlap in abundant resource categories. However, the weightings may be sensitive to sampling error for very scarce resource states. 53 | 54 | Although it might seem reasonable to do so, you should not sum the resource utilization across species in order to estimate resource abundance. This estimate is not independent of observed utilization and can lead to Type I errors (incorrect rejection of a true null hypothesis). 55 | 56 | Some people are disturbed and suspicious of the fact that the null model results may depend on which algorithm is used and how the data are processed. But this is exactly as it should be: the results depend on the assumptions of the model. In the more familiar world of a simple ANOVA, the results will depend on whether the factors are treated as fixed or random and whether the data are transformed or not. And of course the results will depend on the sample size, the spatial scale of the study, and whether the data were collected as random, haphazard, systematic, or representative samples. Although there is often a preferred set of options for a null model analysis (which we have used in our defaults), we think it is always worthwhile to explore different variations of the model so that you can understand the result. See Gotelli and Ulrich (2012) for a discussion of other general issues in null model analysis. 57 | 58 | ## Graphics 59 | 60 | The niche overlap module offers two graphic outputs. `plot(type="hist") generates a standard histogram of simulated metric values (blue bars) based on the selected algorithm and metric. The vertical red line indicates the observed metric for the original data, the pair of vertical long-dash lines indicate the 95% one-tailed cutpoints, and the short-dash lines indicate the 95% two-tailed cutpoints. The latter would constitute a proper 95% confidence interval for the null distribution. Note that these intervals are not based on a normal or other parametric distribution. Instead, they are always estimated directly from the histogram, which means they could be asymmetric, and will be sensitive to the number of replicates used. 61 | 62 | ```{r, fig.show='hold', fig.align='center',fig.height=4,fig.width=4,echo=FALSE} 63 | set.seed(56) # for repeatable results 64 | myModel <- niche_null_model(dataMacWarb,suppressProg=TRUE) # default model settings 65 | plot(myModel,type="hist") 66 | ``` 67 | 68 | `plot(type="niche")` generates a rendering of the species $\times$ utilization matrix for the original data matrix (red) and one simulated data matrix (blue). The area of each circle depicted is proportional to the utilization of a resource category by a species. If no circle is shown, the utilization was 0.0. 69 | 70 | ```{r,fig.show='hold',fig.height=6,fig.width = 4,fig.align='center'} 71 | plot(myModel,type="niche") 72 | ``` 73 | 74 | 75 | 76 | ```{r, fig.align='center',echo=FALSE, eval=FALSE} 77 | set.seed(56) # for repeatable results 78 | myModel <- niche_null_model(dataMacWarb,suppressProg=TRUE) # default model settings 79 | #plot(myModel,type="hist") #<- throws error, figure margins too large 80 | 81 | 82 | 83 | ``` 84 | 85 | ## Defaults 86 | 87 | ```{r, eval=FALSE} 88 | 89 | speciesData # user must supply a data frame; speciesData=dataMacWarb for default run 90 | algo = "ra3" # reshuffle elements within each row of the matrix 91 | metric = "pianka" # pianka niche overlap index 92 | nReps = 1000 # number of null assemblage created 93 | rowNames=TRUE # reads speciesData as a data frame wtih row labels in the first column 94 | saveSeed=FALSE # if TRUE, saves random number seed 95 | algoOpts=list() # list of other specific options for the algorithm 96 | metricOpts=list() # list of other specific options for the metric 97 | suppressProg= FALSE # suppress printing of progress bar (for creating markdown files) 98 | ``` 99 | 100 | ## Examples 101 | 102 | ```{r, eval=FALSE} 103 | str(dataMacWarb) # structure of MacArthur's warbler data set 104 | summary(myModel) # output summary of null model analysis 105 | 106 | #create a random data set with uniform (0,1) values 107 | myRandomData <- matrix(runif(300), nrow=30) 108 | 109 | # run null model with czekanowski index and ra1, 5000 replications 110 | myRandomModel <- niche_null_model(speciesData=myRandomData, rowNames=FALSE, 111 | algo="ra1", metric="czekanowski", 112 | suppressProg=TRUE,nReps=5000) 113 | 114 | # print summary of model and plot histogram 115 | summary(myRandomModel) 116 | plot(myRandomModel,type="hist") 117 | 118 | ``` 119 | 120 | ## Caveats 121 | 122 | This null model is appropriate only for unordered niche categories, such as host plant species or dietary type. Different kinds of null models are appropriate for continuous data (such as prey body size) or circular data (such as temporal niches measured over diurnal or annual time scales). The niche overlap model used here also assumes all resource categories are equally available to all species. However, `ra2` and `ra4` fix the zero states, which means that resource categories that were never used by a species are assumed to be unavailable to that species even in the absence of competition. None of the algorithm explicitly account for sampling variation in the number of observations per category. However, `ra3` and `ra4` do account somewhat for sampling variation because the percent utilization values are themselves randomized among resource categories. 123 | 124 | ## Literature 125 | 126 | Castro-Arellano, I., T.E. Lacher, Jr., M.R. Willig, and T.F. Rangel. 2010. Assessment of assemblage-wide temporal niche segregation using null models. Methods in Ecology & Evolution 1: 311-318. 127 | 128 | Chase, J.M. and M.A. Leibold. 2003. Ecological Niches: Linking Classical And Contemporary Approaches. University of Chicago Press, Chicago. 129 | 130 | Connell, J.H. 1980. Diversity and the coevolution of competitors, or the ghost of competition past. Oikos 35: 131-138. 131 | 132 | Gause, G.F. 1934. The Struggle For Existence. Williams & Wilkins, Baltimore. 133 | 134 | Hardin, G. 1960. The competitive exclusion principle. Science 131: 1292-1297. 135 | 136 | Gotelli, N.J. and W. Ulrich. 2012. Statistical challenges in null model analysis. Oikos 121: 171-180. 137 | 138 | Lawlor, L.R. 1980a. Structure and stability in natural and randomly constructed model ecosystems. American Naturalist 116: 394-408. 139 | 140 | Lawlor, L.R. 1980b. Overlap, similarity, and competition coefficients. Ecology 61: 245-251. 141 | 142 | MacArthur, R.H. 1958. Population ecology of some warblers of northeastern coniferous forests. Ecology 39: 599-699. 143 | 144 | MacArthur, R.H. And R. Levins. 1967. The limiting similarity, convergence, and divergence of coexisting species. American Naturalist 101: 377-385. 145 | 146 | Schoener, T.S. 1974. Resource partitioning in ecological communities. Science 185: 27-39. 147 | 148 | Winemiller, K.O. and E.R. Pianka. 1990. Organization in natural assemblages of desert lizards and tropical fishes. Ecological Monographs 60: 27-55. -------------------------------------------------------------------------------- /vignettes/nullModelPlug-Ins.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Null Model Plug-Ins" 3 | author: "Nicholas J. Gotelli, Edmund M. Hart, Aaron M. Ellison" 4 | date: "`r Sys.Date()`" 5 | output: 6 | rmarkdown::html_vignette: 7 | toc: true 8 | 9 | vignette: > 10 | %\VignetteIndexEntry{Null Model Plug-Ins} 11 | %\VignetteEngine{knitr::rmarkdown} 12 | %\usepackage[utf8]{inputenc} 13 | --- 14 | 15 | ## Introduction 16 | 17 | EcoSimR provides a variety of options to fit niche-overlap, size ratio and co-occurrence null models with algorithms and metrics out of the box. Each of these are easily callable with `niche_null_model()`,`size_null_model()`, or `cooc_null_model()`. These functions are actually just wrappers for a function called `null_model_engine()`. The wrappers are conveniences that control inputs, and provide easy summary and plotting functions. However you can add your own algorithm and metrics. These can be completely novel or can be used with an existing null model. The first part is defining a metric or algorithm function that is compatible with the null model engine. This is because each user defined function requires a standard set of inputs to work with the null model engine. 18 | 19 | ## User Defined Function Overview 20 | 21 | _**Algorithms**_ 22 | 23 | Algorithms in the context of the null model engine are any function that will randomize an input data frame and return that randomization in the same form of the input. The classic example is of a co-occurrence null model. The input is a data frame of 1's and 0's that reperesent a species x site co-occurrence matrix where a 1 or 0 represents incidence of Species 1 at Site 1 (and so forth). A suitable randomization algorithm will accept this input and return a randomized matrix of the same size. All user defined algorithm require that the first parameter be called `speciesData` and is the species data to randomize e.g.: 24 | 25 | ```{r,eval=FALSE} 26 | foo <- function(speciesData,...){ 27 | ## Code to randomize here! 28 | } 29 | ``` 30 | 31 | A simple example might look like this (this is actually `sim1()` ) 32 | 33 | ```{r,eval=FALSE} 34 | myAlgo <- function(speciesData) { 35 | return(matrix(sample(speciesData), ncol=ncol(speciesData))) 36 | } 37 | ``` 38 | 39 | Following the required `speciesData` parameter, you can include an arbitrary number of parameters. Here's an example (actually `sim10()` ) 40 | 41 | ```{r, eval = FALSE} 42 | myAlgo2 <- function(speciesData,rowWeights,colWeights) { 43 | matrixWeights <- outer(rowWeights,colWeights) 44 | return(matrix(vector_sample(speciesData, weights =matrixWeights),ncol=ncol(speciesData))) 45 | } 46 | ``` 47 | 48 | _**Metrics**_ 49 | 50 | A user defined metric function will take data frame and calculate a scalar value. The null model distribution is the distribution of these values. Similar to algorithms, metrics require that the first parameter be called `m`. Here's a simple example (`species_combo()` in the package). 51 | 52 | ```{r,eval=FALSE} 53 | bar <- function(m){ 54 | return(ncol(unique(m,MARGIN=2))) 55 | } 56 | ``` 57 | 58 | Also an arbirtary number of parameters can be added with any names you choose. 59 | 60 | ```{r, eval=FALSE} 61 | bar <- function(m, trim = FALSE){ 62 | if(trim){ 63 | m <- m[which(rowSums(m)>0),] 64 | } 65 | return(ncol(unique(m,MARGIN=2))) 66 | } 67 | ``` 68 | 69 | Now that user defined functions have been written they can easily be plugged into the null model engine. 70 | 71 | ## Adding to existing null models 72 | 73 | One use case for creating your own algorithms and metrics is because you want to plug into the existing null model frame works in the package. Let's use co-occurrence models as an example. The `cooc_null_model()` function provides an easy interface with existing models, but power users may want to build upon the provided metrics and algorithms. First create a user defined algorithm. 74 | 75 | ```{r} 76 | myAlgo <- function(speciesData) { 77 | matrixWeights <- outer(rowSums(speciesData),rep(1,ncol(speciesData))) 78 | return(matrix(vector_sample(speciesData, weights=matrixWeights),ncol=ncol(speciesData))) 79 | } 80 | ``` 81 | 82 | Now choose an existing metric you want to use, for this example let's choose the `checker` metric. Because we want to have our results be compatible with an existing co-occurrence model, we need to specify the type of model we're running. The options are 83 | 84 | * `cooc` for co-occurrence models 85 | * `niche` for niche overlap models 86 | * `size` for size ratio models 87 | 88 | 89 | ```{r, message=FALSE,warning=FALSE,echo=FALSE} 90 | library(EcoSimR) 91 | ## Simulate data 92 | coocSimData <- ranMatGen(aBetaCol=0.5,bBetaCol=0.5, 93 | aBetaRow=0.5,bBetaRow=0.5, numRows=30,numCols=30, mFill=0.25,abun=0,emptyRow=FALSE, emptyCol=FALSE)$m 94 | 95 | coocOut <- null_model_engine(speciesData = coocSimData, algo = "myAlgo", metric = "checker",type="cooc",suppressProg = TRUE) 96 | 97 | ``` 98 | 99 | ```{r,eval=FALSE} 100 | ## Simulate data 101 | coocSimData <- ranMatGen(aBetaCol=0.5,bBetaCol=0.5, aBetaRow=0.5,bBetaRow=0.5, numRows=30,numCols=30, 102 | mFill=0.25,abun=0,emptyRow=FALSE, emptyCol=FALSE)$m 103 | 104 | coocOut <- null_model_engine(speciesData = coocSimData,nReps=1000, 105 | algo = "myAlgo", metric = "checker",type="cooc") 106 | 107 | ``` 108 | 109 | This will create a co-occurrence null model with your own alogrithm, and use the `checker` metric. The advantage of this is that you can now make co-occurrence plots and compare to existing null models. 110 | 111 | ```{r, fig.height=4,fig.width=4,fig.align='center'} 112 | ## Histogram plots 113 | plot(coocOut,type='hist') 114 | ``` 115 | ```{r,fig.height = 4,fig.width=6,fig.align='center'} 116 | ## Matrix examples 117 | plot(coocOut, type='cooc') 118 | 119 | ## Summary function 120 | summary(coocOut) 121 | 122 | ``` 123 | 124 | ## Creating novel null models 125 | 126 | You can create novel null models in a similar manner. Instead of just adding your own new algorithm and using an existing metric, you just create a new algorithm and a metric. If you do this, there's no need to specify the type. However if your new alogrithm and metric combination work on the same data as a co-occurrence model, you could specify the type as `cooc`. Specifying the type simply allows you to make type specific plots. 127 | 128 | First we'll create new algorithms and new metrics. We'll also create an algorithm that has extra parameters so you can see how easy it is to add custom parameters. 129 | 130 | 131 | ```{r My algo and metric} 132 | 133 | myAlgo <- function(speciesData,rowWeights,colWeights) { 134 | matrixWeights <- outer(rowWeights,colWeights) 135 | return(matrix(vector_sample(speciesData, weights =matrixWeights),ncol=ncol(speciesData))) 136 | } 137 | 138 | ## The C-Score 139 | myMetric <- function(m) 140 | { 141 | m <- m[which(rowSums(m)>0),] # make calculation on submatrix with no missing species 142 | shared = tcrossprod(m) 143 | sums = rowSums(m) 144 | 145 | upper = upper.tri(shared) 146 | 147 | scores = (sums[row(shared)[upper]] - shared[upper])* 148 | (sums[col(shared)[upper]] - shared[upper]) 149 | 150 | return(mean(scores)) 151 | } 152 | 153 | ``` 154 | 155 | It's easy to plug our new metric and algorithm into the null model engine. Note that at the end we have a list of parameter options. This is how you can pass any extra parameters to your algorithms or metrics. 156 | 157 | ```{r,message=FALSE,warning=FALSE,echo=FALSE} 158 | 159 | novelNull <- null_model_engine(coocSimData,algo="myAlgo",metric="myMetric", 160 | algoOpts = list(rowWeights = runif(dim(coocSimData)[1]), 161 | colWeights = runif(dim(coocSimData)[2])),suppressProg=T) 162 | 163 | ``` 164 | ```{r,eval=FALSE} 165 | 166 | novelNull <- null_model_engine(coocSimData,algo="myAlgo",metric="myMetric", 167 | algoOpts = list(rowWeights = runif(dim(coocSimData)[1]), 168 | colWeights = runif(dim(coocSimData)[2]))) 169 | ``` 170 | 171 | Your new null model can produce a similar summary to the standard null models, as well as a basic histogram plot. 172 | 173 | ```{r, fig.height=4,fig.width=4,fig.align='center'} 174 | summary(novelNull) 175 | plot(novelNull) 176 | 177 | ``` 178 | 179 | 180 | Any randomization algorithm and metric can be plugged into the null model framework. You can also set the type of null model you create to easily print summaries and plots to compare to the existing null models available in `EcoSimR`. 181 | 182 | --------------------------------------------------------------------------------