Package 'ecospat'

Description

Collection of methods, utilities and data sets for the support of spatial ecology analyses with a focus on pre-, core and post- modelling analyses of species distribution, niche quantification and community assembly. The ecospat package was written by current and former members and collaborators of the ecospat group of Antoine Guisan, Department of Ecology and Evolution (DEE) & Institute of Earth Surface Dynamics (IDYST), University of Lausanne, Switzerland.

Pre-modelling:

• Spatial autocorrelation:ecospat.mantel.correlogram

• Variable selection: ecospat.npred

• Climate Analalogy: ecospat.climan, ecospat.mess, ecospat.plot.mess

• Phylogenetic diversity measures: ecospat.calculate.pd

• Biotic Interactions: ecospat.cons_Cscore, ecospat.Cscore, ecospat.co_occurrences

• Minimum Dispersal routes: ecospat.mdr

• Niche Quantification: ecospat.grid.clim.dyn, ecospat.niche.equivalency.test, ecospat.niche.similarity.test, ecospat.plot.niche, ecospat.plot.niche.dyn, ecospat.plot.contrib, ecospat.niche.overlap, ecospat.plot.overlap.test, ecospat.niche.dyn.index, ecospat.shift.centroids, ecospat.niche.dynIndexProjGeo, ecospat.niche.zProjGeo, ecospat.margin,ecospat.nichePOSNB,ecospat.nicheNBmean

• Data Preparation: ecospat.caleval, ecospat.cor.plot, ecospat.occ.desaggregation, ecospat.rand.pseudoabsences, ecospat.rcls.grd, ecospat.recstrat_prop, ecospat.recstrat_regl, ecospat.sample.envar

Core Niche Modelling:

• Model evaluation: ecospat.cv.glm, ecospat.permut.glm, ecospat.cv.gbm, ecospat.cv.me, ecospat.cv.rf, ecospat.boyce, ecospat.CommunityEval, ecospat.cohen.kappa, ecospat.max.kappa, ecospat.max.tss, ecospat.meva.table, ecospat.plot.kappa, ecospat.plot.tss, ecospat.adj.D2.glm, ecospat.CCV.createDataSplitTable, ecospat.CCV.modeling, ecospat.CCV.communityEvaluation.bin, ecospat.CCV.communityEvaluation.prob,ecospat.ESM.EnsembleEvaluation,ecospat.poolingEvaluation

• Spatial predictions and projections: ecospat.ESM.Modeling, ecospat.ESM.EnsembleModeling, ecospat.ESM.Projection, ecospat.ESM.EnsembleProjection, ecospat.SESAM.prr, ecospat.binary.model, ecospat.Epred, ecospat.mpa

• Variable Importance: ecospat.maxentvarimport, ecospat.ESM.VarContrib

Post Modelling:

• Variance Partition: ecospat.varpart

• Spatial predictions of species assemblages: ecospat.cons_Cscore

• Range size quantification: ecospat.rangesize, ecospat.occupied.patch

Description

This function is used for calculating an adjusted D2 from a calibrated GLM object

Usage

ecospat.adj.D2.glm(glm.obj)

Arguments

Details

This function takes a calibrated GLM object with a binomial error distribution and returns an evaluation of the model fit. The measure of the fit of the models is expressed as the percentage of explained deviance adjusted by the number of degrees of freedom used (similar to the adjusted-R2 in the case of Least-Square regression; see Weisberg 1980) and is called the adjusted-D2 (see guisan and Zimmermann 2000 for details on its calculation).

Value

Returns an adjusted D square value (proportion of deviance accounted for by the model).

Author(s)

Christophe Randin [email protected] and Antoine Guisan [email protected]

References

Weisberg, S. 1980. Applied linear regression. Wiley.

Guisan, A., S.B. Weiss and A.D. Weiss. 1999. GLM versus CCA spatial modeling of plant species distribution. Plant Ecology, 143, 107-122.

Guisan, A. and N.E. Zimmermann. 2000. Predictive habitat distribution models in ecology. Ecol. Model., 135, 147-186.

Examples

data(ecospat.testData)
glm.obj<-glm(Achillea_millefolium~ddeg+mind+srad+slp+topo, 
family = binomial, data=ecospat.testData)

ecospat.adj.D2.glm(glm.obj)

Description

Generate a binary map from a continuous model prediction.

Usage

ecospat.binary.model (Pred, Threshold)

Arguments

Details

This function generates a binary model prediction (presence/absence) from an original model applying a threshold. The threshold could be arbitrary, or be based on the maximum acceptable error of false negatives (i.e. percentage of the presence predicted as absences, omission error).

Value

The binary model prediction (presence/absence).

Author(s)

Ruben G. Mateo [email protected] with contributions of Frank Breiner [email protected] and Flavien Collart

References

Fielding, A.H. and J.F. Bell. 1997. A review of methods for the assessment of prediction errors in conservation presence/absence models. Environmental Conservation, 24: 38-49.

Engler, R., A Guisan and L. Rechsteiner. 2004. An improved approach for predicting the distribution of rare and endangered species from occurrence and pseudo-absence data. Journal of Applied Ecology, 41, 263-274.

Liu, C., Berry, P. M., Dawson, T. P. and R. G. Pearson. 2005. Selecting thresholds of occurrence in the prediction of species distributions. Ecography, 28, 385-393.

Jimenez-Valverde, A. and J.M.Lobo. 2007. Threshold criteria for conversion of probability of species presence to either-or presence-absence. Acta oecologica, 31, 361-369.

Liu, C., White, M. and G. Newell. 2013. Selecting thresholds for the prediction of species occurrence with presence-only data. J. Biogeogr., 40, 778-789.

Freeman, E.A. and G.G. Moisen. 2008. A comparison of the performance of threshold criteria for binary classification in terms of predicted prevalence and kappa. Ecological Modelling, 217, 48-58.

See Also

ecospat.mpa, optimal.thresholds

Examples

library(terra)
# coordinates of the plots
xy <- ecospat.testData[,2:3]

# environmental data
predictors <- terra::rast(system.file("extdata","ecospat.testEnv.tif",package="ecospat"))

env <- terra::extract(predictors,xy,ID=FALSE)  
spData <- cbind.data.frame(occ=ecospat.testData$Veronica_alpina,env)
mod <- glm(occ~ddeg0+I(ddeg0^2)+srad68+I(srad68^2),data=spData,family = binomial())

# predict to entire dataset
pred <- terra::predict(predictors,mod,type="response") 
  
### make binary maps
# use MPA to convert suitability to binary map

mpa.cutoff <- ecospat.mpa(pred,xy[spData$occ==1,],perc = 0.9) # 90% presences encompassed
pred.bin.mpa <- ecospat.binary.model(pred,mpa.cutoff)

plot(pred.bin.mpa)
points(xy[spData$occ==1,])

Description

Calculate the Boyce index as in Hirzel et al. (2006). The Boyce index is used to assess model performance.

Usage

ecospat.boyce (fit, obs, nclass=0, window.w="default", res=100, PEplot = TRUE, 
rm.duplicate = TRUE, method = 'spearman')

Arguments

rm.duplicate = TRUE, method = 'spearman'

Details

The Boyce index only requires presences and measures how much model predictions differ from random distribution of the observed presences across the prediction gradients (Boyce et al. 2002). It is thus an appropriate metric in the case of presence-only models. It is continuous and varies between -1 and +1. Positive values indicate a model which present predictions are consistent with the distribution of presences in the evaluation dataset, values close to zero mean that the model is not different from a random model, negative values indicate counter predictions, i.e., predicting poor quality areas where presences are more frequent (Hirzel et al. 2006).

Removing the successive duplicated P/E values (rm.duplicate = TRUE) focuses more on the discriminative aspect of the predictions, lowering the assessment of the evaluation of the model resolution (sensu Hirzel et al. 2006 p. 150). However, it seems that in the initial version, dupplicated values were not removed.

In the initial publication on the continuous Boyce index, the correlation was set to method = 'spearman'. However, using method = 'kendall' or method = 'pearson' might be more informative about the accuracy of the predictions.

Value

The function returns a list that contains a vector F.ratio (the predicted-to-expected ratio for each class-interval) and a numeric Spearman.cor (the Boyce index value)

Author(s)

Blaise Petitpierre [email protected] and Frank Breiner [email protected] with the updates of Flavien Collart

References

Boyce, M.S., P.R. Vernier, S.E. Nielsen and F.K.A. Schmiegelow. 2002. Evaluating resource selection functions. Ecol. Model., 157, 281-300.

Hirzel, A.H., G. Le Lay, V. Helfer, C. Randin and A. Guisan. 2006. Evaluating the ability of habitat suitability models to predict species presences. Ecol. Model., 199, 142-152.

Examples

obs <- (ecospat.testData$glm_Saxifraga_oppositifolia
[which(ecospat.testData$Saxifraga_oppositifolia==1)])

ecospat.boyce (fit = ecospat.testData$glm_Saxifraga_oppositifolia , obs, nclass=0, 
window.w="default", res=100, PEplot = TRUE)

Description

Calculate all phylogenetic diversity measures listed in Schweiger et al., 2008 (see full reference below).

Usage

ecospat.calculate.pd (tree, data, method="spanning", type="clade", root=FALSE, 
average=FALSE, verbose=FALSE)

Arguments

Details

Given a phylogenetic tree and a presence/absence matrix this script calculates phylogenetic diversity of a group of species across a given set of grid cells or locations. The library "ape" is required to read the tree in R. Command is "read.tree" or "read.nexus". Options of type: "P" is a normalized mearure of "Q". "clade" is "PDnode" when root= FALSE, and is "PDroot" ehn root =TRUE. "species" is "AvPD".

Value

This function returns a list of phylogenetic diversity values for each of the grid cells in the presence/absence matrix

Author(s)

Nicolas Salamin [email protected] and Dorothea Pio [email protected]

References

Schweiger, O., S. Klotz, W. Durka and I. Kuhn. 2008. A comparative test of phylogenetic diversity indices. Oecologia, 157, 485-495.

Pio, D.V., O. Broennimann, T.G. Barraclough, G. Reeves, A.G. Rebelo, W. Thuiller, A. Guisan and N. Salamin. 2011. Spatial predictions of phylogenetic diversity in conservation decision making. Conservation Biology, 25, 1229-1239.

Pio, D.V., R. Engler, H.P. Linder, A. Monadjem, F.P.D. Cotterill, P.J. Taylor, M.C. Schoeman, B.W. Price, M.H. Villet, G. Eick, N. Salamin and A. Guisan. 2014. Climate change effects on animal and plant phylogenetic diversity in southern Africa. Global Change Biology, 20, 1538-1549.

Examples

fpath <- system.file("extdata", "ecospat.testTree.tre", package="ecospat")
library(ape)
tree <-ape::read.tree(fpath)
data <- ecospat.testData[9:52] 

pd <- ecospat.calculate.pd(tree, data, method = "spanning", type = "species", root = FALSE, 
average = FALSE, verbose = TRUE )

plot(pd)

Description

Generate an evaluation and calibration dataset with a desired ratio of disaggregation.

Usage

ecospat.caleval (data, xy, row.num=1:nrow(data), nrep=1, ratio=0.7, 
disaggregate=0, pseudoabs=0, npres=0, replace=FALSE)

Arguments

Details

This functions generates two list, one with the calibration or training dataset and other list with the evaluation or testing dataset disaggregated with a minimum distance.

Value

list("eval"=eval,"cal"=cal))

Author(s)

Blaise Petitpierre [email protected]

Examples

data <- ecospat.testData
caleval <- ecospat.caleval (data = ecospat.testData[53], xy = data[2:3], row.num = 1:nrow(data), 
nrep = 2, ratio = 0.7, disaggregate = 0.2, pseudoabs = 100, npres = 10, replace = FALSE)
caleval

Description

The function uses the output of ecospat.CCV.modeling to calculate a range of community evaluation metrics based on a selection of thresholding techniques both for the calibration data and independent evaluation data.

Usage

ecospat.CCV.communityEvaluation.bin(ccv.modeling.data,
                                    thresholds= c('MAX.KAPPA', 'MAX.ROC','PS_SDM'),
                                    community.metrics=c('SR.deviation','Sorensen'),
                                    parallel=FALSE,
                                    cpus=4,
                                    fix.threshold=0.5,
                                    MCE=5,
                                    MEM=NULL)

Arguments

Details

The function uses the probability output of the ecospat.CCV.modeling function and creates binary maps based on the selected thresholding methods. These binary maps are then used to calculate the selected community evaluation metrics both for the calibration and evaluation data of each modeling run.

Value

Author(s)

Daniel Scherrer <[email protected]>

References

Scherrer, D., D'Amen, M., Mateo, M.R.G., Fernandes, R.F. & Guisan , A. (2018) How to best threshold and validate stacked species assemblages? Community optimisation might hold the answer. Methods in Ecology and Evolution, in review

See Also

ecospat.CCV.modeling; ecospat.CCV.createDataSplitTable; ecospat.CCV.communityEvaluation.prob

Description

This function generates a number of community evaluation metrics directly based on the probability returned by the individual models. Instead of thresholding the predictions (ecospat.CCV.communityEvaluation.bin this function directly uses the probability and compares its outcome to null models or average expectations.)

Usage

ecospat.CCV.communityEvaluation.prob(ccv.modeling.data,
    community.metrics=c('SR.deviation','community.AUC','Max.Sorensen',
                         'Max.Jaccard','probabilistic.Sorensen',
                         'probabilistic.Jaccard'),
    parallel = FALSE, 
    cpus = 4)

