Create ensemble of SDM predictions — ensemble

Create a weighted or unweighted ensemble of SDM predictions, including associated uncertainty values

Usage

ensemble_create(x, x.idx, w = NULL, x.var.idx = NULL, ...)

# S3 method for class 'sf'
ensemble_create(x, x.idx, w = NULL, x.var.idx = NULL, ...)

# S3 method for class 'data.frame'
ensemble_create(x, x.idx, w = NULL, x.var.idx = NULL, ...)

Arguments

x: object of class sf or class data.frame
x.idx: vector of column names or numerical indices; indicates which columns in x will be used to create the ensemble
w: weights for the ensemble; either a numeric vector the same length as x or a data frame (or tibble) with the same number of rows as x and ncol(w) == length(x.idx). If w is a numeric vector, its values (i.e. the weights) must sum to 1. The default value is 1 / length(x.idx), i.e. an unweighted ensemble
x.var.idx: vector of column names or column indices; indicates columns in x with variance values with which to calculate uncertainty values for the ensemble. If x.var.idx is specified, it must be the same length as x.idx. Use x.var.idx = NULL (the default) if none of the predictions have associated uncertainty values; in this case the uncertainty values for the ensemble will be calculated using the among-model uncertainty. See the 'Details' section for more information
...: Arguments to be passed to methods; specifically designed for passing na.rm argument to sum

Value

An object of the same class as x with two columns appended to the data frame:

'Pred_ens' - The ensemble predictions
'Var_ens' - The variance of the ensemble predictions, calculated using either the within-model uncertainty (if x.var.idx is specified) or the among-model uncertainty (if x.var.idx is NULL)

Note that all other columns of x will be included in the returned object. Also, if x is of class sf then 1) the geometry list-column will be the last column of the returned object and 2) the agr attribute will be set as 'constant' for 'Pred_ens' and 'Var_ens'

Details

ensemble_create is designed to be used after overlaying predictions with overlay_sdm and (if desired) rescaling the overlaid predictions with ensemble_rescale.

This function implements ensemble methods provided in eSDM_GUI. Note that it does not implement regional exclusion, which must be done manually if not using the GUI.

Ensemble uncertainty is calculated using either the within-model uncertainty (if x.var.idx is specified) or the among-model uncertainty (if x.var.idx is NULL). See the eSDM GUI manual for applicable formulas.

Examples

