diff --git a/README.md b/README.md index 3ede9de..f56d3be 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ -[![CRAN version](http://www.r-pkg.org/badges/version/ENMeval)](https://CRAN.R-project.org/package=ENMeval) [![downloads](http://cranlogs.r-pkg.org/badges/grand-total/ENMeval?color=orange)](http://cranlogs.r-pkg.org/badges/grand-total/ENMeval?color=orange) +[![CRAN version](https://www.r-pkg.org/badges/version/ENMeval)](https://CRAN.R-project.org/package=ENMeval) [![downloads](https://cranlogs.r-pkg.org:443/badges/grand-total/ENMeval?color=orange)](https://cranlogs.r-pkg.org:443/badges/grand-total/ENMeval?color=orange) # ENMeval R package for automated runs and evaluations of ecological niche models. -[`ENMeval`](https://cran.r-project.org/package=ENMeval) is an R package that performs automated runs and evaluations of ecological niche models, and currently implements Maxent using the either (now by default) the 'maxnet' algoritm developed by [Phillips *et al.* (2017)](https://onlinelibrary.wiley.com/doi/full/10.1111/ecog.03049) using the ['maxnet' R package](https://cran.r-project.org/package=maxnet) or [the original java program (http://biodiversityinformatics.amnh.org/open_source/maxent/). `ENMeval` was made for those who want to "tune" their models to maximize predictive ability and avoid overfitting, or in other words, optimize model complexity to balance goodness-of-fit and predictive ability. The primary function, `ENMevaluate`, does all the heavy lifting and returns several items including a table of evaluation statistics and, for each setting combination, a model object and a raster layer showing the model prediction across the study extent. There are also options for calculating niche overlap between predictions, running in parallel to speed up computation, and more. For a more detailed description of the package, check out the open-access publication: +[`ENMeval`](https://cran.r-project.org/package=ENMeval) is an R package that performs automated runs and evaluations of ecological niche models, and currently implements Maxent using the either (now by default) the 'maxnet' algoritm developed by [Phillips *et al.* (2017)](https://onlinelibrary.wiley.com/doi/full/10.1111/ecog.03049) using the ['maxnet' R package](https://cran.r-project.org/package=maxnet) or [the original java program (https://biodiversityinformatics.amnh.org/open_source/maxent/). `ENMeval` was made for those who want to "tune" their models to maximize predictive ability and avoid overfitting, or in other words, optimize model complexity to balance goodness-of-fit and predictive ability. The primary function, `ENMevaluate`, does all the heavy lifting and returns several items including a table of evaluation statistics and, for each setting combination, a model object and a raster layer showing the model prediction across the study extent. There are also options for calculating niche overlap between predictions, running in parallel to speed up computation, and more. For a more detailed description of the package, check out the open-access publication: -[Muscarella, R., Galante, P. J., Soley-Guardia, M., Boria, R. A., Kass, J. M., Uriarte, M. and Anderson, R. P. (2014), ENMeval: An R package for conducting spatially independent evaluations and estimating optimal model complexity for Maxent ecological niche models. Methods in Ecology and Evolution, 5: 1198–1205.](http://onlinelibrary.wiley.com/doi/10.1111/2041-210X.12261/full) +[Muscarella, R., Galante, P. J., Soley-Guardia, M., Boria, R. A., Kass, J. M., Uriarte, M. and Anderson, R. P. (2014), ENMeval: An R package for conducting spatially independent evaluations and estimating optimal model complexity for Maxent ecological niche models. Methods in Ecology and Evolution, 5: 1198–1205.](https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/2041-210X.12261) Also see the vignette for examples of implementation. diff --git a/man/ENMeval-package.Rd b/man/ENMeval-package.Rd index d44f81e..4884a79 100644 --- a/man/ENMeval-package.Rd +++ b/man/ENMeval-package.Rd @@ -32,7 +32,7 @@ There are some differences between the 'maxnet' and 'maxent.jar' algorithms that \note{ Currently, \pkg{ENMeval} only implements the Maxent algorithm (via either the 'maxent.jar' or 'maxnet' implementations), but we eventually plan to expand it to work with other algorithms. All calculations are based on the raw Maxent output (i.e., \emph{not} logistic or cumulative transformations) and users can choose whether to use 'clamping' (see Maxent documentation for details on this option). Additionally, Maxent models are run with the arguments: \code{noaddsamplestobackground} and \code{noremoveDuplicates}. Users should consult Maxent documentation (Phillips \emph{et al.} 2006) and other references (e.g., Phillips and Dudik 2008) for more information on these options. We note that interested users can edit the source code of \code{ENMeval} (in particular, the \code{\link{make.args}} and \code{\link{tuning}} functions) if they desire to change these or other options. -When using the 'maxent.jar' implementation (\bold{\emph{not default as of version 0.3.0}}), \code{ENMevaluate} directly uses several functions from the \pkg{dismo} package (Hijmans \emph{et al.} 2011). Most importantly, the \code{maxent} function that runs the Maxent algorithm (Phillips \emph{et al.} 2006) in Java. Before running this command, the user must first download Maxent from \href{http://www.cs.princeton.edu/~schapire/maxent/}{this website}. Then, place the file 'maxent.jar' in the 'java' folder of the \pkg{dismo} package. The user can locate that folder by typing: \code{system.file("java", package="dismo")}. For additional details, users should consult the documentation of the \pkg{dismo} package (or just use the newer [default] \pkg{maxnet} implementation). +When using the 'maxent.jar' implementation (\bold{\emph{not default as of version 0.3.0}}), \code{ENMevaluate} directly uses several functions from the \pkg{dismo} package (Hijmans \emph{et al.} 2011). Most importantly, the \code{maxent} function that runs the Maxent algorithm (Phillips \emph{et al.} 2006) in Java. Before running this command, the user must first download Maxent from \href{https://www.cs.princeton.edu/~schapire/maxent/}{this website}. Then, place the file 'maxent.jar' in the 'java' folder of the \pkg{dismo} package. The user can locate that folder by typing: \code{system.file("java", package="dismo")}. For additional details, users should consult the documentation of the \pkg{dismo} package (or just use the newer [default] \pkg{maxnet} implementation). } diff --git a/man/make.args.Rd b/man/make.args.Rd index 9bfa462..51c5a2f 100644 --- a/man/make.args.Rd +++ b/man/make.args.Rd @@ -21,7 +21,7 @@ When \code{labels = FALSE}, the following additional arguments are added: \code{noaddsamplestobackground, noremoveDuplicates, noautofeature}. -For details on these arguments, see Phillips \emph{et al.} (2006) and the help documentation and tutorial of the Maxent software and the tutorial that can be downloaded from \href{http://www.cs.princeton.edu/~schapire/maxent/}{this website}. +For details on these arguments, see Phillips \emph{et al.} (2006) and the help documentation and tutorial of the Maxent software and the tutorial that can be downloaded from \href{https://www.cs.princeton.edu/~schapire/maxent/}{this website}. } \value{ diff --git a/man/var.importance.Rd b/man/var.importance.Rd index e11f450..71bc68d 100644 --- a/man/var.importance.Rd +++ b/man/var.importance.Rd @@ -33,7 +33,7 @@ var.importance(mod) \note{Both metrics should be interpreted with caution when the predictor variables are correlated (Phillips 2006).} -\references{Phillips, S. (2006) A brief tutorial on Maxent. AT&T Research. Available at: http://www.cs.princeton.edu/~schapire/maxent/tutorial/tutorial.doc} +\references{Phillips, S. (2006) A brief tutorial on Maxent. AT&T Research. Available at: https://www.cs.princeton.edu/~schapire/maxent/tutorial/tutorial.doc} \author{Jamie M. Kass and Robert Muscarella } diff --git a/vignettes/ENMeval-vignette.Rmd b/vignettes/ENMeval-vignette.Rmd index b5cc1ad..05b39a0 100644 --- a/vignettes/ENMeval-vignette.Rmd +++ b/vignettes/ENMeval-vignette.Rmd @@ -25,9 +25,9 @@ knitr::opts_chunk$set(collapse=TRUE, message=FALSE, warning=FALSE, comment="#>") ## Introduction {#intro} -[`ENMeval`](https://cran.r-project.org/package=ENMeval) is an R package that performs automated runs and evaluations of ecological niche models, and currently only implements [Maxent](http://biodiversityinformatics.amnh.org/open_source/maxent/). `ENMeval` was made for those who want to "tune" their models to maximize predictive ability and avoid overfitting, or in other words, optimize model complexity to balance goodness-of-fit and predictive ability. The primary function, `ENMevaluate`, does all the heavy lifting and returns several items including a table of evaluation statistics and, for each setting combination (here, colloquially: *runs*), a model object and a raster layer showing the model prediction across the study extent. There are also options for calculating niche overlap between predictions, running in parallel to speed up computation, and more. For a more detailed description of the package, check out the open-access publication: +[`ENMeval`](https://cran.r-project.org/package=ENMeval) is an R package that performs automated runs and evaluations of ecological niche models, and currently only implements [Maxent](https://biodiversityinformatics.amnh.org/open_source/maxent/). `ENMeval` was made for those who want to "tune" their models to maximize predictive ability and avoid overfitting, or in other words, optimize model complexity to balance goodness-of-fit and predictive ability. The primary function, `ENMevaluate`, does all the heavy lifting and returns several items including a table of evaluation statistics and, for each setting combination (here, colloquially: *runs*), a model object and a raster layer showing the model prediction across the study extent. There are also options for calculating niche overlap between predictions, running in parallel to speed up computation, and more. For a more detailed description of the package, check out the open-access publication: -[Muscarella, R., Galante, P. J., Soley-Guardia, M., Boria, R. A., Kass, J. M., Uriarte, M. and Anderson, R. P. (2014), ENMeval: An R package for conducting spatially independent evaluations and estimating optimal model complexity for Maxent ecological niche models. Methods in Ecology and Evolution, 5: 1198–1205.](http://onlinelibrary.wiley.com/doi/10.1111/2041-210X.12261/full) +[Muscarella, R., Galante, P. J., Soley-Guardia, M., Boria, R. A., Kass, J. M., Uriarte, M. and Anderson, R. P. (2014), ENMeval: An R package for conducting spatially independent evaluations and estimating optimal model complexity for Maxent ecological niche models. Methods in Ecology and Evolution, 5: 1198–1205.](https://onlinelibrary.wiley.com/doi/10.1111/2041-210X.12261/full) ## Data Acquisition & Pre-processing {#data} In this vignette, we briefly demonstrate acquisition and pre-processing of input data for `ENMeval`. There are a number of other excellent tutorials on these steps, some of which we compiled in the [Resources](#resources) section. @@ -35,8 +35,8 @@ In this vignette, we briefly demonstrate acquisition and pre-processing of input We'll start by reading in an occurrence dataset for [*Bradypus variegatus*](https://en.wikipedia.org/wiki/Brown-throated_sloth), the Brown-throated sloth. We'll go ahead and load the `ENMeval` package. (We are using [`spocc`](https://cran.r-project.org/package=spocc) to download occurrence records). ```{r occDownload} -if (!require('spocc')) install.packages('spocc', repos="http://cran.us.r-project.org") -if (!require('ENMeval')) install.packages('ENMeval', repos="http://cran.us.r-project.org") +if (!require('spocc')) install.packages('spocc', repos="https://cran.us.r-project.org") +if (!require('ENMeval')) install.packages('ENMeval', repos="https://cran.us.r-project.org") library(ENMeval) @@ -47,7 +47,7 @@ occs <- readRDS("bvariegatus.rds") occs <- occs[!duplicated(occs),] ``` -We are going to model the climatic niche suitability for our focal species using climate data from [WorldClim](http://www.worldclim.org/). WorldClim has a range of variables available at various resolutions; for simplicity, here we'll use the 9 bioclimatic variables at 10 arcmin resolution (about 20 km across at the equator) included in the `dismo` package. These climatic data are based on 50-year averages from 1950-2000. Now's also a good time to load the package, as it includes all the downstream dependencies (`raster`, `dismo`, etc.). +We are going to model the climatic niche suitability for our focal species using climate data from [WorldClim](https://www.worldclim.org/). WorldClim has a range of variables available at various resolutions; for simplicity, here we'll use the 9 bioclimatic variables at 10 arcmin resolution (about 20 km across at the equator) included in the `dismo` package. These climatic data are based on 50-year averages from 1950-2000. Now's also a good time to load the package, as it includes all the downstream dependencies (`raster`, `dismo`, etc.). ```{r envDownload, warning=FALSE, message=FALSE, fig.width = 5, fig.height = 5} library(raster) @@ -98,8 +98,8 @@ envs.backg <- crop(envs, bb.buf) We may also, however, want to remove the Caribbean islands (for example) from our background extent. For this, we can use tools from the [`maptools`](https://cran.r-project.org/package=maptools) package, which is not automatically loaded with `ENMeval`. ```{r removeCaribbean, message=FALSE, fig.width = 5, fig.height = 5} -if (!require('maptools')) install.packages('maptools', repos="http://cran.us.r-project.org") -if (!require('rgeos')) install.packages('rgeos', repos="http://cran.us.r-project.org") +if (!require('maptools')) install.packages('maptools', repos="https://cran.us.r-project.org/") +if (!require('rgeos')) install.packages('rgeos', repos="https://cran.us.r-project.org/") library(maptools) library(rgeos) @@ -436,37 +436,37 @@ Below is a running list of other things we plan to add to this vignette. Feel f ###### Web Resources - [Hijmans, R. and Elith, J. (2016) Species distribution modeling with R. dismo vignette.](https://cran.r-project.org/package=dismo) -- [Phillips, S. J. (2006) Phillips, S. (2006) A brief tutorial on Maxent. AT&T Research. Available at: http://biodiversityinformatics.amnh.org/open_source/maxent/](http://biodiversityinformatics.amnh.org/open_source/maxent/) +- [Phillips, S. J. (2006) Phillips, S. (2006) A brief tutorial on Maxent. AT&T Research. Available at: https://biodiversityinformatics.amnh.org/open_source/maxent/](https://biodiversityinformatics.amnh.org/open_source/maxent/) -- [Yoder, J. (2013) Species distribution models in R. The Molecular Ecologist.](http://www.molecularecologist.com/2013/04/species-distribution-models-in-r/) +- [Yoder, J. (2013) Species distribution models in R. The Molecular Ecologist.](https://www.molecularecologist.com/2013/04/species-distribution-models-in-r/) - [Maxent Google Group](https://groups.google.com/forum/embed/#!forum/maxent) ###### General Guides -- [Merow, C., Smith, M., and Silander, J.A. (2013) A practical guide to Maxent: what it does, and why inputs and settings matter. Ecography 36, 1-12.](http://onlinelibrary.wiley.com/doi/10.1111/j.1600-0587.2013.07872.x/abstract) +- [Merow, C., Smith, M., and Silander, J.A. (2013) A practical guide to Maxent: what it does, and why inputs and settings matter. Ecography 36, 1-12.](https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0587.2013.07872.x) -- [Peterson, A.T., Soberón, J., Pearson, R.G., Anderson, R.P., Martínez-Meyer, E., Nakamura, M., and Araújo, M.B. (2011) Ecological Niches and Geographic Distributions. Monographs in Population Biology, 49. Princeton University Press.](http://press.princeton.edu/titles/9641.html) +- [Peterson, A.T., Soberón, J., Pearson, R.G., Anderson, R.P., Martínez-Meyer, E., Nakamura, M., and Araújo, M.B. (2011) Ecological Niches and Geographic Distributions. Monographs in Population Biology, 49. Princeton University Press.](https://press.princeton.edu/titles/9641.html) -- [Renner, I.W., Elith, J., Baddeley, A., Fithian, W., Hastie, T., Phillips, S.J., . . . Warton, D.I. (2015) Point process models for presence-only analysis. Methods in Ecology and Evolution 6, 366-379.](http://onlinelibrary.wiley.com/doi/10.1111/2041-210X.12352/abstract) +- [Renner, I.W., Elith, J., Baddeley, A., Fithian, W., Hastie, T., Phillips, S.J., . . . Warton, D.I. (2015) Point process models for presence-only analysis. Methods in Ecology and Evolution 6, 366-379.](https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/2041-210X.12352) ###### Model Evaluation -- [Aiello-Lammens, M.E., Boria, R.A., Radosavljevic, A., Vilela, B., and Anderson, R.P. (2015) spThin: an R package for spatial thinning of species occurrence records for use in ecological niche models. Ecography 38, 541-545.](http://onlinelibrary.wiley.com/doi/10.1111/ecog.01132/abstract) +- [Aiello-Lammens, M.E., Boria, R.A., Radosavljevic, A., Vilela, B., and Anderson, R.P. (2015) spThin: an R package for spatial thinning of species occurrence records for use in ecological niche models. Ecography 38, 541-545.](https://onlinelibrary.wiley.com/doi/abs/10.1111/ecog.01132) -- [Fielding, A.H. and Bell, J.F. (1997) A review of methods for the assessment of prediction errors in conservation presence-absence models. Environmental Conservation 24, 38-49.](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.463.359&rep=rep1&type=pdf) +- [Fielding, A.H. and Bell, J.F. (1997) A review of methods for the assessment of prediction errors in conservation presence-absence models. Environmental Conservation 24, 38-49.](https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.463.359&rep=rep1&type=pdf) -- [Hijmans, R.J. (2012) Cross-validation of species distribution models: removing spatial sorting bias and calibration with a null model. Ecology 93, 679-688.](http://onlinelibrary.wiley.com/doi/10.1890/11-0826.1/abstract) +- [Hijmans, R.J. (2012) Cross-validation of species distribution models: removing spatial sorting bias and calibration with a null model. Ecology 93, 679-688.](https://esajournals.onlinelibrary.wiley.com/doi/abs/10.1890/11-0826.1) -- [Muscarella, R., Galante, P. J., Soley-Guardia, M., Boria, R. A., Kass, J. M., Uriarte, M. and Anderson, R. P. (2014), ENMeval: An R package for conducting spatially independent evaluations and estimating optimal model complexity for Maxent ecological niche models. Methods Ecol Evol, 5: 1198–1205.](http://onlinelibrary.wiley.com/doi/10.1111/2041-210X.12261/full) +- [Muscarella, R., Galante, P. J., Soley-Guardia, M., Boria, R. A., Kass, J. M., Uriarte, M. and Anderson, R. P. (2014), ENMeval: An R package for conducting spatially independent evaluations and estimating optimal model complexity for Maxent ecological niche models. Methods Ecol Evol, 5: 1198–1205.](https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/2041-210X.12261) -- [Radosavljevic, A. and Anderson, R.P. (2014) Making better Maxent models of species distributions: complexity, overfitting and evaluation. Journal of Biogeography 41, 629-643.](http://onlinelibrary.wiley.com/doi/10.1111/jbi.12227/abstract) +- [Radosavljevic, A. and Anderson, R.P. (2014) Making better Maxent models of species distributions: complexity, overfitting and evaluation. Journal of Biogeography 41, 629-643.](https://onlinelibrary.wiley.com/doi/abs/10.1111/jbi.12227) -- [Shcheglovitova, M. and Anderson, R.P. (2013) Estimating optimal complexity for ecological niche models: A jackknife approach for species with small sample sizes. Ecol. Model. 269, 9-17.](http://www.sciencedirect.com/science/article/pii/S0304380013004043) +- [Shcheglovitova, M. and Anderson, R.P. (2013) Estimating optimal complexity for ecological niche models: A jackknife approach for species with small sample sizes. Ecol. Model. 269, 9-17.](https://www.sciencedirect.com/science/article/pii/S0304380013004043) -- [Veloz, S.D. (2009) Spatially autocorrelated sampling falsely inflates measures of accuracy for presence-only niche models. Journal of Biogeography 36, 2290-2299.](http://onlinelibrary.wiley.com/doi/10.1111/j.1365-2699.2009.02174.x/abstract) +- [Veloz, S.D. (2009) Spatially autocorrelated sampling falsely inflates measures of accuracy for presence-only niche models. Journal of Biogeography 36, 2290-2299.](https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2699.2009.02174.x) -- [Wenger, S.J. and Olden, J.D. (2012) Assessing transferability of ecological models: an underappreciated aspect of statistical validation. Methods in Ecology and Evolution 3, 260-267.](http://onlinelibrary.wiley.com/doi/10.1111/j.2041-210X.2011.00170.x/abstract) +- [Wenger, S.J. and Olden, J.D. (2012) Assessing transferability of ecological models: an underappreciated aspect of statistical validation. Methods in Ecology and Evolution 3, 260-267.](https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/j.2041-210X.2011.00170.x) ###### Some Empirical Examples -- [Pearson, R.G., Raxworthy, C.J., Nakamura, M., and Peterson, A.T. (2007) Predicting species distributions from small numbers of occurrence records: a test case using cryptic geckos in Madagascar. Journal of Biogeography 34, 102-117.](http://onlinelibrary.wiley.com/doi/10.1111/j.1365-2699.2006.01594.x/abstract) +- [Pearson, R.G., Raxworthy, C.J., Nakamura, M., and Peterson, A.T. (2007) Predicting species distributions from small numbers of occurrence records: a test case using cryptic geckos in Madagascar. Journal of Biogeography 34, 102-117.](https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2699.2006.01594.x) diff --git a/vignettes/ENMeval-vignette.md b/vignettes/ENMeval-vignette.md index 9044ea7..a086900 100644 --- a/vignettes/ENMeval-vignette.md +++ b/vignettes/ENMeval-vignette.md @@ -14,13 +14,13 @@ Introduction ------------ - + - - + + @@ -30,7 +30,7 @@ Introduction - + @@ -62,8 +62,8 @@ Introduction - - + + @@ -283,21 +283,21 @@ Introduction - + - - - + + + - - - - - - - - + + + + + + + + - +