Arguments

Value

Note

If the community evaluation metric 'SR.deviation' is selected the returned tables will have the following columns:

• SR.obs = observed species richness,

• SR.mean = the predicted species richness (based on the probabilities assuming poission binomial distribution),

• SR.dev = the deviation of observed and predicted species richness,

• SR.sd = the standard deviation of the predicted species richness (based on the probabilities assuming poission binomial distribution),

• SR.prob = the probability that the observed species richness falls within the predicted species richness (based on the probabilities assuming poission binomial distribution),

• SR.imp.05 = improvement of species richness prediction over null-model 0.5,

• SR.imp.average.SR = improvement of species richness prediction over null-model average.SR and

• SR.imp.prevalence = improvement of species richness prediction over null-model prevalence.

If the community evalation metric community.AUC is selected the returned tables will have the following colums:

• Community.AUC = The AUC of ROC of a given site (in this case the ROC plot is community sensitiviy [percentage species predicted corretly present] vs 1 - community specificity [percentage of species predicted correctly absent])

If the community evaluation metrics ('Max.Sorensen', 'Max.Jaccard') is selected the returned tables will have the follwing colums:

• Max.Jaccard = The maximum possible Jaccard similarity based on an optimal site specific threshold.

• Max.Sorensen = The maximum possible Sorensen similarity based on an optimal site specific threshold.

If the community evaluation metrics ('probabilistic.Sorensen', 'probabilistic.Jaccard') is selected the returned tables will have the follwing colums:

• probabilistic.Jaccard = The probabilistic Jaccard similarity index based on Scherrer et al. 2019, Methods in Ecology and Evolution

• probabilistic.Sorensen = The probabilistic Sorensen similarity index based on Scherrer et al. 2019, Methods in Ecology and Evolution

• composition.imp.05 = improvement of species compostion prediction over the null-model 0.5.

• composition.imp.average.SR = improvement of the species composition prediction over the null-model average.SR.

• composition.imp.prevalence = improvement of the species composition prediction over the null-model prevalence.

For detailed descriptions of the null models see Scherrer et al. 2019

Author(s)

Daniel Scherrer <[email protected]>

See Also

ecospat.CCV.modeling; ecospat.CCV.createDataSplitTable; ecospat.CCV.communityEvaluation.bin;

Description

Creates a DataSplitTable with calibration and evaluation data either for cross-validation or repeated split sampling at the community level (i.e., across all species).

Usage

ecospat.CCV.createDataSplitTable(NbRunEval, 
                                 DataSplit,
                                 validation.method,
                                 NbSites,
                                 sp.data=NULL,
                                 minNbPresences=NULL,
                                 minNbAbsences=NULL,
                                 maxNbTry=1000)

Arguments

Details

If a sp.data data.frame with species presences and absences is provided the function tries to create a DataSplitTable which ensures that the maximum possible number of species can be modelled (according to the specified minimum presences and absences.)

Value

Author(s)

Daniel Scherrer <[email protected]>

See Also

ecospat.CCV.modeling

Examples

#Creating a DataSplitTable for 200 sites, 25 runs with an 
#80/20 calibration/evaluation cross-validation

DataSplitTable <- ecospat.CCV.createDataSplitTable(NbSites = 200, 
                                                   NbRunEval=25, 
                                                   DataSplit=80, 
                                                   validation.method='cross-validation')
                                                   
#Loading species occurence data and remove empty communities
testData <- ecospat.testData[,c(24,34,43,45,48,53,55:58,60:63,65:66,68:71)]
sp.data <- testData[which(rowSums(testData)>0), sort(colnames(testData))]

#Creating a DataSplitTable based on species data directly
DataSplitTable <- ecospat.CCV.createDataSplitTable(NbRunEval = 20,
                                                   DataSplit = 70,
                                                   validation.method = "cross-validation",
                                                   NbSites = NULL,
                                                   sp.data = sp.data, 
                                                   minNbPresence = 15, 
                                                   minNbAbsences = 15, 
                                                   maxNbTry = 250)

Description

Creates probabilistic prediction for all species based on SDMs or ESMs and returns their evaluation metrics and variable importances.

Usage

ecospat.CCV.modeling(sp.data, 
                     env.data, 
                     xy,
                     DataSplitTable=NULL,
                     DataSplit = 70, 
                     NbRunEval = 25,
                     minNbPredictors =5,
                     validation.method = "cross-validation",
                     models.sdm = c("GLM","RF"), 
                     models.esm = "CTA", 
                     modeling.options.sdm = NULL, 
                     modeling.options.esm = NULL, 
                     ensemble.metric = "AUC", 
                     ESM = "YES",
                     parallel = FALSE, 
                     cpus = 4,
                     VarImport = 10,
                     modeling.id)

Arguments

Details

The basic idea of the community cross-validation (CCV) is to use the same data (sites) for the model calibration/evaluation of all species. This ensures that there is "independent" cross-validation/split-sample data available not only at the individual species level but also at the community level. This is key to allow an unbiased estimation of the ability to predict species assemblages (Scherrer et al. 2018). The output of the ecospat.CCV.modeling function can then be used to evaluate the species assemblage predictions with the ecospat.CCV.communityEvaluation.bin or ecospat.CCV.communityEvaluation.prob functions.

Value

Author(s)

Daniel Scherrer <[email protected]> with the updates from Flavien Collart and Olivier Broennimann

References

Scherrer, D., D'Amen, M., Mateo, M.R.G., Fernandes, R.F. & Guisan , A. (2018) How to best threshold and validate stacked species assemblages? Community optimisation might hold the answer. Methods in Ecology and Evolution, in review

See Also

ecospat.CCV.createDataSplitTable; ecospat.CCV.communityEvaluation.bin; ecospat.CCV.communityEvaluation.prob

Examples

#Loading species occurence data and remove empty communities
  data(ecospat.testData)
  testData <- ecospat.testData[,c(24,34,43,45,48,53,55:58)]
  sp.data <- testData[which(rowSums(testData)>2), sort(colnames(testData))]
  
  #Loading environmental data
  env.data <- ecospat.testData[which(rowSums(testData)>2),4:8]
  
  #Coordinates for all sites
  xy <- ecospat.testData[which(rowSums(testData)>2),2:3]
  
  #Running all the models for all species
  myCCV.Models <- ecospat.CCV.modeling(sp.data = sp.data,
                                       env.data = env.data,
                                       xy = xy,
                                       NbRunEval = 2,
                                       minNbPredictors = 10,
                                       VarImport = 3)
                                       
  #Calculating the probabilistic community metrics
  metrics = c('SR.deviation','community.AUC','probabilistic.Sorensen','Max.Sorensen')
  myCCV.Eval.prob <- ecospat.CCV.communityEvaluation.prob(
          ccv.modeling.data = myCCV.Models, 
          community.metrics = metrics)
          
  #Thresholding all the predictions and calculating the community evaluation metrics
  myCCV.communityEvaluation.bin <- ecospat.CCV.communityEvaluation.bin(
        ccv.modeling.data = myCCV.Models, 
        thresholds = c('MAX.KAPPA', 'MAX.ROC','PS_SDM'),
        community.metrics= c('SR.deviation','Sorensen'),
        parallel = FALSE,
        cpus = 4)

Description

Assess climate analogy between a projection extent (p) and a reference extent (ref, used in general as the background to calibrate SDMs)

Usage

ecospat.climan (ref, p)

Arguments

Value

Returns a vector. Values below 0 are novel conditions at the univariate level (similar to the MESS), values between 0 and 1 are analog and values above 1 are novel covariate condtions. For more information see Mesgeran et al. (2014)

Author(s)

Blaise Petitpierre [email protected]

References

Mesgaran, M.B., R.D. Cousens and B.L. Webber. 2014. Here be dragons: a tool for quantifying novelty due to covariate range and correlation change when projecting species distribution models. Diversity & Distributions, 20, 1147-1159.

Examples

x <- ecospat.testData[c(4:8)]
p<- x[1:90,] #A projection dataset.
ref<- x[91:300,] #A reference dataset
ecospat.climan(ref,p)

Description

Calculate an index of species co-occurrences.

Usage

ecospat.co_occurrences (data)

Arguments

Details

Computes an index of co-occurrences ranging from 0 (never co-occurring) to 1 (always co-occuring).

Value

The species co-occurrence matrix and box-plot of the co-occurrence indices

Author(s)

Loic Pellissier [email protected]

References

Pellissier, L., K.A. Brathen, J. Pottier, C.F. Randin, P. Vittoz, A. Dubuis, N.G. Yoccoz, T. Alm, N.E. Zimmermann and A. Guisan. 2010. Species distribution models reveal apparent competitive and facilitative effects of a dominant species on the distribution of tundra plants. Ecography, 33, 1004-1014.

Guisan, A. and N. Zimmermann. 2000. Predictive habitat distribution models in ecology. Ecological Modelling, 135:147-186

Examples

matrix <- ecospat.testData[c(9:16,54:57)]
ecospat.co_occurrences (data=matrix)

Description

Calculates Cohen's kappa and variance estimates, within a 95 percent confidence interval.

Usage

ecospat.cohen.kappa(xtab)

Arguments

Details

The argument xtab is a contingency table. xtab <- table(Pred >= th, Sp.occ)

Value

A list with elements 'kap', 'vark', 'totn' and 'ci' is returned. 'kap' is the cohen's kappa, 'vark' is the variance estimate within a 95 percent confidence interval, 'totn' is the number of plots and 'ci' is the confidence interval.

Author(s)

Christophe Randin [email protected] with contributions of Niklaus. E. Zimmermann [email protected] and Valeria Di Cola [email protected]

References

Bishop, Y.M.M., S.E. Fienberg and P.W. Holland. 1975. Discrete multivariate analysis: Theory and Practice. Cambridge, MA: MIT Press. pp. 395-397.

Pearce, J. and S. Ferrier. 2000. Evaluating the predictive performance of habitat models developed using logistic regression. Ecol. Model., 133, 225-245.

See Also

ecospat.meva.table, ecospat.max.tss, ecospat.plot.tss, ecospat.plot.kappa, ecospat.max.kappa

Examples

Pred <- ecospat.testData$glm_Agrostis_capillaris
Sp.occ <- ecospat.testData$Agrostis_capillaris
th <- 0.39 # threshold
xtab <- table(Pred >= th, Sp.occ)

ecospat.cohen.kappa(xtab)

Description

Calculate several indices of accuracy of community predictions.

Usage

ecospat.CommunityEval (eval, pred, proba, ntir, verbose = FALSE)

Arguments

Details

This function calculates several indices of accuracy of community predictions based on stacked predictions of species ditribution models. In case proba is set to FALSE the function returns one value per index and per site. In case proba is set to TRUE the function generates presences-absences based on the predicted probabilities and returns one value per index, per site and per trial.

Value

A list of evaluation metrics calculated for each site (+ each trial if proba is set to TRUE):

deviance.rich.pred: the deviation of the predicted species richness to the observed

overprediction: the proportion of species predicted as present but not observed among the species predicted as present

underprediction: the proportion of species predicted as absent but observed among the species observed as present

prediction.success: the proportion of species correctly predicted as present or absent

sensitivity: the proportion of species correctly predicted as present among the species observed as present

specificity : the proportion of species correctly predicted as absent among the species observed as absent

kappa: the proportion of specific agreement

TSS: sensitivity+specificity-1

similarity: the similarity of community composition between the observation and the prediction. The calculation is based on the Sorenses index.

Jaccard: this index is a widely used metric of community similarity.

Author(s)

Julien Pottier [email protected]

with contribution of Daniel Scherrer [email protected], Anne Dubuis [email protected] and Manuela D'Amen [email protected]

References

Pottier, J., A. Dubuis, L. Pellissier, L. Maiorano, L. Rossier, C.F. Randin, P. Vittoz and A. Guisan. 2013. The accuracy of plant assemblage prediction from species distribution models varies along environmental gradients. Global Ecology and Biogeography, 22, 52-63.

Examples

data(ecospat.testData)
eval <- ecospat.testData[c(53,62,58,70,61,66,65,71,69,43,63,56,68,57,55,60,54,67,59,64)]
pred <- ecospat.testData[c(73:92)]

ecospat.CommunityEval (eval, pred, proba=TRUE, ntir=10)

Description

Co-occurrence Analysis & Environmentally Constrained Null Models. The function tests for non-random patterns of species co-occurrence in a presence-absence matrix. It calculates the C-score index for the whole community and for each species pair. An environmental constraint is applied during the generation of the null communities.

Usage

ecospat.cons_Cscore(presence,pred,nperm,outpath,verbose = FALSE)

Arguments

Details

An environmentally constrained approach to null models will provide a more robust evaluation of species associations by facilitating the distinction between mutually exclusive processes that may shape species distributions and community assembly. The format required for input databases: a plots (rows) x species (columns) matrix. Input matrices should have column names (species names) and row names (sampling plots). NOTE: a SES that is greater than 2 or less than -2 is statistically significant with a tail probability of less than 0.05 (Gotelli & McCabe 2002 - Ecology)

Value

Returns the C-score index for the observed community (ObsCscoreTot), the mean of C-score for the simulated communities (SimCscoreTot), p.value (PValTot) and standardized effect size (SES.Tot). It also saves a table in the specified path where the same metrics are calculated for each species pair (only the table with species pairs with significant p.values is saved in this version).

Author(s)

Anne Dubuis [email protected] and Manuela D'Amen [email protected]

References

