Ecological niche

Environmental niche modelling

Operating system

Interface (matter)

Maximum bubble pressure method

Niche

Bubble

Habitat

Ecology

Programming language

R package

Graphical user interface

Computer science

Computational science

Computational biology

Biology

Methods in Ecology and Evolution

The description of species' distributional patterns has become a major focus of biodiversity informatics (Guralnick & Hill, 2009). One of the main developments in this field is in the growing use of correlational ecological niche models (ENMs), which are based on the principle that environmental requirements of a species, or its ecological niche, determine the sites where it can survive (Grinnell, 1917). These models are widely used in macroecological and biogeographic studies (Guisan & Zimmermann, 2000; Raxworthy et al., 2003). Applications often include the analysis of potential biological invasions, prediction of disease outbreaks and understanding effects of climate change on species distributions, as well as in phylogenetic frameworks to infer evolution of ecological niches, among many others (Peterson et al., 2011). Recently, efforts have been made to develop specialized software to support ecological niche modelling and species distribution modelling: NicheA (Qiao et al., 2016), kuenm (Cobos, Peterson, Barve, & Osorio-Olvera, 2019), Wallace (Kass et al., 2018), ENMeval (Muscarella et al., 2014), biomod2 (Thuiller, Lafourcade, Engler, & Araújo, 2009), dismo (Hijmans, Phillips, Leathwick, & Elith, 2019), sdm (Naimi & Araújo, 2016), SSDM (Schmitt, Pouteau, Justeau, de Boissieu, & Birnbaum, 2017), SDMToolbox (Brown, Bennett, & French, 2017), sklearn (Pedregosa et al., 2011) and others. These efforts include non-open and open source packages that can be run either inside a graphical user interface (GUI; i.e. SDMToolbox, Wallace) or via commands in a programming language like R and python (i.e. dismo; biomod2, sklearn). Although these packages have a great diversity of functions to do ecological niche modelling exercises, few of them have the characteristic of being a GUI and at the same time provide the functions to perform analysis via scripts (i.e. sdm, SSDM). NicheToolBox (ntbox) is a software package with functions that can be used as a part of a script or via its GUI; it incorporates routines and tools for modelling correlational ecological niches with information that is straightforward to obtain from online sources about species' occurrences (e.g. Global Biodiversity Information Facility, GBIF; https://www.gbif.org) or environmental landscapes (e.g. CHELSA, Bio-Oracle). Alternatively, it can use data provided by the user, while allowing users to keep track of each step of the procedure by saving the workflow. ntbox is written in the R language (http://www.r-project.org/), which has become one of the most widely used languages for data analysis in biodiversity informatics. ntbox provides a detailed log of the modelling process, greatly facilitating replication of analyses. The workflow includes at least five steps: (a) obtaining georeferenced occurrences of species, (b) getting environmental information for modelling (usually in raster format), (c) data curation and spatial filtering of occurrences, (d) model calibration and evaluation and (e) reporting the workflow. One of the deepest ideas coming from Hutchinson (1957) is that a ‘duality’ exists between geographic and environmental spaces (Colwell & Rangel, 2009). The entire enterprise of ecological niche modelling is based on this duality, yet software oriented to help a user to explore it is still largely lacking (Qiao et al., 2016, is an exception). Covering this gap is one of the main goals of ntbox (see Section 5 in Appendix S1). Moreover, despite the broad use of ENMs, no other platform currently implements a model calibration and selection protocol for ellipsoid models with options in a GUI to facilitate visualization of selected models in environmental space. Several reasons exist for using ellipsoids to model niches. First, convex shapes have been proposed as good models of fundamental niches (Jiménez, Soberón, Christen, & Soto, 2019), since it is reasonable to expect that if a species is able to tolerate extremes of a variable, it should also tolerate intermediate values (Drake, 2015). Second, the structure of fitness in niche space has been hypothesized to be approximately ellipsoidal, with some empirical support for this idea (Maguire Jr., 1973; Osorio-Olvera, Yañez-Arenas, Martínez-Meyer, & Peterson, 2020). Third, ellipsoids are simple models as they require only three parameters for defining them: (a) a niche-centroid, which is the point in ecological space where fitness has been argued to have maximum value (Martínez-Meyer, Díaz-Porras, Peterson, & Yáñez-Arenas, 2013); (b) a shape matrix, which measures how dependent two niche axes are and how they change together; and (c) the proportion of observations to be included in the ellipsoid (Van Aelst & Rousseeuw, 2009). Also, experience shows that simple ellipsoids may offer good models of swarms of points in multivariate space (Farber & Kadmon, 2003). A potential weakness of this approach is the implicit assumption that performance curves have symmetric forms, which may not be a general pattern across species (Holt, 2020), even if they are convex. Among the basic operations that the ntbox package supports are: (a) obtaining environmental data through WorldClim (Hijmans, Cameron, Parra, Jones, & Jarvis, 2005), CHELSA (Karger et al., 2016, 2017), Bio-Oracle (Assis et al., 2018; Tyberghein et al., 2012) and ENVIREM (Title & Bemmels, 2018); (b) filtering and visualizing species' occurrence data either provided by the user or retrievable from online sources (e.g. GBIF); (c) specifying a model calibration area, either using a pre-defined polygon or by creating one dynamically on-the-fly on a map provided in the GUI; (d) calculating bivariate correlations among environmental variables to choose the least redundant ones; (e) conducting principal component analysis on environmental variables and transferring them to explicit spatio-temporal scenarios; (f) estimating, visualizing and manipulating ecological niches based on minimum-volume ellipsoids (Van Aelst & Rousseeuw, 2009), BIOCLIM (Booth, Nix, Busby, & Hutchinson, 2014; Busby, 1991) and Maxent (Phillips, Anderson, & Schapire, 2006); (g) analysing group membership of observations using k-means clustering; (h) evaluating models with statistics based on partial ROC (Peterson, Papes, & Soberon, 2008) and multiple metrics based on the confusion matrix (Fielding & Bell, 1997); (i) a model-selection protocol for ellipsoid models based on statistical significance and model predictive performance (see Cobos, Peterson, Barve, et al., 2019; Cobos, Peterson, Osorio-Olvera, & Jiménez-García, 2019); (j) map binarization based on several thresholding methodologies; (k) environmental dissimilarity analysis to evaluate extrapolation risk in model transfers, including mobility-oriented parity (MOP; Owens et al., 2013), multivariate environmental similarity surfaces (MESS; Elith, Kearney, & Phillips, 2010) and extrapolation detection tool (ExDet; Mesgaran, Cousens, & Webber, 2014); (l) geographic information system (GIS) tools to crop and mask raster layers and export them on different raster formats; and (m) saving and exporting the workflow report as HTML files at every moment during the process (Figure 1). See Table 1 for a detailed list of ntbox native functions; users can find help about how to perform each of the above analysis steps inside the GUI in the package reference guide (Appendix S1, which is also compiled as a vignette when installing the package) and also can find code to reproduce examples for each ntbox function in https://luismurao.github.io/ntbox. One of the most important characteristics of ntbox is generation of ecological niche models based on n-dimensional minimum volume ellipsoids (MVEs). It uses Mahalanobis distances to the ellipsoid centroid under the idea that the maximum fitness occurs at the centroid (Osorio-Olvera, Soberón, & Falconi, 2019). This is an attractive alternative to frequently used algorithms for generating correlative niche models (i.e. BIOCLIM, Maxent, GARP) and that lack assumptions about fitness. Mahalanobis distances, on the other hand, show a relationship to abundance (Osorio-Olvera, Yañez-Arenas, et al., 2020; Ureña-Aranda et al., 2015). This approach provides a means by which to define ecological niches based on their shape (i.e. it is widely assumed, through theoretical and experimental work, that fundamental niches have convex forms) and internal structure (i.e. how suitability is distributed within the niche; Jiménez et al., 2019; Maguire Jr., 1973; Osorio-Olvera et al., 2019). ntbox allows the user to perform a model calibration and selection protocol for ellipsoids based on partial ROC and omission rates; to this end, ntbox determines if testing points lie inside (correctly predicted presence) or outside of the ellipsoid model (Etherington, 2019; Van Aelst & Rousseeuw, 2009); then, for statistical significance, it performs a partial ROC test using an environmental background provided by the user; model performance is computed as omission rates for both training and testing data (Cobos, Peterson, Barve, et al., 2019; Cobos, Peterson, Osorio-Olvera, et al., 2019; Osorio-Olvera, Yañez-Arenas, et al., 2020). This evaluation method in environmental space makes the process of model calibration and selection faster than methods that need to create a map of the prediction first and then transform it into a binary map to compute omission rates. We demonstrate the use of ntbox by modelling the potential distribution of Leopardus wiedii, a near-threatened small cat that lives in the Neotropics (Figure 2). Here we modelled the ecological niche of L. wiedii using ellipsoids and showed the performance and speed of ntbox model calibration and selection protocol for MVEs by using environmental information of America at three different spatial resolutions (10′, 5′ and 2.5′). We describe in general terms the functions used at each step of the workflow presented in Figure 1, and provide the code to reproduce the complete example in Appendix S2. First, in ntbox, the user can choose from different environmental data layers which will be downloaded for the modelling process; here, we used the function getData from the raster package to download WorldClim's (https://worldclim.org) bioclimatic layers at 10′, 5′ and 2.5′ resolutions. Second, we searched 5,000 occurrences for L. wiedii from the GBIF database by applying the function search_gbif and explored the provenance and date of collection of these points (Figure 2). The number of georeferenced points that we found before data curation and cleaning was 859. After eliminating wrongly georeferenced localities, filtering occurrences for years ≥1950 and removing spatial duplicates (with the function clean_dup), we had 379 records. We extracted the environmental information of these records for each spatial resolution to look for and remove environmental duplicates. This second process of data curation left us with 231, 274 and 306 records for layers at 10′, 5′ and 2.5′ respectively. Then, each occurrence dataset was split randomly into training and testing data in a proportion of 70:30. For each dataset, we estimated correlations among environmental variables and eliminated the correlated ones using the function correlation_finder with a threshold of r ≤ 0.95. The number of environmental variables kept after this process was 14. Finally, we calibrated MVE models with the function ellisposid_selection, and selected best models by applying the following criteria: (a) a significant value of partial ROC test (p ≤ 0.5); (b) omission rate values for training and testing data ≤5%; and (c) models that presented the maximum value of AUC regarding the three spatial resolutions. To compute the partial ROC test and AUC, we used 10,000, 15,000 and 30,000 background points for the 10′, 5′ and 2.5′ layers respectively. Ellipsoid models were built in 3, 4 and 5 dimensions, using all possible combinations of the 14 least correlated variables, which generated 3,367 models for each spatial resolution (Table 2 and see Appendix S2 for details). The main arguments of the ellisposid_selection function are: (a) environmental training data (env_train); (b) environmental testing data (env_test); (c) a vector with the names of environmental variables to be fitted (env_vars); (d) the proportion of training points to be included in the MVE (level); (e) the environmental background (env_bg), which is a data.frame used to estimate the partial ROC and AUC test (this allows the algorithm to estimate statistical significance and performance with no need for writing raster models); (f) omission rate criteria for selecting models (omr_criteria); (g) a logical argument that indicates if models will be run in parallel (parallel); and (h) a logical argument to specify whether or not to return the value of partial ROC. Users can find details about how to use all the functions described in this example at https://luismurao.github.io/ntbox/. In Table 2, we show the performance and the time to run the calibration and selection process of MVEs. Best models had omission rates lower than 5% and an AUC ranging from ~0.85 to 0.87 (some models had bigger AUCs but they had omission rates >5%; see Appendix S2). The time to run the 3,367 models for each resolution ranged from ~2 to 4 min (computer specifications: core i9 3.6 GHz, 64 GB RAM, Windows 10). Differences in running times relate to the number of background points used to compute the partial ROC and AUC test. The code to replicate this example is given in Appendix S2, and Figure 2 shows results as they are displayed in the GUI, with the corresponding binary distribution map of the best model at a 2.5′ spatial resolution after imposing a 10th-percentile threshold on the suitability raster. Here we present ntbox, an r package that supports functionalities for doing tasks related to ecological niche modelling, ranging from getting occurrence and environmental data and performing common GIS tasks, to evaluating ENMs and SDMs (see Figure 1; Table 1). These analyses can be run either via the GUI or from the R command line, thus allowing users to share and replicate the protocols generated from the different processes according to requirements from different users, such as larger-scale analyses or in collaborative schemes with users with different degrees of programming skills. Although the ENM part of the workflow focuses on modelling niches as ellipsoids, the package allows users to run other algorithms as well, including Maxent with all its parameters (currently available only in the command-line interface; see Table 1). One strength of the ellipsoid calibration and selection protocol presented here is speed and performance (Table 2). The example shown here is just for demonstrating the use of ntbox; however, it is important to bear in mind that the workflow for modelling species' niches may take into account other factors such as sampling biases in occurrence records, the occurrence thinning method for trying to avoid problems related to spatial autocorrelation, the relationship between the time when an observation was made and the temporal resolution of modelling layers, among other things (Peterson et al., 2011). The aim of ntbox is to supply tools for conducting analyses related to understanding species' niches and geographic distributions. Future modules of the package will allow users to run dynamic distribution models to estimate, for example, the dispersal dynamics of invasive species (Osorio-Olvera & Soberon, 2020). As ntbox is a project born in the open-source community (the source code has been available freely on GitHub since 2016), anyone can contribute to it via its GitHub repository (https://github.com/luismurao/ntbox); we expect that users wishing to contribute could help by providing code to run other modelling algorithms and statistical tools or by reporting bugs. Many of the ideas and improvements to the software were realized after several rounds of analysis and on different projects with researchers and students during a research stay by L.O.-O. at the Biodiversity Institute, University of Kansas, as well as during courses taught at the Instituto de Ecología, A.C. and UNAM. L.O.-O. acknowledges the Posgrado en Ciencias Biológicas, UNAM. We also thank Comisión Nacional para el Conocimiento y Uso de la Biodiversidad (CONABIO) for providing web support and space on their servers (shiny.conabio.gob.mx:3838/nichetoolb2/). J.S., R.G.C.-D. and L.O.-O. thank Blitzi Soberon for providing them moral encouragement. We thank Ángela Nava-Bolaños for her comments on a version of the manuscript. Authors declare no conflict of interest. L.O.-O. conceived the project and coded the software; A.L.-N. and L.O.-O. lead the writing of the manuscript; J.S., A.T.P., A.L.-N., M.F., R.G.C.-D., E.M.-M., V.B. and N.B. gave suggestions to improve the package. All authors tested and verified the software to give final approval for publication. Obtaining NicheToolBox: The full code of the r package NicheToolBox (ntbox), along with instructions on how to install and use it, is available in the corresponding author's main GitHub repository: https://github.com/luismurao/ntbox. The source code is licensed under GPL-3. ntbox package is publicly available on Zenodo at https://doi.org/10.5281/zenodo.3937910 (Osorio-Olvera, Lira-Noriega, et al., 2020). Please note: The publisher is not responsible for the content or functionality of any supporting information supplied by the authors. Any queries (other than missing content) should be directed to the corresponding author for the article.

<scp>ntbox</scp> : An <scp>r</scp> package with graphical user interface for modelling and evaluating multidimensional ecological niches

ntbox : An r package with graphical user interface for modelling and evaluating multidimensional ecological niches