ensemble_create(preds.1, c("Density", "Density2"), c(0.2, 0.8))
#> Simple feature collection with 325 features and 6 fields
#> Attribute-geometry relationships: constant (6)
#> Geometry type: POLYGON
#> Dimension:     XY
#> Bounding box:  xmin: -123 ymin: 32 xmax: -117 ymax: 35.03686
#> Geodetic CRS:  WGS 84
#> First 10 features:
#>       Density  Density2        Var1         Var2  Pred_ens     Var_ens
#> 1  0.18149697 0.7048871 0.004881167 5.813315e-04 0.6002090 0.043829949
#> 2  0.02813584 0.4876443 0.008067182 4.260565e-04 0.3957426 0.033783679
#> 3  0.06602004 0.3539495 0.002044914 8.936224e-03 0.2963636 0.013264536
#> 4  0.02904423 0.7001870 0.004061446 4.281218e-04 0.5659584 0.072069219
#> 5  0.03662517 0.6350484 0.009396155 6.683912e-03 0.5153638 0.057297659
#> 6  0.04675287 0.8962417 0.008085898 9.530925e-05 0.7263440 0.115461011
#> 7  0.02349130 0.2610464 0.008159037 6.253449e-03 0.2135354 0.009029186
#> 8  0.02890871 0.9543314 0.008667279 1.936805e-03 0.7692468 0.137025134
#> 9  0.04262853 0.2411099 0.001207384 4.332171e-03 0.2014136 0.006303176
#> 10 0.14753231 0.4311854 0.003063388 7.799161e-03 0.3744547 0.012873448
#>                          geometry
#> 1  POLYGON ((-123 32, -122.875...
#> 2  POLYGON ((-122.625 32.00828...
#> 3  POLYGON ((-122.375 32.01319...
#> 4  POLYGON ((-122.125 32.0176,...
#> 5  POLYGON ((-121.875 32.02153...
#> 6  POLYGON ((-121.625 32.02496...
#> 7  POLYGON ((-121.375 32.0279,...
#> 8  POLYGON ((-121.125 32.03036...
#> 9  POLYGON ((-120.875 32.03232...
#> 10 POLYGON ((-120.625 32.03379...
ensemble_create(preds.1, 1:2, c(0.2, 0.8), c("Var1", "Var2"))
#> Simple feature collection with 325 features and 6 fields
#> Attribute-geometry relationships: constant (6)
#> Geometry type: POLYGON
#> Dimension:     XY
#> Bounding box:  xmin: -123 ymin: 32 xmax: -117 ymax: 35.03686
#> Geodetic CRS:  WGS 84
#> First 10 features:
#>       Density  Density2        Var1         Var2  Pred_ens      Var_ens
#> 1  0.18149697 0.7048871 0.004881167 5.813315e-04 0.6002090 0.0005672988
#> 2  0.02813584 0.4876443 0.008067182 4.260565e-04 0.3957426 0.0005953634
#> 3  0.06602004 0.3539495 0.002044914 8.936224e-03 0.2963636 0.0058009796
#> 4  0.02904423 0.7001870 0.004061446 4.281218e-04 0.5659584 0.0004364558
#> 5  0.03662517 0.6350484 0.009396155 6.683912e-03 0.5153638 0.0046535501
#> 6  0.04675287 0.8962417 0.008085898 9.530925e-05 0.7263440 0.0003844338
#> 7  0.02349130 0.2610464 0.008159037 6.253449e-03 0.2135354 0.0043285688
#> 8  0.02890871 0.9543314 0.008667279 1.936805e-03 0.7692468 0.0015862463
#> 9  0.04262853 0.2411099 0.001207384 4.332171e-03 0.2014136 0.0028208846
#> 10 0.14753231 0.4311854 0.003063388 7.799161e-03 0.3744547 0.0051139986
#>                          geometry
#> 1  POLYGON ((-123 32, -122.875...
#> 2  POLYGON ((-122.625 32.00828...
#> 3  POLYGON ((-122.375 32.01319...
#> 4  POLYGON ((-122.125 32.0176,...
#> 5  POLYGON ((-121.875 32.02153...
#> 6  POLYGON ((-121.625 32.02496...
#> 7  POLYGON ((-121.375 32.0279,...
#> 8  POLYGON ((-121.125 32.03036...
#> 9  POLYGON ((-120.875 32.03232...
#> 10 POLYGON ((-120.625 32.03379...
ensemble_create(data.frame(a = 1:5, b = 3:7), c(1, 2))
#>   a b Pred_ens Var_ens
#> 1 1 3        2       1
#> 2 2 4        3       1
#> 3 3 5        4       1
#> 4 4 6        5       1
#> 5 5 7        6       1

weights.df <- data.frame(runif(325), c(rep(NA, 100), runif(225)))
ensemble_create(preds.1, c("Density", "Density2"), weights.df, na.rm = TRUE)
#> Simple feature collection with 325 features and 6 fields
#> Attribute-geometry relationships: constant (6)
#> Geometry type: POLYGON
#> Dimension:     XY
#> Bounding box:  xmin: -123 ymin: 32 xmax: -117 ymax: 35.03686
#> Geodetic CRS:  WGS 84
#> First 10 features:
#>       Density  Density2        Var1         Var2   Pred_ens Var_ens
#> 1  0.18149697 0.7048871 0.004881167 5.813315e-04 0.18149697       0
#> 2  0.02813584 0.4876443 0.008067182 4.260565e-04 0.02813584       0
#> 3  0.06602004 0.3539495 0.002044914 8.936224e-03 0.06602004       0
#> 4  0.02904423 0.7001870 0.004061446 4.281218e-04 0.02904423       0
#> 5  0.03662517 0.6350484 0.009396155 6.683912e-03 0.03662517       0
#> 6  0.04675287 0.8962417 0.008085898 9.530925e-05 0.04675287       0
#> 7  0.02349130 0.2610464 0.008159037 6.253449e-03 0.02349130       0
#> 8  0.02890871 0.9543314 0.008667279 1.936805e-03 0.02890871       0
#> 9  0.04262853 0.2411099 0.001207384 4.332171e-03 0.04262853       0
#> 10 0.14753231 0.4311854 0.003063388 7.799161e-03 0.14753231       0
#>                          geometry
#> 1  POLYGON ((-123 32, -122.875...
#> 2  POLYGON ((-122.625 32.00828...
#> 3  POLYGON ((-122.375 32.01319...
#> 4  POLYGON ((-122.125 32.0176,...
#> 5  POLYGON ((-121.875 32.02153...
#> 6  POLYGON ((-121.625 32.02496...
#> 7  POLYGON ((-121.375 32.0279,...
#> 8  POLYGON ((-121.125 32.03036...
#> 9  POLYGON ((-120.875 32.03232...
#> 10 POLYGON ((-120.625 32.03379...