Gotelli, N.J. and D.J. McCabe. 2002. Species co-occurrence: a meta-analysis of JM Diamond's assembly rules model. Ecology, 83, 2091-2096.

Peres-Neto, P.R., J.D. Olden and D.A. Jackson. 2001. Environmentally constrained null models: site suitability as occupancy criterion. Oikos, 93, 110-120.

Examples

presence <- ecospat.testData[c(53,62,58,70,61,66,65,71,69,43,63,56,68,57,55,60,54,67,59,64)]
pred <- ecospat.testData[c(73:92)]
nperm <- 10000
outpath <- getwd()
cons_Cscore<-ecospat.cons_Cscore(presence, pred, nperm, outpath)

Description

A scatter plot of matrices, with bivariate scatter plots below the diagonal, histograms on the diagonal, and the Pearson correlation above the diagonal. Useful for descriptive statistics of small data sets (better with less than 10 variables).

Usage

ecospat.cor.plot(data)

Arguments

Details

Adapted from the pairs help page. Uses panel.cor, and panel.hist, all taken from the help pages for pairs. It is a simplifies version of pairs.panels() function of the package psych.

Value

A scatter plot matrix is drawn in the graphic window. The lower off diagonal draws scatter plots, the diagonal histograms, the upper off diagonal reports the Pearson correlation.

Author(s)

Adjusted by L. Mathys, 2006, modified by N.E. Zimmermann

Examples

data <- ecospat.testData[,4:8]
ecospat.cor.plot(data)

Description

The function tests for nonrandom patterns of species co-occurrence in a presence-absence matrix. It calculates the C-score index for the whole community and for each species pair. Null communities have column sum fixed.

Usage

ecospat.Cscore (data, nperm, outpath, verbose = FALSE)

Arguments

Details

This function allows to apply a pairwise null model analysis (Gotelli and Ulrich 2010) to a presence-absence community matrix to determine which species associations are significant across the study area. The strength of associations is quantified by the C-score index (Stone and Roberts 1990) and a 'fixed-equiprobable' null model algorithm is applied. The format required for input databases: a plots (rows) x species (columns) matrix. Input matrices should have column names (species names) and row names (sampling plots). NOTE: a SES that is greater than 2 or less than -2 is statistically significant with a tail probability of less than 0.05 (Gotelli & McCabe 2002).

Value

The function returns the C-score index for the observed community (ObsCscoreTot), p.value (PValTot) and standardized effect size (SES.Tot). It saves also a table in the working directory where the same metrics are calculated for each species pair (only the table with species pairs with significant p-values is saved in this version)

Author(s)

Christophe Randin [email protected] and Manuela D'Amen <[email protected]>

References

Gotelli, N.J. and D.J. McCabe. 2002. Species co-occurrence: a meta-analysis of JM Diamond's assembly rules model. Ecology, 83, 2091-2096.

Gotelli, N.J. and W. Ulrich. 2010. The empirical Bayes approach as a tool to identify non-random species associations. Oecologia, 162, 463-477

Stone, L. and A. Roberts, A. 1990. The checkerboard score and species distributions. Oecologia, 85, 74-79

See Also

ecospat.co_occurrences and ecospat.cons_Cscore

Examples

## Not run: 
data<- ecospat.testData[c(53,62,58,70,61,66,65,71,69,43,63,56,68,57,55,60,54,67,59,64)]
nperm <- 10000
outpath <- getwd()
Cscore<-ecospat.Cscore(data, nperm, outpath)


## End(Not run)

Description

K-fold and leave-one-out cross validation for GBM.

Usage

ecospat.cv.gbm (gbm.obj, data.cv, K=10, cv.lim=10, jack.knife=FALSE, verbose = FALSE)

Arguments

Details

This function takes a calibrated GBM object with a binomial error distribution and returns predictions from a stratified 10-fold cross-validation or a leave-one-out / jack-knived cross-validation. Stratified means that the original prevalence of the presences and absences in the full dataset is conserved in each fold.

Value

Returns a dataframe with the observations (obs) and the corresponding predictions by cross-validation or jacknife.

Author(s)

Christophe Randin [email protected] and Antoine Guisan [email protected]

References

Randin, C.F., T. Dirnbock, S. Dullinger, N.E. Zimmermann, M. Zappa and A. Guisan. 2006. Are niche-based species distribution models transferable in space? Journal of Biogeography, 33, 1689-1703.

Pearman, P.B., C.F. Randin, O. Broennimann, P. Vittoz, W.O. van der Knaap, R. Engler, G. Le Lay, N.E. Zimmermann and A. Guisan. 2008. Prediction of plant species distributions across six millennia. Ecology Letters, 11, 357-369.

Examples

library(gbm)
data('ecospat.testData')

# data for Soldanella alpina
data.Solalp<- ecospat.testData[c("Soldanella_alpina","ddeg","mind","srad","slp","topo")] 

# gbm model for Soldanella alpina
gbm.Solalp <- gbm::gbm(Soldanella_alpina ~ ., data = data.Solalp,
                  distribution = "bernoulli", cv.folds = 10, n.cores=2)

# cross-validated predictions
gbm.pred <- ecospat.cv.gbm (gbm.obj= gbm.Solalp,data.Solalp, 
                            K=10, cv.lim=10, jack.knife=FALSE)

Description

K-fold and leave-one-out cross validation for GLM.

Usage

ecospat.cv.glm (glm.obj, K=10, cv.lim=10, jack.knife = FALSE, verbose = FALSE)

Arguments

Details

This function takes a calibrated GLM object with a binomial error distribution and returns predictions from a stratified 10-fold cross-validation or a leave-one-out / jack-knived cross-validation. Stratified means that the original prevalence of the presences and absences in the full dataset is conserved in each fold.

Value

Returns a dataframe with the observations (obs) and the corresponding predictions by cross-validation or jacknife.

Author(s)

Christophe Randin [email protected] and Antoine Guisan [email protected]

References

Randin, C.F., T. Dirnbock, S. Dullinger, N.E. Zimmermann, M. Zappa and A. Guisan. 2006. Are niche-based species distribution models transferable in space? Journal of Biogeography, 33, 1689-1703.

Pearman, P.B., C.F. Randin, O. Broennimann, P. Vittoz, W.O. van der Knaap, R. Engler, G. Le Lay, N.E. Zimmermann and A. Guisan. 2008. Prediction of plant species distributions across six millennia. Ecology Letters, 11, 357-369.

Examples

if(require("rms",quietly=TRUE)){
  data('ecospat.testData')

  # data for Soldanella alpina
  data.Solalp<- ecospat.testData[c("Soldanella_alpina","ddeg","mind","srad","slp","topo")] 

  # glm model for Soldanella alpina

  glm.Solalp <- glm(Soldanella_alpina ~ pol(ddeg,2) + pol(mind,2) + pol(srad,2) + pol(slp,2) 
      + pol(topo,2), data = data.Solalp, family = binomial)

  # cross-validated predictions
  glm.pred <- ecospat.cv.glm (glm.obj=glm.Solalp , K=10, cv.lim=10, jack.knife=FALSE)
}

Description

K-fold and leave-one-out cross validation for Maxent.

Usage

ecospat.cv.me(data.cv.me, name.sp, names.pred, K=10, cv.lim=10, 
              jack.knife=FALSE, verbose=FALSE)

Arguments

Details

This function takes a calibrated Maxent object with a binomial error distribution and returns predictions from a stratified 10-fold cross-validation or a leave-one-out / jack-knived cross-validation. Stratified means that the original prevalence of the presences and absences in the full dataset is conserved in each fold.

Value

Returns a dataframe with the observations (obs) and the corresponding predictions by cross-validation or jacknife.

Author(s)

Christophe Randin [email protected] and Antoine Guisan [email protected]

References

Randin, C.F., T. Dirnbock, S. Dullinger, N.E. Zimmermann, M. Zappa and A. Guisan. 2006. Are niche-based species distribution models transferable in space? Journal of Biogeography, 33, 1689-1703.

Pearman, P.B., C.F. Randin, O. Broennimann, P. Vittoz, W.O. van der Knaap, R. Engler, G. Le Lay, N.E. Zimmermann and A. Guisan. 2008. Prediction of plant species distributions across six millennia. Ecology Letters, 11, 357-369.

Examples

data('ecospat.testData')

# data for Soldanella alpina
data.Solalp<- ecospat.testData[c("Soldanella_alpina","ddeg","mind","srad","slp","topo")] 

# maxent modelling and cross-validated predictions

# path to maxent.jar file
path<- paste0(system.file(package="dismo"), "/java/maxent.jar")

if (file.exists(path) & require(rJava)) {
  me.pred <- ecospat.cv.me(data.Solalp, names(data.Solalp)[1],
             names(data.Solalp)[-1], K = 10, cv.lim = 10, jack.knife = FALSE)
  }

Description

K-fold and leave-one-out cross validation for randomForest.

Usage

ecospat.cv.rf (rf.obj, data.cv, K=10, cv.lim=10, jack.knife=FALSE, verbose = FALSE)

Arguments

Details

This function takes a calibrated randomForest object with a binomial error distribution and returns predictions from a stratified 10-fold cross-validation or a leave-one-out / jack-knived cross-validation. Stratified means that the original prevalence of the presences and absences in the full dataset is conserved in each fold.

Value

Returns a dataframe with the observations (obs) and the corresponding predictions by cross-validation or jacknife.

Author(s)

Christophe Randin [email protected] and Antoine Guisan [email protected]

References

Randin, C.F., T. Dirnbock, S. Dullinger, N.E. Zimmermann, M. Zappa and A. Guisan. 2006. Are niche-based species distribution models transferable in space? Journal of Biogeography, 33, 1689-1703.

Pearman, P.B., C.F. Randin, O. Broennimann, P. Vittoz, W.O. van der Knaap, R. Engler, G. Le Lay, N.E. Zimmermann and A. Guisan. 2008. Prediction of plant species distributions across six millennia. Ecology Letters, 11, 357-369.

Examples

data('ecospat.testData')

# data for Soldanella alpina
data.Solalp<- ecospat.testData[c("Soldanella_alpina","ddeg","mind","srad","slp","topo")] 

library(randomForest)
rf.Solalp <- randomForest(x = data.Solalp[,-1], y = as.factor(data.Solalp[,1]))
rf.pred <- ecospat.cv.rf(rf.Solalp, data.Solalp, K = 10, cv.lim = 10, 
                         jack.knife = FALSE, verbose = FALSE)

Description

Calculate the mean (or weighted mean) of several predictions.

Usage

ecospat.Epred (x, w=rep(1,ncol(x)), th=0)

Arguments

Details

The Weighted Average consensus method utilizes pre-evaluation of the predictive performance of the single-models. In this approach, half (i.e. four) of the eight single-models with highest accuracy are selected first, and then a WA is calculated based on the pre-evaluated AUC of the single-models

Value

A weighted mean binary transformation of the models.

Author(s)

Blaise Petitpierre [email protected]

References

Boyce, M.S., P.R. Vernier, S.E. Nielsen and F.K.A. Schmiegelow. 2002. Evaluating resource selection functions. Ecol. Model., 157, 281-300.

Marmion, M., M. Parviainen, M. Luoto, R.K. Heikkinen andW. Thuiller. 2009. Evaluation of consensus methods in predictive species distribution modelling. Diversity and Distributions, 15, 59-69.

Examples

x <- ecospat.testData[c(92,96)]
mean <- ecospat.Epred (x, w=rep(1,ncol(x)), th=0.5)

Description

This function evaluates the Ensemble of Small Models by pooling the different runs of the cross validation as in Collart et al. (2021).

Usage

ecospat.ESM.EnsembleEvaluation(ESM.modeling.output,
                               ESM.EnsembleModeling.output,
                               metrics = c("SomersD","AUC","MaxTSS","MaxKappa","Boyce"), 
                               EachSmallModels = FALSE)

Arguments

Details

Because a minimum sample size is needed to evaluate models (see Collart & Guisan, 2023), this function uses the approach from Collart et al.(2021), which consists to pool the suitability values of the hold-out data (evaluation dataset) across replicates. As the same data point (presence or absence or background point) is presumably sampled in several replicates, the suitability values for each data point is consequently averaged across replicates where they were sampled. This procedure generates a series of independent suitability values with a size approximately equal (as some data points may not have been sampled by chance in any of the n replicates) to that of the number of data point.

Value

a list containing:

Author(s)

Flavien Collart [email protected]

with contributions of Olivier Broennimann [email protected]

References

Collart, F., & Guisan, A. (2023). Small to train, small to test: Dealing with low sample size in model evaluation. Ecological Informatics. 75, 102106. doi:10.1016/j.ecoinf.2023.102106

Collart, F., Hedenas, L., Broennimann, O., Guisan, A. and Vanderpoorten, A. 2021. Intraspecific differentiation: Implications for niche and distribution modelling. Journal of Biogeography. 48, 415-426. doi:10.1111/jbi.14009

See Also

ecospat.ESM.EnsembleModeling

Description

This function evaluates and averages simple bivariate models by weighted means to Ensemble Small Models as in Lomba et al. 2010 and Breiner et al. 2015.

Usage

ecospat.ESM.EnsembleModeling( ESM.modeling.output, 
                                  weighting.score, 
                                  threshold=NULL, 
                                  models)

Arguments

Details

The basic idea of ensemble of small models (ESMs) is to model a species distribution based on small, simple models, for example all possible bivariate models (i.e. models that contain only two predictors at a time out of a larger set of predictors), and then combine all possible bivariate models into an ensemble (Lomba et al. 2010; Breiner et al. 2015).

