Description

BIOMOD_EnsembleModeling combines models and make ensemble predictions built with BIOMOD_Modeling. The ensemble predictions can also be evaluated against the original data given to BIOMOD_Modeling. Biomod2 proposes a range of options to build ensemble models and predictions and to assess the modeling uncertainty. The created ensemble models can then be used to project distributions over space and time as classical biomod2 models.

Usage

Arguments

Details

1. Models sub-selection (chosen.models)

   Useful to exclude some models that have been selected in the previous steps (modeling.output). This vector of model names can be access applying get_built_models to your modeling.output data. It makes easier the selection of models. The default value (i.e. ‘all’) will kept all available models.

2. Models assembly rules (em.by)

   Please refer to EnsembleModelingAssembly vignette that is dedicated to this parameter.

   5 different ways to combine models can be considered. You can make ensemble models considering :

   • Dataset used for models building (Pseudo Absences dataset and repetitions done): 'PA_dataset+repet'

   • Dataset used and statistical models : 'PA_dataset+algo'

   • Pseudo-absences selection dataset : 'PA_dataset'

   • Statistical models : 'algo'

   • A total consensus model : 'all'

   The value chosen for this parameter will control the number of ensemble models built. If no evaluation data was given the at BIOMOD_FormatingData step, some ensemble models evaluation may be a bit unfair because the data that will be used for evaluating ensemble models could differ from those used for evaluate BIOMOD_Modeling models (in particular, some data used for 'basal models' calibration can be re-used for ensemble models evaluation). You have to keep it in mind ! (EnsembleModelingAssembly vignette for extra details)

3. Evaluation metrics

   • eval.metric

     The selected metrics here are necessary the ones chosen at the BIOMOD_Modeling step. If you select several, ensembles will be built according to each of them. The chosen metrics will be used at different stages in this function :

     1. to remove ‘bad models’ (having a score lower than eval.metric.quality.threshold (see bellow))

     2. to make the binary transformation needed for committee averaging computation

     3. to weight the models in the probability weighted mean model

     4. to test (and/or evaluate) your ensemble-models forecasting ability (at this step, each ensemble-model (ensemble will be evaluated according to each evaluation metric)

   • eval.metric.quality.threshold

     You have to give as many threshold as eval.metric you have selected. If you have selected several evaluation metrics , take care to ensure that the order of thresholds matches the order of eval.metric. All models having a score lower than these quality thresholds will not be kept for building ensemble-models.

4. Ensemble-models algorithms

   1. Mean of probabilities (prob.mean)

      This ensemble-model corresponds to the mean probabilities over the selected models.

   2. Coefficient of variation of Probabilities (prob.cv)

      This ensemble-model corresponds to the coefficient of variation (i.e. sd / mean) of the probabilities over the selected models. This model is not scaled. It will be evaluated like all other ensemble-models although this interpretation is obviously different. CV is a measure of uncertainty rather a measure of probability of occurrence. If the CV gets a high evaluation score it means that the uncertainty is high where the species is observed (which might not be a good feature of the models). The lower is the score, the better are the models. CV is a nice complement to the mean probability.

   3. Confidence interval (prob.ci & prob.ci.alpha) This is the confidence interval around the mean probability (see above). This is also a nice complement to the mean probability. Two ensemble-models will be built if prob.ci is TRUE :

      • The upper one (there is less than a 100*prob.ci.alpha/2 % of chance to get probabilities upper than the given ones)

      • The lower one (there is less than a 100*prob.ci.alpha/2 % of chance to get probabilities lower the than given ones)

      These intervals are calculated with the following function :

      I_c = [ \bar{x} - \frac{t_α sd }{ √{n} }; \bar{x} + \frac{t_α sd }{ √{n} }]

   4. Median of probabilities (prob.median)

      This ensemble-model corresponds to the median probability over the selected models. The median is less sensitive to outliers than the mean. In practical terms, calculating the median requires more time and memory than the mean (or even weighting mean) as it asks to load all predictions to then extract the median. It may need to be considered in case of large dataset.

   5. Models committee averaging (committee.averaging)

      To do this model, the probabilities from the selected models are first transformed into binary data according to the thresholds defined at BIOMOD_Modeling step (maximizing evaluation metric score over ‘testing dataset’ ). The committee averaging score is then the average of binary predictions. It is built on the analogy of a simple vote. Each model vote for the species being ether present or absent. For each site, the sum of 1 is then divided by the number of models. The interesting feature of this measure is that it gives both a prediction and a measure of uncertainty. When the prediction is close to 0 or 1, it means that all models agree to predict 0 and 1 respectively. When the prediction is around 0.5, it means that half the models predict 1 and the other half 0.

   6. Weighted mean of probabilities (prob.mean.weight & prob.mean.weight.decay)

      This algorithm return the mean weighted (or more precisely this is the weighted sum) by the selected evaluation method scores (better a model is, more importance it has in the ensemble). The scores come from BIOMOD_Modeling step.

      The prob.mean.weight.decay is the ratio between a weight and the following or prior one. The formula is : W = W(-1) * prob.mean.weight.decay. For example, with the value of 1.6 and 4 weights wanted, the relative importance of the weights will be 1 /1.6/2.56(=1.6*1.6)/4.096(=2.56*1.6) from the weakest to the strongest, and gives 0.11/0.17/0.275/0.445 considering that the sum of the weights is equal to one. The lower the prob.mean.weight.decay, the smoother the differences between the weights enhancing a weak discrimination between models.

      The value 'proportional' (default) is also possible for the prob.mean.weight.decay: the weights are awarded for each method proportionally to their evaluation scores. The advantage is that the discrimination is more fair than with the prob.mean.weight.decay. In the latter case, close scores can strongly diverge in the weights they are awarded, when the proportional method will consider them as being fairly similar in prediction quality and award them a similar weight. It is also possible to define a function as prob.mean.weight.decay argument. In this case the given function will be applied to models scores to transform them into weights that will be used for weighted mean ensemble model building. For instance if you specified function(x){x^2} as prob.mean.weight.decay, the squared of evaluation score of each model will be used to weight formal models predictions.

Value

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

You can access to evaluation scores with the get_evaluations function and to the built models names with the get_built_models function (see example).

Note

Models are now combined by repetition, other way to combine them (e.g. by Models, all together...) will be available soon

Author(s)

Damien Georges & Wilfried Thuiller with participation of Robin Engler

See Also

BIOMOD_Modeling, BIOMOD_Projection, BIOMOD_EnsembleForecasting

Examples