Marlon E. Cobos, Weverton Trindade, Luis F. Arias-Giraldo, Luis Osorio-Olvera, and A. Townsend Peterson
Package description
kuenm2 is an new version of kuenm Cobos et al. 2019, an R package designed to make the process of ecological niche modeling (ENM) easier, faster, and more reproducible, and at the same time more robust. The aim of this package is to facilitate crucial steps in the ENM process: data preparation, model calibration, selected model exploration, model projections, and analyses of uncertainty and variability.
This new version of the package reduces the dependency on a strictly organized working directory (required only if projections to multiple scenarios are needed). Instead, kuenm2 functions generate specific R objects that store all the necessary information for subsequent steps. The ENM workflow in kuenm2 begins with data preparation, which requires at minimum a data.frame containing occurrence record coordinates (longitude and latitude) and a SpatRaster object with predictor variables.
kuenm2 fits maximum entropy (Maxnet) models or logistic generalized linear models (GLMs). Maxnet models are created as described in Phillips et al. (2017), and GLMs are constructed as in Cobos and Peterson (2023).
Installing the package
Note: Internet connection is required to install the package.
To install the latest release of kuenm2 use the following line of code:
# Installing from CRAN
#install.packages("kuenm2") # in progressThe development version of kuenm2 can be installed using the code below.
# Installing and loading packages
if(!require(remotes)){
install.packages("remotes")
}
# To install the package use
remotes::install_github("marlonecobos/kuenm2")
# To install the package and its vignettes use (if needed use: force = TRUE)
remotes::install_github("marlonecobos/kuenm2", build_vignettes = TRUE) # in progressHaving problems?
If you have any problems during installation of the development version from GitHub, restart R session, close other RStudio sessions you may have open, and try again. If during the installation you are asked to update packages, do so if you don’t need a specific version of one or more of the packages to be installed. If any of the packages gives an error when updating, please install it alone using install.packages(), then try installing kuenm2 again.
To load the package use:
Workflow in kuenm2
The kuenm2 package facilitates the following steps in the ENM process: basic data cleaning, data preparation, model calibration, model exploration, model projections, projection comparisons, and exploration of variability and uncertainty. The figure below shows a schematic view of how the package works. A brief description of the steps that can be performed with the package is presented below. For a complete description and demonstration of the steps, see the package vignettes listed in the section Checking the vignettes.
Figure 1. Schematic view of the workflow to use kuenm2.
Basic data cleaning
Data cleaning tools in kuenm2 help to automate the following basic steps: columns sorting, missing-data cleaning, duplicate removal, exclusion of coordinates with longitude and latitude values of 0, and filtering based on coordinate decimal precision (see function initial_cleaning()). In addition, users can erase duplicates based on the pixels of a raster layer, and move records that are barely outside the valid pixels of a raster layer (see function advanced_cleaning()).
Data preparation
kuenm2 has two main functions that help users prepare their data for the ENM process. These functions take initial data, and guide users to make decisions about the algorithm to be used for models and the combination of parameters (feature classes, regularization multiplier, sets of variables) to be explored later during model calibration. Users can input occurrence records and raster layers, or a data.frame that has been prepared before hand. The main functions for this step are prepare_data() and prepare_user_data(). Users can also explore in more detail how environmental values look like in the data for model calibration using the results from preparing data and the functions explore_calibration_geo(), explore_calibration_hist(), and plot_explore_calibration().
Model calibration
Model calibration is the most computationally challenging process automated in kuenm2. In this step, candidate models are trained and tested using a k-fold cross-validation approach. Then, models are selected based on multiple criteria to warranty that the models used in later steps are the most robust among the candidates. The main function used in this step is calibration().
Model explorations
After the best performing models have been selected, users need to fit this models (fit_selected()) in order to explore their characteristics and continue with the next steps. Fitted models can then be used to assess variable importance in models, as well as to explore variable response curves. See functions variable_importance() and response_curves().
Model projections
Once selected models have been fit and explored, projections to single or multiple scenarios can be done. To facilitate projections to simple or complex combinations of scenarios, multiple functions are available. The function predict_selected() performs projections to single scenarios, and the function project_selected() helps with multiple scenarios. Notice, however, that before projecting to multiple scenarios, some steps need to be done. For an example of projections to future scenarios, with WorldClim variables, see the functions: organize_future_worldclim(), and prepare_projection().
Projection comparisons
When projections to multiple scenarios involve a transfer to another time that can be compared to the current scenario, kuenm2 provides a way to quantify and characterize changes. This can be done using the function projection_changes() and the results help to describe changes in each of the scenarios, and distinct levels of agreement in these changes among scenarios.
Variability and uncertainty
For results of model projections to multiple scenarios, tools for analyses of variability and uncertainty are included in kuenm2. Variability in model projections (projection_variability()) is represented geographically by exploring the variance that comes from replicates, distinct model parameterizations, and general circulation models (in projections to other times). To represent uncertainty, the Mobility Oriented-Parity (MOP) metric is used to compare all projection scenarios to conditions of model training (projection_mop()).
Checking the vignettes
Users can check kuenm2 vignettes for a full explanation of the package functionality. If installing the development version form GitHub, make sure to use the argument build_vignettes = TRUE.
Check each of the vignettes with the code below:
# Guide to basic data cleaning before the ENM process
vignette("basic_data_cleaning")
# Guide to prepare data for the ENM process
vignette("prepare_data")
# Guide to train and evaluate candidate models, and select based on performance
#vignette("model_calibration") # in progress
# Guide to explore selected models, variable importance, response curves
#vignette("model_exploration") # in progress
# Guide to predict models in geographic space (single scenarios)
#vignette("model_predictions") # in progress
# Guide to project models in geographic space (multiple scenarios)
#vignette("model_projections") # in progress
# Guide to explore variability and uncertainty in projections (multiple scenarios)
#vignette("variability_and_uncertainty") # in progress