The ESM set of functions could be used to build ESMs using simple bivariate models which are averaged using weights based on model performances (e.g. AUC) according to Breiner et al. (2015). They provide full functionality of the approach described in Breiner et al. (2015).

Value

species: species name ESM.fit: data.frame of the predicted values for the data used to build the models. ESM.evaluations: data.frame with evaluations scores for the ESMs weights: weighting scores used to weight the bivariate models to build the single ESM weights.EF: weighting scores used to weight the single ESM to build the ensemble of ESMs from different modelling techniques (only available if >1 modelling techniques were selected). failed: bivariate models which failed because they could not be calibrated.

A "BIOMOD.ensemble.models.out" object. This object will be later given to ecospat.ESM.EnsembleProjection if you want to make some projections of this ensemble-models.

Author(s)

Frank Breiner [email protected]

with contributions of Olivier Broennimann and Flavien Collart [email protected]

References

Lomba, A., L. Pellissier, C.F. Randin, J. Vicente, F. Moreira, J. Honrado and A. Guisan. 2010. Overcoming the rare species modelling paradox: A novel hierarchical framework applied to an Iberian endemic plant. Biological Conservation, 143,2647-2657.

Breiner F.T., A. Guisan, A. Bergamini and M.P. Nobis. 2015. Overcoming limitations of modelling rare species by using ensembles of small models. Methods in Ecology and Evolution, 6,1210-1218.

Breiner F.T., Nobis M.P., Bergamini A., Guisan A. 2018. Optimizing ensembles of small models for predicting the distribution of species with few occurrences. Methods in Ecology and Evolution. doi:10.1111/2041-210X.12957

See Also

ecospat.ESM.Modeling

Description

This function projects calibrated ESMs into new space or time.

Usage

ecospat.ESM.EnsembleProjection( ESM.prediction.output, 
                                    ESM.EnsembleModeling.output,
                                    chosen.models = 'all')

Arguments

Details

The basic idea of ensemble of small models (ESMs) is to model a species distribution based on small, simple models, for example all possible bivariate models (i.e. models that contain only two predictors at a time out of a larger set of predictors), and then combine all possible bivariate models into an ensemble (Lomba et al. 2010; Breiner et al. 2015).

The ESM set of functions could be used to build ESMs using simple bivariate models which are averaged using weights based on model performances (e.g. AUC) according to Breiner et al. (2015). They provide full functionality of the approach described in Breiner et al. (2015). For projections only the full models (100

For further details please refer to BIOMOD_EnsembleForecasting.

Value

Returns the projections of ESMs for the selected single models and their ensemble (data frame or SpatRaster). ESM.projections ‘projection files’ are saved on the hard drive projection folder. This files are either an array or a SpatRaster depending the original projections data type. Load these created files to plot and work with them.

Author(s)

Frank Breiner with the contributions of Flavien Collart [email protected]

References

Lomba, A., L. Pellissier, C.F. Randin, J. Vicente, F. Moreira, J. Honrado and A. Guisan. 2010. Overcoming the rare species modelling paradox: A novel hierarchical framework applied to an Iberian endemic plant. Biological Conservation, 143,2647-2657.

Breiner F.T., A. Guisan, A. Bergamini and M.P. Nobis. 2015. Overcoming limitations of modelling rare species by using ensembles of small models. Methods in Ecology and Evolution, 6,1210-1218.

Breiner F.T., Nobis M.P., Bergamini A., Guisan A. 2018. Optimizing ensembles of small models for predicting the distribution of species with few occurrences. Methods in Ecology and Evolution. doi:10.1111/2041-210X.12957

See Also

ecospat.ESM.EnsembleModeling

Description

This function calibrates simple bivariate models as in Lomba et al. 2010 and Breiner et al. 2015.

Usage

ecospat.ESM.Modeling( data, 
                          NbRunEval, 
                          DataSplit, 
                          DataSplitTable, 
                          Prevalence,
                          weighting.score, 
                          models, 
                          tune,
                          modeling.id, 
                          models.options, 
                          which.biva, 
                          parallel, 
                          cleanup,
                          Yweights)

Arguments

Details

The basic idea of ensemble of small models (ESMs) is to model a species distribution based on small, simple models, for example all possible bivariate models (i.e. models that contain only two predictors at a time out of a larger set of predictors), and then combine all possible bivariate models into an ensemble (Lomba et al. 2010; Breiner et al. 2015).

The ESM set of functions could be used to build ESMs using simple bivariate models which are averaged using weights based on model performances (e.g. AUC) according to Breiner et al. (2015). They provide full functionality of the approach described in Breiner et al. (2015).

The argument which.biva allows to split model runs, e.g. if which.biva is 1:3, only the three first bivariate variable combinations will be modeled. This allows to run different biva splits on different computers. However, it is better not to use this option if all models are run on a single computer. Default: running all biva models. NOTE: Make sure to give each of your biva runs a unique modeling.id. Please avoid space characters in your working directory path if you are using MAXENT because this can cause an error.

Value

A BIOMOD.models.out object (same as in biomod2) See "BIOMOD.models.out" for details.

Author(s)

Frank Breiner [email protected] and Mirko Di Febbraro [email protected] with contributions of Olivier Broennimann [email protected] and Flavien Collart

References

Lomba, A., L. Pellissier, C.F. Randin, J. Vicente, F. Moreira, J. Honrado and A. Guisan. 2010. Overcoming the rare species modelling paradox: A novel hierarchical framework applied to an Iberian endemic plant. Biological Conservation, 143,2647-2657.

Breiner F.T., A. Guisan, A. Bergamini and M.P. Nobis. 2015. Overcoming limitations of modelling rare species by using ensembles of small models. Methods in Ecology and Evolution, 6,1210-1218.

Breiner F.T., Nobis M.P., Bergamini A., Guisan A. 2018. Optimizing ensembles of small models for predicting the distribution of species with few occurrences. Methods in Ecology and Evolution. doi:10.1111/2041-210X.12957

See Also

ecospat.ESM.Projection, ecospat.ESM.EnsembleModeling, ecospat.ESM.EnsembleProjection, ecospat.ESM.EnsembleEvaluation, ecospat.ESM.threshold,ecospat.ESM.VarContrib, ecospat.ESM.responsePlot

BIOMOD_FormatingData, bm_ModelingOptions, BIOMOD_Modeling,BIOMOD_Projection

Examples

library(biomod2)

# Loading test data
data(ecospat.testNiche.inv)
inv <- ecospat.testNiche.inv

# species occurrences
xy <- inv[,1:2]
sp_occ <- inv[11]

# env data
current <- inv[3:8]

### Formating the data with the BIOMOD_FormatingData() function from the package biomod2
sp <- 1
myBiomodData <- biomod2::BIOMOD_FormatingData( resp.var = as.numeric(sp_occ[,sp]),
                                      expl.var = current,
                                      resp.xy = xy,
                                      resp.name = colnames(sp_occ)[sp])

### Calibration of simple bivariate models
my.ESM <- ecospat.ESM.Modeling( data=myBiomodData,
                                models=c('GLM'),
                                NbRunEval=2,
                                DataSplit=70,
                                weighting.score=c("AUC"),
                                parallel=FALSE)  

### Ensemble models
my.ESM_EF <- ecospat.ESM.EnsembleModeling(my.ESM,weighting.score=c("SomersD"),threshold=0)

### thresholds to produce binary maps
my.ESM_thresholds <- ecospat.ESM.threshold(my.ESM_EF)

### Evaluation of bivariate and ensemble models based on standard cross-validation
my.ESM_EF$ESM.evaluations
my.ESM_thresholds

### Evaluation of the ensemble models based on the pooling procedure 
my.ESM_evaluations <- ecospat.ESM.EnsembleEvaluation(ESM.modeling.output= my.ESM,
                                                     ESM.EnsembleModeling.output = my.ESM_EF,
                                                     metrics= c("AUC","MaxTSS"),
                                                     EachSmallModels = FALSE)
my.ESM_evaluations$ESM.evaluations

### Projection of simple bivariate models into new space 
my.ESM_proj_current<-ecospat.ESM.Projection(ESM.modeling.output=my.ESM,
                                            new.env=current)
### Projection of calibrated ESMs into new space 
my.ESM_EFproj_current <- ecospat.ESM.EnsembleProjection(ESM.prediction.output=my.ESM_proj_current,
                                                        ESM.EnsembleModeling.output=my.ESM_EF)
### Binary Projection based on max TSS of calibrated ESMs into new space                                                
my.ESM_EFproj_current_binary <- (my.ESM_EFproj_current > (my.ESM_thresholds$TSS.th*1000))*1

## get the variable contributions of ESMs
ecospat.ESM.VarContrib(my.ESM,my.ESM_EF)                                                      

## get the response plots of ESMs
my.ESM_responsePlot<-ecospat.ESM.responsePlot(my.ESM_EF,my.ESM,fixed.var.metric = 'mean')

Description

This function projects simple bivariate models on new.env

Usage

ecospat.ESM.Projection(ESM.modeling.output, 
                           new.env,
                           name.env,
                           models,
                           parallel,
                           cleanup)

Arguments

Details

The basic idea of ensemble of small models (ESMs) is to model a species distribution based on small, simple models, for example all possible bivariate models (i.e. models that contain only two predictors at a time out of a larger set of predictors), and then combine all possible bivariate models into an ensemble (Lomba et al. 2010; Breiner et al. 2015).

The ESM set of functions could be used to build ESMs using simple bivariate models which are averaged using weights based on model performances (e.g. AUC) accoring to Breiner et al (2015). They provide full functionality of the approach described in Breiner et al. (2015).

The name of new.env must be a regular expression (see ?regex)

Value

Returns the projections for all selected models (same as in biomod2) See "BIOMOD.projection.out" for details.

Author(s)

Frank Breiner [email protected]

with contributions of Olivier Broennimann and Flavien Collart [email protected]

References

Lomba, A., L. Pellissier, C.F. Randin, J. Vicente, F. Moreira, J. Honrado and A. Guisan. 2010. Overcoming the rare species modelling paradox: A novel hierarchical framework applied to an Iberian endemic plant. Biological Conservation, 143,2647-2657.

Breiner F.T., A. Guisan, A. Bergamini and M.P. Nobis. 2015. Overcoming limitations of modelling rare species by using ensembles of small models. Methods in Ecology and Evolution, 6,1210-1218.

Breiner F.T., Nobis M.P., Bergamini A., Guisan A. 2018. Optimizing ensembles of small models for predicting the distribution of species with few occurrences. Methods in Ecology and Evolution. doi:10.1111/2041-210X.12957

See Also

ecospat.ESM.Modeling

Description

This function creates response plots (evaluation strips) for Ensmebles of Small Models (ESMs).

Usage

ecospat.ESM.responsePlot( ESM.EnsembleModeling.output,
                              ESM.modeling.output,
                              fixed.var.metric = 'median')

Arguments

Details

This function plots the response curves of a model for each variable, while keeping the remianing variables constant. This is an adaptation of the Evaluation Strip method proposed by Elith et al.(2005)

Value

A plot of the response curves is produced (red line Ensemble, grey lines single algorithms) and a list with the output is provided.

Author(s)

Frank Breiner [email protected]

References

Elith, J., Ferrier, S., Huettmann, FALSE. & Leathwick, J. R. 2005 The evaluation strip: A new and robust method for plotting predicted responses from species distribution models. Ecological Modelling 186, 280-289.

See Also

ecospat.ESM.Modeling

Description

This function evaluates the full model which is used for projections and provides thresholds to produce binary maps.

Usage

ecospat.ESM.threshold( ESM.EnsembleModeling.output, 
                           PEplot = FALSE)

Arguments

Details

This function provides evaluation scores of the full model (no split sampling) and thresholds which can be used to convert suitability maps into binary maps. Various thresholds are provided: TSS (where sensitivity and specificity are maximised), MPA 1.0 (where all presences are prdicted positive), MPA 0.95 (where 95% of all presences are predicted positive), MPA 0.90 (where 90% of all presences are predicted positive), Boyce.th.min (the lowest suitability value where the predicted/expected ratio is >1) and Boyce.th.max (the highest suitability value where the predicted/expected ratio is =1).

Value

A data.frame with evluation scores and thresholds.

Author(s)

Frank Breiner [email protected]

References

Hirzel, Alexandre H., et al. Evaluating the ability of habitat suitability models to predict species presences. Ecological modelling, 199.2 (2006): 142-152.

Engler, Robin, Antoine Guisan, and Luca Rechsteiner. An improved approach for predicting the distribution of rare and endangered species from occurrence and pseudo-absence data. Journal of applied ecology, 41.2 (2004): 263-274.

Fielding, Alan H., and John F. Bell. A review of methods for the assessment of prediction errors in conservation presence/absence models." Environmental conservation, 24.1 (1997): 38-49.

See Also

ecospat.ESM.Modeling

Description

calculates the variable contribution of each variable and method in an ESM model

Usage

ecospat.ESM.VarContrib(ESM.modeling.output,
                           ESM_EF.output)

Arguments

Details

Calculates the ratio between sum of weights of bivariate models where a focal variable was used and sum of weights of bivariate models where the focal variable was not used. The ratio is corrected for the number of models with or without the focal variable. This ratio gives an indication on the proportional contribution of the variable in the final ensemble model. A value of higher than 1 indicate that the focal variable has a higher contribution than average. In the case of multiple methods (e.g., GLM, GAM...), the contributions are counted per method. For ensemble model, the contributions are then weighted means (based on the weighting score as chosen in ecospat.ESM.EnsembleModeling()) of single methods

Value

Returns a dataframe with contribution values (i.e. proportional contribution) by variable and model

Author(s)

Olivier Broennimann <[email protected]> with contributions of Heidi Mod [email protected] and Daniel Scherrer [email protected]

See Also

ecospat.ESM.Modeling

Description

Create a grid with occurrence densities along one or two gridded environmental gradients.

Usage

ecospat.grid.clim.dyn (glob, glob1, sp, R, th.sp, th.env, geomask, 
  kernel.method, extend.extent)

Arguments

Details

Using the scores of an ordination (or SDM prediction), create a grid z of RxR pixels (or a vector of R pixels when using scores of dimension 1 or SDM predictions) with occurrence densities. Only scores of one, or two dimensions can be used. th.sp is the quantile of the distribution of species density at occurrence sites. For example, if th.sp is set to 0.05, the species niche is drawn by including 95 percent of the species occurrences, removing the more marginal populations. Similarly, th.env is the quantile of the distribution of the environmental density at all sites of the study area. If th.env is set to 0.05, the delineation of the study area in the environmental space includes 95 percent of the study area, removing the more marginal sites of the study area. By default, these thresholds are set to 0 but can be modified, depending on the importance of some marginal sites in the delineation of the species niche and/or the study area in the environmnental space. It is recommended to check if the shape of the delineated niche and study area corresponds to the shape of the plot of the PCA scores (or any other ordination techniques used to set the environmental space). Visualisation of the gridded environmental space can be done through the functions ecospat.plot.niche or ecospat.plot.niche.dyn If you encounter a problem during your analyses, please first read the FAQ section of "Niche overlap" in https://www.unil.ch/ecospat/home/menuguid/ecospat-resources/tools.html The argument geomask can be a SpatialPolygon or a SpatRaster object. Note that the CRS should be the same as the one used for the points.

The parameter extend.extent allows modifying the extent of the grid. By default, the window covers from the minimum to the maximum value of the environmental values present in the study area. The vector extend.extent indicates how much you want to shift the x-minimal, x-maximal, y-minimal and y-maximal values respectively.

Value

A grid z of RxR pixels (or a vector of R pixels) with z.uncor being the density of occurrence of the species, and z.cor the occupancy of the environment by the species (density of occurrences divided by the desinty of environment in the study area.

Author(s)

Olivier Broennimann [email protected] and Blaise Petitpierre [email protected]

References

Broennimann, O., M.C. Fitzpatrick, P.B. Pearman, B. Petitpierre, L. Pellissier, N.G. Yoccoz, W. Thuiller, M.J. Fortin, C. Randin, N.E. Zimmermann, C.H. Graham and A. Guisan. 2012. Measuring ecological niche overlap from occurrence and spatial environmental data. Global Ecology and Biogeography, 21:481-497.

Petitpierre, B., C. Kueffer, O. Broennimann, C. Randin, C. Daehler and A. Guisan. 2012. Climatic niche shifts are rare among terrestrial plant invaders. Science, 335:1344-1348.

See Also

ecospat.plot.niche.dyn

Examples

library(ade4)
library(terra)

data(ecospat.testNiche)
data(ecospat.testData)

spp <- ecospat.testNiche
clim <- ecospat.testData[2:8]

occ.sp_test <- na.exclude(ecospat.sample.envar(
  dfsp = spp, colspxy = 2:3, colspkept = 1:3, dfvar = clim,
  colvarxy = 1:2, colvar = "all", resolution = 25
))

occ.sp <- cbind(occ.sp_test, spp[, 4]) # add species names

# list of species
sp.list <- levels(occ.sp[, 1])
sp.nbocc <- c()

for (i in 1:length(sp.list)) {
  sp.nbocc <- c(sp.nbocc, length(which(occ.sp[, 1] == sp.list[i])))
}
# calculate the nb of occurences per species

sp.list <- sp.list[sp.nbocc > 4] # remove species with less than 5 occurences
nb.sp <- length(sp.list) # nb of species
ls()
# selection of variables to include in the analyses
# try with all and then try only worldclim Variables
Xvar <- c(3:7)
nvar <- length(Xvar)

# number of interation for the tests of equivalency and similarity
iterations <- 100
# resolution of the gridding of the climate space
R <- 100
#################################### PCA-ENVIRONMENT ##################################
data <- rbind(occ.sp[, Xvar + 1], clim[, Xvar])
w <- c(rep(0, nrow(occ.sp)), rep(1, nrow(clim)))
library(ade4)
pca.cal <- ade4::dudi.pca(data, row.w = w, center = TRUE, scale = TRUE, scannf = FALSE, nf = 2)

####### selection of species ######
sp.list
sp.combn <- combn(1:2, 2)

for (i in 1:ncol(sp.combn)) {
  row.sp1 <- which(occ.sp[, 1] == sp.list[sp.combn[1, i]]) # rows in data corresponding to sp1
  row.sp2 <- which(occ.sp[, 1] == sp.list[sp.combn[2, i]]) # rows in data corresponding to sp2
  name.sp1 <- sp.list[sp.combn[1, i]]
  name.sp2 <- sp.list[sp.combn[2, i]]
  # predict the scores on the axes
  scores.clim <- pca.cal$li[(nrow(occ.sp) + 1):nrow(data), ] # scores for global climate
  scores.sp1 <- pca.cal$li[row.sp1, ] # scores for sp1
  scores.sp2 <- pca.cal$li[row.sp2, ] # scores for sp2
}
# calculation of occurence density and test of niche equivalency and similarity
# with the default kernel method
z1 <- ecospat.grid.clim.dyn(scores.clim, scores.clim, scores.sp1, R = 100)
z2 <- ecospat.grid.clim.dyn(scores.clim, scores.clim, scores.sp2, R = 100)

# calculation of occurence density and test of niche equivalency and similarity
# with the ks kernel method
z1.kde <- ecospat.grid.clim.dyn(scores.clim, scores.clim, scores.sp1, R = 100, kernel.method = "ks")
z2.kde <- ecospat.grid.clim.dyn(scores.clim, scores.clim, scores.sp2, R = 100, kernel.method = "ks")

par(mfrow = c(2, 2))
plot(z1$z.uncor, main = "Sp1 with default kernel")
plot(z1.kde$z.uncor, main = "Sp1 with KS kernel")
plot(z2$z.uncor, main = "Sp2 with default kernel")
plot(z2.kde$z.uncor, main = "Sp2 with KS kernel")

z1.ext <- ecospat.grid.clim.dyn(scores.clim, scores.clim, scores.sp1, R = 100,
  extend.extent = c(0,1,0,0)) 

par(mfrow = c(1, 2))
plot(z1$z.uncor, main = "Sp1 with default extent")
plot(z1.ext$z.uncor, main = "Sp1 with extended extent")

Description

Investigate spatial autocorrelation of environmental covariables within a set of occurrences as a function of distance.

Usage

ecospat.mantel.correlogram (dfvar, colxy, n, colvar, max, nclass, nperm)

Arguments

Details

Requires ecodist library. Note that computation time increase tremendously when using more than 500 occurrences (n>500)

Value

Draws a plot with distance vs. the mantel r value. Black circles indicate that the values are significative different from zero. White circles indicate non significant autocorrelation. The selected distance is at the first white circle where values are non significative different from cero.

Author(s)

Olivier Broennimann [email protected]

References

Legendre, P. and M.J. Fortin. 1989. Spatial pattern and ecological analysis. Vegetatio, 80, 107-138.

See Also

mgram

Examples

ecospat.mantel.correlogram(dfvar=ecospat.testData[c(2:16)],colxy=1:2, n=100, colvar=3:7, 
max=1000, nclass=10, nperm=100)

Description

Estimate the margin of the distribution in the bi-dimensional environmental space based on bootstrapped kernel density estimation the percentage of the distribution included within the margin.

Usage

ecospat.margin (z, th.quant, kern.method, bootstrap, bootstrap.rep, bootstrap.ncore)

Arguments

Details

th.quant is the quantile of the distribution of species density at occurrence sites. For example, if th.quant is set to 0.05, the margin of the distribution is drawn by including 95 percent of the species occurrences, removing the more marginal populations. If th.quant is set to 0, the margin of the distribution is the minimal envelope including 100 percent of the species occurrences. The bootstrap estimation of the margin allows representing the uncertainty around this margin. By default it returns a contour covering a 95 percents confidence interval (CI), but you can easily choose a custom CI.

Value

a list with $niche.envelope = a SpatRaster of the niche envelope including the distribution, $niche.contour = a SpatiaLine object of the margin, $niche.density = a SpatRaster of the niche density within the niche envelope.

Author(s)

Blaise Petitpierre [email protected]

See Also

ecospat.plot.niche.dyn

Examples

library(ade4)
library(terra)

data(ecospat.testData)

sp1 <- ecospat.testData[ecospat.testData$Bromus_erectus == 1, 1:8] # species occurences
clim <- ecospat.testData[4:8] # environment of the study area

#################################### PCA-ENVIRONMENT ##################################
library(ade4)
pca.cal <- ade4::dudi.pca(clim, center = TRUE, scale = TRUE, scannf = FALSE, nf = 2)

####### projection of the species distribution into the environmental space ######
# predict the scores on the axes
scores.clim <- pca.cal$li # scores for global climate
scores.sp1 <- ade4::suprow(pca.cal, sp1[, 4:8])$li # scores for sp1

z1 <- ecospat.grid.clim.dyn(scores.clim, scores.clim, scores.sp1, R = 100, 
  extend.extent = c(0, 1, 0, 0))

####### estimate the margin ######
z1.margin <- ecospat.margin(z1, th.quant = 0, bootstrap = FALSE) # including all occurrences
z1.95margin <- ecospat.margin(z1, th.quant = 0.05, 
  bootstrap = FALSE) # including 95 percent of the occurrences
z1.bootstrap.margin <- ecospat.margin(z1,th.quant = 0,
  bootstrap = TRUE, bootstrap.rep = 100) # bootstrap estimation of the niche limit

####### plot the margin and its uncertainty ######
plot(z1.margin$niche.density) # plot of the niche density
points(z1$sp) # with species occurences
lines(z1.margin$niche.contour) # limit of the margin if you include all the distribution
lines(z1.95margin$niche.contour, col = 2) # limit of the margin if you exclude the 
                                                  # 5 percents of the most marginal distribution
lines(z1.bootstrap.margin$niche.contour, col = 2, lty = "dotted") 
      # limit of the niche based on the 95 percent CI of the bootstrap

par(mfrow=c(1,2))
plot(z1.bootstrap.margin$niche.envelope, main = "Margin uncertainty", 
  legend.args=list(text="CI", cex = 0.8)) # shows uncertainty of niche margin in SpatRaster mode
points(z1$sp) # with species occurences
# shows the uncertainty of the niche limit in vector mode
boot<-terra::as.contour(z1.bootstrap.margin$niche.envelope)
plot(boot, col = gray(10:1 / 10), main = "Margin uncertainty") 
# select a customized confidence interval (here for example 80 percent)
confInt80 <- terra::as.polygons(z1.bootstrap.margin$niche.envelope >= 50, dissolve = TRUE) 
lines(confInt80, lty = "dotted", col = 2)

Description

Calculates values for Cohen's Kappa along different thresholds, considering this time 0.01 increments (i.e. 99 thresholds).

Usage

ecospat.max.kappa(Pred, Sp.occ)

Arguments

Value

Return values for Cohen's Kappa for 99 thresholds at 0.01 increments.

Author(s)

Antoine Guisan [email protected] with contributions of Luigi Maiorano [email protected] and Valeria Di Cola [email protected].

References

Liu, C., P.M. Berry, T.P. Dawson, and R.G. Pearson. 2005. Selecting thresholds of occurrence in the prediction of species distributions. Ecography, 28, 385-393.

See Also

ecospat.meva.table, ecospat.max.tss, ecospat.plot.tss, ecospat.cohen.kappa, ecospat.plot.kappa

Examples

Pred <- ecospat.testData$glm_Agrostis_capillaris
Sp.occ <- ecospat.testData$Agrostis_capillaris
kappa100 <- ecospat.max.kappa(Pred, Sp.occ)

Description

Calculates values for True skill statistic (TSS) along different thresholds, considering this time 0.01 increments (i.e. 99 thresholds).

Usage

ecospat.max.tss(Pred, Sp.occ)

Arguments

Value

Return values for TSS for 99 thresholds at 0.01 increments.

Author(s)

Luigi Maiorano [email protected] with contributions of Antoine Guisan [email protected]

References

Liu, C., P.M. Berry, T.P. Dawson, and R.G. Pearson. 2005. Selecting thresholds of occurrence in the prediction of species distributions. Ecography, 28, 385-393.

See Also

ecospat.meva.table, ecospat.max.kappa, ecospat.plot.tss, ecospat.cohen.kappa, ecospat.plot.kappa

Examples

data(ecospat.testData)
Pred <- ecospat.testData$glm_Agrostis_capillaris
Sp.occ <- ecospat.testData$Agrostis_capillaris
TSS100 <- ecospat.max.tss(Pred, Sp.occ)

Description

Calculate the importance of variables for Maxent in the same way Biomod does, by randomly permuting each predictor variable independently, and computing the associated reduction in predictive performance.

Usage

ecospat.maxentvarimport (model, dfvar, nperm)

Arguments

Details

The calculation is made as biomod2 "variables_importance" function. It's more or less base on the same principle than randomForest variables importance algorithm. The principle is to shuffle a single variable of the given data. Make model prediction with this 'shuffled' data.set. Then we compute a simple correlation (Pearson's by default) between references predictions and the 'shuffled' one. The return score is 1-cor(pred_ref,pred_shuffled). The highest the value, the more influence the variable has on the model. A value of this 0 assumes no influence of that variable on the model. Note that this technique does not account for interactions between the variables.

Value

a list which contains a data.frame containing variables importance scores for each permutation run.

Author(s)

Blaise Petitpierre [email protected]

Examples

library(dismo)
data('ecospat.testData')

# data for Soldanella alpina
data.Solalp<- ecospat.testData[c("Soldanella_alpina","ddeg","mind","srad","slp","topo")]

# path to maxent.jar file
path<- paste0(system.file(package="dismo"), "/java/maxent.jar")

if (file.exists(path) & require(rJava)) {
  me <- maxent(data.Solalp[,-1],data.Solalp[,1])
  ecospat.maxentvarimport (model=me, dfvar=data.Solalp[,-1], nperm=5)
  }

Description

ecospat.mdr is a function that implement a minimum cost arborescence approach to analyse the invasion routes of a species from dates occurrence data.

Usage

ecospat.mdr (data, xcol, ycol, datecol, mode, rep, mean.date.error, fixed.sources.rows)

Arguments

Details

The function draws an incoming route to each occurence from the closest occurrence already occupied (with a previous date) and allows to substract a random number of time (years) to the observed dates from a truncated negative exponential distribution. It is possible to run several iterations and to get boostrap support for each route. itexp and rtexp functions are small internal functions to set a truncated negative exponential distribution.

Value

A list is returned by the function with in positon [[1]], a datafame with each row corresponding to a route (with new/old coordinates, new/old dates, length of the route, timespan, dispersal rate), in position [[2]] the total route length, in position [[3]] the median dispersal rate and in position [[4]] the number of outgoing nodes (index of clustering of the network)

Author(s)

Olivier Broennimann [email protected]

References

Hordijk, W. and O. Broennimann. 2012. Dispersal routes reconstruction and the minimum cost arborescence problem. Journal of theoretical biology, 308, 115-122.

Broennimann, O., P. Mraz, B. Petitpierre, A. Guisan, and H. Muller-Scharer. 2014. Contrasting spatio-temporal climatic niche dynamics during the eastern and western invasions of spotted knapweed in North America.Journal of biogeography, 41, 1126-1136.

Examples

if(require("maps",quietly=TRUE)){

data(ecospat.testMdr)
data<- ecospat.testMdr
intros<-order(data$date)[1:2] # rows corresponding to first introductions

# plot observed situation

plot(data[,2:1],pch=15,cex=0.5)
points(data[intros,2:1],pch=19,col="red")
text(data[,2]+0.5,data[,1]+0.5,data[,3],cex=0.5)
map(add=TRUE)

# calculate minimum cost arborescence (MCA) of dispersal routes

obs<-ecospat.mdr(data=data,xcol=2,ycol=1,datecol=3,mode="min",rep=100,
                  mean.date.error=1,fixed.sources.rows=intros)

# plot MCA results
# arrows' thickness indicate support for the routes

mca<-obs[[1]]
plot(mca[,3:4],type="n",xlab="longitude",ylab="latitude")
arrows(mca[,1],mca[,2],mca[,3],mca[,4],length = 0.05,lwd=mca$bootstrap.value*2)
map(add=TRUE)

# plot intros

points(data[intros,2:1],pch=19,col="red")
text(data[intros,2]+0.5,data[intros,1]+0.5,data[intros,3],cex=1,col="red")

# dispersal routes statistics

obs[[2]] # total routes length in DD
obs[[3]] # median dispersal rate in DD/yr
obs[[4]] # number of outcoming nodes
}

Description

Calculate the MESS (i.e. extrapolation) as in Maxent.

Usage

ecospat.mess (proj, cal, w="default")

Arguments

Details

Shows the variable that drives the multivariate environmental similarity surface (MESS) value in each grid cell.

Value

Author(s)

Blaise Petitpierre [email protected]. Modified by Daniel Scherrer [email protected]

References

Elith, J., M. Kearney and S. Phillips. 2010. The art of modelling range-shifting species. Methods in ecology and evolution, 1, 330-342.

See Also

ecospat.plot.mess

Examples

x <- ecospat.testData[c(2,3,4:8)]
proj <- x[1:90,] #A projection dataset.
cal <- x[91:300,] #A calibration dataset

#Create a MESS object 
mess.object <- ecospat.mess (proj, cal, w="default")

#Plot MESS 
ecospat.plot.mess (mess.object, cex=1, pch=15)

Description

Calculates values of a series of different evaluations metrics for a model and for a given threshold value

Usage

ecospat.meva.table(Pred, Sp.occ, th)

Arguments

Value

A contingency table of observations and predicted probabilities of presence values, and a list of evaluation metrics for the selected threshold.

Author(s)

Antoine Guisan [email protected] with contributions of Luigi Maiorano [email protected]

References

Pearce, J. and S. Ferrier. 2000. Evaluating the predictive performance of habitat models developed using logistic regression. Ecol. Model., 133, 225-245. Wunderlich, R.F. et al. 2019. Two alternative evaluation metrics to replace the true skill statistic in the assessment of species distribution models. Nature Conservation, 35, 97-116. doi:10.3897/natureconservation.35.33918

See Also

ecospat.max.kappa, ecospat.max.tss, ecospat.plot.tss, ecospat.cohen.kappa, ecospat.plot.kappa

Examples

Pred <- ecospat.testData$glm_Agrostis_capillaris
Sp.occ <- ecospat.testData$Agrostis_capillaris

meva <- ecospat.meva.table (Pred, Sp.occ, 0.39)

Description

Calculate the minimal predicted area.

Usage

ecospat.mpa (Pred, Sp.occ.xy, perc)

Arguments

Details

The minimal predicted area (MPA) is the minimal surface obtained by considering all pixels with predictions above a defined probability threshold (e.g. 0.7) that still encompasses 90 percent of the species' occurrences (Engler et al. 2004).

Value

Returns the minimal predicted area.

Author(s)

Frank Breiner [email protected] with the contribution of Flavien Collart

References

Engler, R., A. Guisan and L. Rechsteiner. 2004. An improved approach for predicting the distribution of rare and endangered species from occurrence and pseudo-absence data. Journal of Applied Ecology, 41, 263-274.

Examples

data(ecospat.testData)
obs <- (ecospat.testData$glm_Saxifraga_oppositifolia
[which(ecospat.testData$Saxifraga_oppositifolia==1)])

ecospat.mpa(obs)
ecospat.mpa(obs,perc=1) ## 100 percent of the presences encompassed

Description

Calculate niche Pioneering, Expansion, Stability, Unfilling and Abandonment.

Usage

ecospat.niche.dyn.index (z1, z2, intersection=0)

Arguments

Details

The function allows to perform niche dynamics analyses between two species. Originally based on Expansion, Stability and Unfilling indices as proposed in Guisan et al. 2014, it now includes the quantification of categories of niche dynamics proposed by Atwater et al. 2018, where the Pioneering niche represents the part of the niche Expansion in the invaded range that corresponds to environments not present in the native range and the Abandonment niche the part of the Unfilling niche in the native range that corresponds to environments not present in the invaded range. If you encounter a problem during your analyses, please first read the FAQ section of "Niche overlap" in https://www.unil.ch/ecospat/home/menuguid/ecospat-resources/tools.html

Value

A list of three objects: a rast object which classifies each pixels of the environmental space into Pioneering, Expansion, Stability, Unfilling or Abandonment Niche. A vector with the Expansion, Stability and Unfilling index values as proposed in Guisan et al. 2014. A vector with the count of pixels for each of the five niche dynamics categories.

Author(s)

Blaise Petitpierre [email protected], Olivier Broennimann [email protected]

References

Guisan, A., Petitpierre, B., Broennimann, O., Daehler, C., Kueffer, C. 2014. Unifying niche shift studies: insights from biological invasions. Trends in ecology and Ecolution, 29,260-269.

Atwater, D.Z., Ervine, C. and Barney J.N. 2018. Climatic niche shifts are common in introduced plants. Nature ecology and Evolution, 2, 34-43.

See Also

ecospat.grid.clim.dyn

Description

Creates a SpatRaster in geography with each pixel containing a niche dynamic index (stability, expansion, or unfilling) extracted from 2 niches generated with ecospat.grid.clim.dyn.

Usage

ecospat.niche.dynIndexProjGeo(z1, z2, proj, env)

Arguments

Details

Extracts the niche dynamic index of objects created by ecospat.niche.dyn.index for each background point (glob) using extract from the terra package. The values are projected to the geographic coordinates of env and returned as a SpatRaster layer. If proj=0, the common background for z1 and z2 (glob) is used. If proj=1, the background (glob1) of z1 is used. If proj=2, the background (glob1) of z2 is used.

Value

a SpatRaster with cell values 0-3. 1: unfilling (habitat occupied by species 1); 2: expansion (habitat occupied only by species 2); 3: stability (habitat occupied by both species); and 0 (unoccupied habitat).

Author(s)

Olivier Broennimann [email protected], Tyler Smith [email protected]

References

Broennimann, O., M.C. Fitzpatrick, P.B. Pearman, B. Petitpierre, L. Pellissier, N.G. Yoccoz, W. Thuiller, M.J. Fortin, C. Randin, N.E. Zimmermann, C.H. Graham and A. Guisan. 2012. Measuring ecological niche overlap from occurrence and spatial environmental data. Global Ecology and Biogeography, 21:481-497.

Petitpierre, B., C. Kueffer, O. Broennimann, C. Randin, C. Daehler and A. Guisan. 2012. Climatic niche shifts are rare among terrestrial plant invaders. Science, 335:1344-1348.

See Also

ecospat.plot.niche.dyn, ecospat.niche.dyn.index, ecospat.niche.zProjGeo

Examples

library(ade4)
library(terra)

data(ecospat.testNiche)
spp <- ecospat.testNiche
xy.sp1 <- subset(spp, species=="sp1")[2:3] #Bromus_erectus
xy.sp2 <- subset(spp, species=="sp4")[2:3] #Pritzelago_alpina

env<-terra::rast(system.file("extdata","ecospat.testEnv.tif",package="ecospat"))

env.sp1 <- terra::extract(env, xy.sp1)[,-1]
env.sp2 <- terra::extract(env, xy.sp2)[,-1]
env.bkg <- na.exclude(terra::values(env))

#####################
## PCA-ENVIRONMENT ##
#####################

library(ade4)
pca.cal <- ade4::dudi.pca(env.bkg, center = TRUE, scale = TRUE,
                    scannf = FALSE, nf = 2)

# predict the scores on the axes
scores.bkg <- pca.cal$li  #scores for background climate
scores.sp1 <- ade4::suprow(pca.cal,env.sp1)$lisup  #scores for sp1
scores.sp2 <- ade4::suprow(pca.cal,env.sp2)$lisup  #scores for sp2

# calculation of occurence density (niche z)
  
z1 <- ecospat.grid.clim.dyn(scores.bkg, scores.bkg,
                            scores.sp1, R = 100)
z2 <- ecospat.grid.clim.dyn(scores.bkg, scores.bkg,
                            scores.sp2, R = 100)

plot(z1$z.uncor)
points(scores.sp1, pch = 21, bg = "green")

plot(z2$z.uncor)
points(scores.sp2, pch = 21, bg = "red")

ecospat.plot.niche.dyn(z1, z2)
points(scores.sp1, pch = 21, bg = "green")
points(scores.sp2, pch = 21, bg = "red")
ecospat.niche.overlap(z1,z2 ,cor = TRUE)

##############################
## dynamic indices in space ##
##############################

geozS <- ecospat.niche.dynIndexProjGeo(z1, z2, proj=0, env)

plot(geozS, col = c("grey", "green", "red", "blue"),
     legend = FALSE)
points(xy.sp1, bg = "green", pch = 21)
points(xy.sp2, bg = "red", pch = 21)

Description

Run a niche equivalency test (see Warren et al 2008) based on two species occurrence density grids.

Usage

ecospat.niche.equivalency.test (z1, z2, rep, intersection = 0, 
overlap.alternative = "higher", expansion.alternative = "lower", 
stability.alternative = "higher", unfilling.alternative = "lower", ncores = 1)

Arguments

Details

Compares the observed niche overlap, expansion, stability and unfilling between z1 and z2 to simulated values between random niches z1.sim and z2.sim, which are built from random reallocations of occurences of z1 and z2.

intersection allows setting if the niche dynamic indices (expansion, stability and unfilling) are measured across the full extent pooling the two study areas or not. If intersection = NA, the analysis is performed on the whole environmental extent (native and invaded). If instersection = 0, the analysis is performed at the intersection between native and invaded range. If instersection = 0.05, the analysis is performed at the intersection of the 5th quantile of both native and invaded environmental densities. Etc...

overlap.alternative specifies if you want to test for niche conservatism (overlap.alternative = "higher", i.e. the niche overlap is more equivalent/similar than random) or for niche divergence (overlap.alternative = "lower", i.e. the niche overlap is less equivalent/similar than random). You can also specifiy if you want to test if you have more, less or different observed niche dynamics than random niches(with expansion.alternative, stability.alternative and unfilling.alternative). If you want to test for niche conservatism, we recommande to set these niche dynamic hypotheses to "lower", "higher" and "lower" respectively for expansion, stability and unfilling.

If you encounter a problem during your analyses, please first read the FAQ section of "Niche overlap" in https://www.unil.ch/ecospat/home/menuguid/ecospat-resources/tools.html

The arguments ncores allows choosing the number of cores used to parallelize the computation. The default value is 1. On multicore computers, the optimal would be ncores = detectCores() - 1.

Value

a list with $obs = observed overlap and dynamic indices, $sim = simulated overlap and dynamic indices, $p.D = p-value of the test on D, $p.I = p-value of the test on I, $p.expansion = p-value for the test on expansion, $p.stability = p-value for the test on stability, $p.unfilling = p-value for the test on unfilling.

Author(s)

Olivier Broennimann [email protected] with contributions of Blaise Petitpierre [email protected]

References

Broennimann, O., M.C. Fitzpatrick, P.B. Pearman,B. Petitpierre, L. Pellissier, N.G. Yoccoz, W. Thuiller, M.J. Fortin, C. Randin, N.E. Zimmermann, C.H. Graham and A. Guisan. 2012. Measuring ecological niche overlap from occurrence and spatial environmental data. Global Ecology and Biogeography, 21, 481-497.

Warren, D.L., R.E. Glor and M. Turelli. 2008. Environmental niche equivalency versus conservatism: quantitative approaches to niche evolution. Evolution, 62, 2868-2883.

See Also

ecospat.grid.clim.dyn, ecospat.niche.similarity.test

Description

Calculate the overlap metrics D and I based on two species occurrence density grids z1 and z2 created by ecospat.grid.clim.

Usage

ecospat.niche.overlap (z1, z2, cor)

Arguments

Details

if cor=FALSE, the z$uncor objects created by ecospat.grid.clim are used to calculate the overlap. if cor=TRUE, the z$cor objects are used.

If you encounter a problem during your analyses, please first read the FAQ section of "Niche overlap" in https://www.unil.ch/ecospat/home/menuguid/ecospat-resources/tools.html

Value

Overlap values D and I. D is Schoener's overlap metric (Schoener 1970). I is a modified Hellinger metric(Warren et al. 2008)

Author(s)

Olivier Broennimann [email protected]

References

Broennimann, O., M.C. Fitzpatrick, P.B. Pearman, B. Petitpierre, L. Pellissier, N.G. Yoccoz, W. Thuiller, M.J. Fortin, C. Randin, N.E. Zimmermann, C.H. Graham and A. Guisan. 2012. Measuring ecological niche overlap from occurrence and spatial environmental data. Global Ecology and Biogeography, 21, 481-497.

Schoener, T.W. 1968. Anolis lizards of Bimini: resource partitioning in a complex fauna. Ecology, 49, 704-726.

Warren, D.L., R.E. Glor and M. Turelli. 2008. Environmental niche equivalency versus conservatism: quantitative approaches to niche evolution. Evolution, 62, 2868-2883.

See Also

ecospat.grid.clim.dyn

Description

Run a niche similarity test (see Warren et al 2008) based on two species occurrence density grids.

Usage

ecospat.niche.similarity.test (z1, z2, rep, intersection = 0, 
  rand.type = 1, ncores= 1, overlap.alternative = "higher", 
  expansion.alternative = "lower", stability.alternative = "higher", 
  unfilling.alternative = "lower")

Arguments

Details

Compares the observed niche overlap between z1 and z2 to overlaps between z1 and random niches (z2.sim) as available in the range of z2 (z2$Z). z2.sim has the same pattern as z2 but the center is randomly translatated in the availabe z2$Z space and weighted by z2$Z densities.

intersection allows setting if the niche dynamic indices (expansion, stability and unfilling) are measured across the full extent pooling the two study areas or not. If intersection = NA, the analysis is performed on the whole environmental extent (native and invaded). If instersection = 0, the analysis is performed at the intersection between native and invaded range. If instersection = 0.05, the analysis is performed at the intersection of the 5th quantile of both native and invaded environmental densities. Etc...

If rand.type = 1, both z1 and z2 are randomly shifted, if rand.type = 2, only z2 is randomly shifted.

overlap.alternative specifies if you want to test for niche conservatism (overlap.alternative = "higher", i.e. the niche overlap is more equivalent/similar than random) or for niche divergence (overlap.alternative = "lower", i.e. the niche overlap is less equivalent/similar than random). You can also specifiy if you want to test if you have more, less or different observed niche dynamics than random niches(with expansion.alternative, stabilty.alternative and unfilling.alternative). If you want to test for niche conservatism, we recommande to set these niche dynamic hypotheses to "lower", "higher" and "lower" respectively for expansion, stability and unfilling.

If you encounter a problem during your analyses, please first read the FAQ section of "Niche overlap" in https://www.unil.ch/ecospat/home/menuguid/ecospat-resources/tools.html

The arguments ncores allows choosing the number of cores used to parallelize the computation. The default value is 1. On multicore computers, the optimal would be ncores = detectCores() - 1.

Value

a list with $obs = observed overlap and dynamic indices, $sim = simulated overlap and dynamic indices, $p.D = p-value of the test on D, $p.I = p-value of the test on I, $p.expansion = p-value for the test on expansion, $p.stability = p-value for the test on stability, $p.unfilling = p-value for the test on unfilling.

Author(s)

Olivier Broennimann [email protected] with contributions of Blaise Petitpierre [email protected]

References

Broennimann, O., M.C. Fitzpatrick, P.B. Pearman, B. Petitpierre, L. Pellissier, N.G. Yoccoz, W. Thuiller, M.J. Fortin, C. Randin, N.E. Zimmermann, C.H. Graham and A. Guisan. 2012. Measuring ecological niche overlap from occurrence and spatial environmental data. Global Ecology and Biogeography, 21, 481-497.

Warren, D.L., R.E. Glor and M. Turelli. 2008. Environmental niche equivalency versus conservatism: quantitative approaches to niche evolution. Evolution, 62, 2868-2883.

See Also

ecospat.grid.clim.dyn, ecospat.niche.equivalency.test

Description

Creates a raster in geography with each pixel containing the occurrence densities extracted from a z object generated with ecospat.grid.clim.dyn.

Usage

ecospat.niche.zProjGeo(z,zproj,env,cor)

Arguments

Details

extracts the occurrence density of z and project them in geography. If zproj=NULL, the occurrence density of z is extracted for each point of the background of z (glob1) using extract (package terra). The values are binded to the geographic coordinates of env and a raster is then recreated using rast with the argument type="xyz".If zproj is a occurrence density object, the background glob1 of this object is chosen and the projection is made on this background.env must then must be the same as used to create zproj.

Value

raster of class RasterLayer

Author(s)

Olivier Broennimann [email protected]

References

Broennimann, O., M.C. Fitzpatrick, P.B. Pearman, B. Petitpierre, L. Pellissier, N.G. Yoccoz, W. Thuiller, M.J. Fortin, C. Randin, N.E. Zimmermann, C.H. Graham and A. Guisan. 2012. Measuring ecological niche overlap from occurrence and spatial environmental data. Global Ecology and Biogeography, 21:481-497.

Petitpierre, B., C. Kueffer, O. Broennimann, C. Randin, C. Daehler and A. Guisan. 2012. Climatic niche shifts are rare among terrestrial plant invaders. Science, 335:1344-1348.

See Also

ecospat.plot.niche.dyn, ecospat.niche.dynIndexProjGeo

Examples

library(ade4)
library(terra)

data("ecospat.testNiche")
spp <- ecospat.testNiche
xy.sp1<-subset(spp,species=="sp1")[2:3] #Bromus_erectus

env<-terra::rast(system.file("extdata","ecospat.testEnv.tif",package="ecospat"))
#plot(env)

env.sp1<-terra::extract(env,xy.sp1)[,-1]
env.bkg<-na.exclude(terra::values(env))

#################################### PCA-ENVIRONMENT ##################################

pca.cal <- ade4::dudi.pca(env.bkg, center = TRUE, scale = TRUE, scannf = FALSE, nf = 2)

# predict the scores on the axes
scores.bkg <- pca.cal$li  #scores for background climate
scores.sp1 <- ade4::suprow(pca.cal,env.sp1)$lisup				#scores for sp1

# calculation of occurence density (niche z)
  
z1 <- ecospat.grid.clim.dyn(scores.bkg, scores.bkg, scores.sp1,R=100)

plot(z1$z.uncor)
points(scores.sp1)

#################################### occurrence density in space ##################################

# sp1
geoz1<-ecospat.niche.zProjGeo(z1,zproj=NULL,env=env)
plot(geoz1,main="z1")
points(xy.sp1)

Description

ecospat.nicheNBmean calculates the weighted mean niche breadth accross several axes from a nichePOSNB object.

Usage

ecospat.nicheNBmean(POSNB,w)

Arguments

Details

The function calculates the weighted mean niche breadth. The weights w are rescaled so that their sum equals 1.

Value

The function returns a 1 column dataframe with the weighted mean niche breadth for each taxa.

Author(s)

Lucie Malard [email protected] and Olivier Broennimann [email protected]

References

L.A. Malard, H.K. Mod, N. Guex, O. Broennimann, E. Yashiro, E. Lara, E.D.A. Mitchell, H. Niculita-Hirzel & A. Guisan. The ecological niche of soil bacterial, archaeal, fungal and protist communities along environmental gradients in the Alps. 2021. Accepted in Soil Biology and Biochemistry.

Examples

data(ecospat.testNichePOSNB)
df<-ecospat.testNichePOSNB

# 1 axes
POSNB<-ecospat.nichePOSNB(df,colvar=c(2),colfreq = 6:17) 

# 2 axes
POSNB<-ecospat.nichePOSNB(df,colvar=c(2:3),colfreq = 6:17) 
ecospat.nicheNBmean(POSNB,w=c(2,1))

# 4 axes
POSNB<-ecospat.nichePOSNB(df,colvar=c(2:5),colfreq = 6:17) 
ecospat.nicheNBmean(POSNB,w=c(1,0.8,0.2,0.1))

Description

ecospat.nichePOSNB calculates the niche breadth and niche position of taxa along environmental gradients from abundance data.

Usage

ecospat.nichePOSNB (df,colvar,colfreq)

Arguments

Details

The function calculates niche position and niche breadth of taxa along one or multiple environmental axes. Niche position is calculated as the mean of the variable, weighted by the relative abundance of the species. Niche breadth is calculated as the standard deviation of each variable, weighted by the relative abundance of the species at each sampling site.

Value

The function returns a matrix containing the average niche position and niche breadth of each taxa along each environmental axi.

Author(s)

Lucie Malard [email protected] and Olivier Broennimann [email protected]

References

L.A. Malard, H.K. Mod, N. Guex, O. Broennimann, E. Yashiro, E. Lara, E.D.A. Mitchell, H. Niculita-Hirzel & A. Guisan. The ecological niche of soil bacterial, archaeal, fungal and protist communities along environmental gradients in the Alps. 2021. Accepted in Soil Biology and Biochemistry.

Examples

data(ecospat.testNichePOSNB)
df<-ecospat.testNichePOSNB

# 1 axes
POSNB<-ecospat.nichePOSNB(df,colvar=c(2),colfreq = 6:17) 

# 2 axes
POSNB<-ecospat.nichePOSNB(df,colvar=c(2:3),colfreq = 6:17) 
ecospat.nicheNBmean(POSNB,w=c(2,1))

# 4 axes
POSNB<-ecospat.nichePOSNB(df,colvar=c(2:5),colfreq = 6:17) 
ecospat.nicheNBmean(POSNB,w=c(1,0.8,0.2,0.1))

Description

Calculate the maximum number of predictors to include in the model with a desired correlation between predictors.

Usage

ecospat.npred (x, th)

Arguments

Value

Returns the number of predictors to use.

Author(s)

Blaise Petitpierre [email protected]

Examples

colvar <- ecospat.testData[c(4:8)]
x <- cor(colvar, method="pearson")
ecospat.npred (x, th=0.75)

Description

Remove species occurrences in a dataframe which are closer to each other than a specified distance threshold.

Usage

ecospat.occ.desaggregation (xy, min.dist, by)

Arguments

Details

This function will desaggregate the original number of occurrences, according to a specified distance.

Value

A subset of the initial dataframe. The number of points is printed as "initial", "kept" and "out".

Author(s)

Frank Breiner [email protected]

with contributions of Olivier Broennimann [email protected]

Examples

spp <- ecospat.testNiche
colnames(spp)[2:3] <- c('x','y')
sp1 <- spp[1:32,2:3]

occ.sp1 <- ecospat.occ.desaggregation(xy=sp1, min.dist=500, by=NULL)
occ.all.sp <- ecospat.occ.desaggregation(xy=spp, min.dist=500, by='Spp')

Description

This function determines the occupied patch of a species using standard IUCN criteria (AOO, EOO) or predictive binary maps from Species Distribution Models.

Usage

ecospat.occupied.patch (bin.map, Sp.occ.xy, buffer = 0)

Arguments

Details

Predictive maps derived from SDMs inform about the potential distribution (or habitat suitability) of a species. Often it is useful to get information about the area of the potential distribution which is occupied by a species, e.g. for Red List assessments.

Value

a SpatRaster with value 1.

Author(s)

Frank Breiner [email protected] with the contribution of Flavien Collart

References

IUCN Standards and Petitions Subcommittee. 2016. Guidelines for Using the IUCN Red List Categories and Criteria. Version 12. Prepared by the Standards and Petitions Subcommittee. Downloadable from http://www.iucnredlist.org/documents/RedListGuidelines.pdf

See Also

ecospat.rangesize, ecospat.mpa, ecospat.binary.model

Examples

library(terra)
library(dismo)

# coordinates of the plots
xy <- ecospat.testData[,2:3]

# environmental data
predictors <- terra::rast(system.file("extdata","ecospat.testEnv.tif",package="ecospat"))
env <- terra::extract(predictors,xy,ID=FALSE)  
spData <- cbind.data.frame(occ=ecospat.testData$Veronica_alpina,env)
mod <- glm(occ~ddeg0+I(ddeg0^2)+srad68+I(srad68^2),data=spData,family = binomial())

# predict to entire dataset
pred <- terra::predict(predictors,mod,type="response") 
plot(pred)
points(xy[spData$occ==1,])
  
### make binary maps
#arbitratry threshold
pred.bin.arbitrary <- ecospat.binary.model(pred,0.3)
names(pred.bin.arbitrary) <- "me.arbitrary"
# use MPA to convert suitability to binary map
mpa.cutoff <- ecospat.mpa(pred,xy[spData$occ==1,])
pred.bin.mpa <- ecospat.binary.model(pred,mpa.cutoff)
names(pred.bin.mpa) <- "me.mpa"

mpa.ocp  <- ecospat.occupied.patch(pred.bin.mpa,xy[spData$occ==1,])
arbitrary.ocp  <- ecospat.occupied.patch(pred.bin.arbitrary,xy[spData$occ==1,])
par(mfrow=c(1,2))
plot(mpa.ocp) ## occupied patches: green area
points(xy[spData$occ==1,],col="red",cex=0.5,pch=19)
plot(arbitrary.ocp)
points(xy[spData$occ==1,],col="red",cex=0.5,pch=19)


## with buffer:
mpa.ocp  <- ecospat.occupied.patch(pred.bin.mpa,xy[spData$occ==1,], buffer=5000)
arbitrary.ocp  <- ecospat.occupied.patch(pred.bin.arbitrary,xy[spData$occ==1,], buffer=5000)

plot(mpa.ocp) ## occupied patches: green area
points(xy[spData$occ==1,],col="red",cex=0.5,pch=19)
plot(arbitrary.ocp)
points(xy[spData$occ==1,],col="red",cex=0.5,pch=19)

Description

A permutation function to get p-values on GLM coefficients and deviance.

Usage

ecospat.permut.glm (glm.obj, nperm, verbose = FALSE)

Arguments

Details

Rows of the response variable are permuted and a new GLM is calibrated as well as deviance, adjusted deviance and coefficients are calculated. These random parameters are compared to the true parameters in order to derive p-values.

Value

Return p-values that are how the true parameters of the original model deviate from the disribution of the random parameters. A p-value of zero means that the true parameter is completely outside the random distribution.

Author(s)

Christophe Randin [email protected], Antoine Guisan [email protected] and Trevor Hastie

References

Hastie, T., R. Tibshirani and J. Friedman. 2001. Elements of Statistical Learning; Data Mining, Inference, and Prediction, Springer-Verlag, New York.

Legendre, P. and L. Legendre. 1998. Numerical Ecology, 2nd English edition. Elsevier Science BV, Amsterdam.

Examples

if(require("rms",quietly=TRUE)){
  data('ecospat.testData')

  # data for Soldanella alpina
  data.Solalp<- ecospat.testData[c("Soldanella_alpina","ddeg","mind","srad","slp","topo")] 

  # glm model for Soldanella alpina

  glm.Solalp <- glm(Soldanella_alpina ~ pol(ddeg,2) + pol(mind,2) + pol(srad,2) + pol(slp,2) 
      + pol(topo,2), data = data.Solalp, family = binomial)
                  
  # p-values
  ecospat.permut.glm (glm.Solalp, 1000)
}

Description

Plot the contribution of the initial variables to the analysis (i.e. correlation circle). Typically these are the eigen vectors and eigen values in ordinations.

Usage

ecospat.plot.contrib (contrib, eigen)

Arguments

Details

Requires ade4 library. If using princomp , use $loadings and $sdev of the princomp object. if using dudi.pca, use $li and $eig of the dudi.pca object.

Author(s)

Olivier Broennimann [email protected]

References

Broennimann, O., M.C. Fitzpatrick, P.B. Pearman, B. Petitpierre, L. Pellissier, N.G. Yoccoz, W. Thuiller, M.J. Fortin, C. Randin, N.E. Zimmermann, C.H. Graham and A. Guisan. 2012. Measuring ecological niche overlap from occurrence and spatial environmental data. Global Ecology and Biogeography, 21, 481-497.

See Also

ecospat.plot.niche.dyn,ecospat.plot.overlap.test, ecospat.niche.similarity.test,princomp

Description

Plots the values for Cohen's Kappa along different thresholds.

Usage

ecospat.plot.kappa(Pred, Sp.occ)

Arguments

Value

A plot of the Cohen's Kappa values along different thresholds.

Author(s)

Luigi Maiorano [email protected] with contributions of Valeria Di Cola [email protected].

References

Liu, C., P.M. Berry, T.P. Dawson, and R.G. Pearson. 2005. Selecting thresholds of occurrence in the prediction of species distributions. Ecography, 28, 385-393.

Landis, J.R. and G.G. Koch. 1977. The measurement of observer agreement for categorical data. biometrics, 33,159-174.

See Also

ecospat.meva.table, ecospat.max.tss, ecospat.plot.tss, ecospat.cohen.kappa, ecospat.max.kappa

Examples

Pred <- ecospat.testData$glm_Agrostis_capillaris
Sp.occ <- ecospat.testData$Agrostis_capillaris
ecospat.plot.kappa(Pred, Sp.occ)

Description

Plot the MESS extrapolation index onto the geographical space.

Usage

ecospat.plot.mess (mess.object, cex=1, pch=15)

Arguments

Value

Returns a plot of the the MESS extrapolation index onto the geographical space.

Author(s)

Blaise Petitpierre [email protected]

References

Elith, J., M. Kearney and S. Phillips. 2010. The art of modelling range-shifting species. Methods in ecology and evolution, 1, 330-342.

See Also

ecospat.mess

Examples

x <- ecospat.testData[c(2,3,4:8)]
proj <- x[1:90,] #A projection dataset.
cal <- x[91:300,] #A calibration dataset

#Create a MESS object 
mess.object <- ecospat.mess (proj, cal, w="default")

#Plot MESS 
ecospat.plot.mess (mess.object, cex=1, pch=15)

Description

Plot a niche z created by ecospat.grid.clim.dyn.

Usage

ecospat.plot.niche (z, title, name.axis1, name.axis2, cor=FALSE)

Arguments

Details

if z is bivariate, a bivariate plot of the niche of the species. if z is univariate, a histogram of the niche of the species

Author(s)

Olivier Broennimann [email protected]

References

Broennimann, O., M.C. Fitzpatrick, P.B. Pearman, B. Petitpierre, L. Pellissier, N.G. Yoccoz, W. Thuiller, M.J. Fortin, C. Randin, N.E. Zimmermann, C.H. Graham and A. Guisan. 2012. Measuring ecological niche overlap from occurrence and spatial environmental data. Global Ecology and Biogeography, 21, 481-497.

See Also

ecospat.grid.clim.dyn

Description

Plot niche categories of niche dynamics between two species densities created by ecospat.grid.clim.dyn.

Usage

ecospat.plot.niche.dyn(z1, z2, intersection = 0, title = "", name.axis1 =
                   "Axis 1", name.axis2 = "Axis 2", interest = 1, col.abn
                   = "lightgreen", col.unf = "green", col.exp = "red",
                   col.stab = "blue", col.pio = "pink", col.NA = "grey",
                   colZ1 = "green3", colZ2 = "red3", transparency = 70,...)

Arguments

Details

Using the default colors, the plot will show the niche stability in blue, niche expansion in red, and niche unfilling in green. The solid contour line indicates the extent of environmental conditions that exists in the native and invaded ranges; the dotted contour line indicates the quantile indicated by the quant argument. The densities of occurrences are displayed using gray shading. This shading shows occurences in the native or invaded range only, as determined by the value of the interest argument.

Author(s)

Blaise Petitpierre [email protected]

Description

Plot a histogram of observed and randomly simulated overlaps, with p-values of equivalency or similarity tests.

Usage

ecospat.plot.overlap.test (x, type, title)

Arguments

Author(s)

Olivier Broennimann [email protected]

References

Broennimann, O., M.C. Fitzpatrick, P.B. Pearman, B. Petitpierre, L. Pellissier, N.G. Yoccoz, W. Thuiller, M.J. Fortin, C. Randin, N.E. Zimmermann, C.H. Graham and A. Guisan. 2012. Measuring ecological niche overlap from occurrence and spatial environmental data. Global Ecology and Biogeography, 21, 481-497.

See Also

ecospat.niche.similarity.test, ecospat.niche.equivalency.test

Description

Plots the values for True skill statistic (TSS) along different thresholds.

Usage

ecospat.plot.tss(Pred, Sp.occ)

Arguments

Value

A plot of the TSS values along different thresholds.

Author(s)

Luigi Maiorano [email protected]

References

Liu, C., P.M. Berry, T.P. Dawson, and R.G. Pearson. 2005. Selecting thresholds of occurrence in the prediction of species distributions. Ecography, 28, 385-393.

Liu, C., M. White and G. Newell. 2013. Selecting thresholds for the prediction of species occurrence with presence-only data. Journal of Biogeography, 40, 778-789.

See Also

ecospat.meva.table, ecospat.max.tss, ecospat.plot.kappa, ecospat.cohen.kappa, ecospat.max.kappa

Examples

Pred <- ecospat.testData$glm_Agrostis_capillaris
Sp.occ <- ecospat.testData$Agrostis_capillaris
ecospat.plot.tss(Pred, Sp.occ)

Description

This function evaluates species distribution models using 100% of the dataset by pooling the different runs of the cross validation as in Collart et al. 2021

Usage

ecospat.poolingEvaluation(fit,
                            calib,
                            resp,
                            AlgoName = NULL,
                            metrics = c("SomersD","AUC","MaxTSS","MaxKappa","Boyce"),
                            ensembleEvaluation=FALSE,
                            w=NULL,
                            metricToEnsemble = "MaxTSS")

Arguments

Details

Because a minimum sample size is needed to evaluate models (see Collart & Guisan,2023; Jiménez-Valverde, 2020), this function uses the approach from Collart et al.(2021), which consists to pool the suitability values of the hold-out data (evaluation dataset) across replicates. As the same data point (presence or absence or background point) is presumably sampled in several replicates, the suitability values for each data point is consequently averaged across replicates where they were sampled. This procedure generates a series of independent suitability values with a size approximately equal (as some data points may not have been sampled by chance in any of the n replicates) to that of the number of data point.

Value

a list containing:

Author(s)

Flavien Collart [email protected]

with contributions of Olivier Broennimann [email protected]

References

Collart, F., & Guisan, A. (2023). Small to train, small to test: Dealing with low sample size in model evaluation. Ecological Informatics. 75, 102106. doi:10.1016/j.ecoinf.2023.102106

Collart, F., Hedenäs, L., Broennimann, O., Guisan, A. and Vanderpoorten, A. 2021. Intraspecific differentiation: Implications for niche and distribution modelling. Journal of Biogeography. 48, 415-426. doi:10.1111/jbi.14009

Jiménez-Valverde, A. 2020. Sample size for the evaluation of presence-absence models. Ecological Indicators. 114, 106289. doi:10.1016/j.ecolind.2020.106289

See Also

ecospat.ESM.EnsembleEvaluation

Examples

set.seed(42)
  resp <- c(rep(1,15),rep(0,85)) #15 presences and 85 absences
  #Generating a fake fit object whith two algorithms and 3 cross-vaidation
  fit <- list(matrix(0,nc=3,nr=100),
              matrix(0,nc=3,nr=100))
  fit[[1]][1:15,] = sample(seq(0,1, by=0.01),15*3,prob=c(rep(1,51),rep(10,50)),replace=TRUE)
  fit[[2]][1:15,] = sample(seq(0,1, by=0.01),15*3,prob=c(rep(1,51),rep(10,50)),replace=TRUE)
  fit[[1]][16:100,] = sample(seq(0,1, by=0.01),85*3,prob=c(rep(10,51),rep(1,50)),replace=TRUE)
  fit[[2]][16:100,] = sample(seq(0,1, by=0.01),85*3,prob=c(rep(10,51),rep(1,50)),replace=TRUE)
  
  # Generating a calib object where 80% of the dataset is used to calibrate the model 
  # and 20% to evaluate it
  calib <- matrix(TRUE,nc=3,nr=100)
  calib[c(sample(1:15,3),sample(16:100,17)),1]=FALSE 
  calib[c(sample(1:15,3),sample(16:100,17)),2]=FALSE 
  calib[c(sample(1:15,3),sample(16:100,17)),3]=FALSE 
  
  # Evaluation via the pooling procedure
  eval <- ecospat.poolingEvaluation(fit=fit,calib=calib,resp=resp,metrics=c("AUC","MaxTSS"))
  eval$evaluations
  
  # Evaluation including the ensemble model based on a weighted mean using MaxTSS
  evalEns <- ecospat.poolingEvaluation(fit=fit,calib=calib,resp=resp,ensembleEvaluation=TRUE,
                                       metrics=c("AUC","MaxTSS"))
  evalEns$evaluations
  
  # Evaluation including the ensemble model based on a mean by giving the same weight for 
  # each algorithm
  evalEns <- ecospat.poolingEvaluation(fit=fit,calib=calib,resp=resp,ensembleEvaluation=TRUE,
                                       metrics=c("AUC","MaxTSS"),w=c(1,1))
  evalEns$evaluations