# Ensemble modelling of multiple downscaling functions

### Description

Predict area of occupancy at fine grain sizes for multiple downscaling methods using `downscale`

and `predict.downscale`

. Occupancies are converted to area of occupancy (AOO) by multiplying by the total extent. The mean of the logged predicted occupancies of all models is then calculated.

### Usage

1 2 3 4 |

### Arguments

`occupancies` |
Either a data frame containing two columns or an object of class "upgrain" from the upgrain function. If using the |

`new.areas` |
vector of grain sizes (in squared units e.g. km^2) for which area of occupancy will be predicted. |

`extent` |
total area in same units as occupancy. If using an object of class "upgrain", this is automatically inputted. |

`cell.width` |
the cell width of the atlas data. Only required for |

`tolerance_mod` |
only applicable for the |

`tolerance_pred` |
only applicable for the |

`tolerance_hui` |
only applicable for the |

`models` |
vector of chosen downscaling models. Default |

`starting_params` |
Starting values for model parameters if a model is not converging sufficiently. A list where each model to be specified is a list of parameter values. The parameter names must be the same for the default values (see |

`plot` |
if |

`verbose` |
if |

### Details

Ten downscaling models are available: `"Nachman"`

, `"PL"`

, `"Logis"`

, `"Poisson"`

, `"NB"`

, `"GNB"`

, `"INB"`

, `"FNB"`

, `"Thomas"`

and `"Hui"`

. They can be input in any order, or all models run through `models = "all"`

. If the `Hui`

model is included the input data must be an object of class `"upgrain"`

generated through `upgrain`

. See `downscale`

and `hui.downscale`

for more details of the available models.

The optimisation procedure requires initial starting values for all model parameters. In most cases the default values should work, however if one or more models are not converging adequately it is possible to input the starting parameters. For each model we wish to specify, the parameters must be in the form of a list with the same parameter names as in the table below. `starting_params`

is then a list of these lists - the names of the lists are the same as the models. For example, if we wish to specify the starting parameters for the Nachman model and the Generalised Negative Binomial model the code would be:

```
starting_params = list(Nachman = list("C" = 0.1, "z" = 0.01),
GNB = list("C" = 0.1, "z" = 1, "k" = 0.01))
```

Please take particular note of captials. The default starting parameters are:

`"Nachman"` | C = 0.01; | z = 0.01 | ||||||||

`"PL"` | C = 0.01; | z = 0.01 | ||||||||

`"Logis"` | C = 0.01; | z = 0.01 | ||||||||

`"Poisson"` | gamma = 1e-8 | |||||||||

`"NB"` | C = 0.01; | k = 0.01 | ||||||||

`"GNB"` | C = 0.00001; | z = 1; | k = 0.01 | |||||||

`"INB"` | C = 1; | gamma = 0.01; | b = 0.1 | |||||||

`"FNB"` | N = 10; | k = 10 | ||||||||

`"Thomas"` | rho = 1e-8; | mu = 10; | sigma = 1 | |||||||

### Value

Returns a list of two data frames:
`Occupancy`

= proportion of occupancies;
`AOO`

= occupancies converted to area of occupancy.

In each data frame the first column `cell.area`

are the grain sizes used for predictions. The final column `Means`

are the mean of the logged predictions of all models for each grain size. Intermediate columns are the predicted occupancies for the selected downscaling models.

### Author(s)

Charles Marsh <charliem2003@gmail.com> with input from Louise Barwell.

### References

Azaele, S., Cornell, S.J., & Kunin, W.E. (2012). Downscaling
species occupancy from coarse spatial scales. *Ecological
Applications* 22, 1004-1014.

Barwell, L.J., Azaele, S., Kunin, W.E., & Isaac, N.J.B. (2014).
Can coarse-grain patterns in insect atlas data predict local occupancy?
*Diversity and Distributions* 20, 895-907.

### See Also

See `upgrain`

for creating objects of class `"upgrain"`

. See `downscale`

and `predict.downscale`

, and `link{hui.downscale}`

for downscaling models individually.

### Examples

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | ```
## example species data
data.file <- system.file("extdata", "atlas_data.txt", package = "downscale")
atlas.data <- read.table(data.file, header = TRUE)
## if the input data is a data frame it must have the columns "lon", "lat"
## and "presence"
head(atlas.data)
## upgrain data (using All Samples threshold)
occupancy <- upgrain(atlas.data,
cell.width = 10,
scales = 3,
method = "All_Sampled",
plot = FALSE)
## ensemble downscaling with an object of class upgrain
ensemble.downscale(occupancies = occupancy,
new.areas = c(1, 2, 5, 15, 50, 100, 400, 1600, 6400),
cell.width = 10,
models = c("Nachman", "PL", "Logis", "GNB", "FNB", "Hui"),
plot = TRUE)
## ensemble modelling with data frame of occupancies (not applicable for Hui
## model) with hypothetical species occupancy data
occupancy.dd <- data.frame(Cell.areas = c(100, 400, 1600, 6400),
Occupancy = c(0.16, 0.36, 0.59, 0.86))
## now extent must be specified (but cell.width not needed)
ensemble.downscale(occupancies = occupancy.dd,
new.areas = c(1, 2, 5, 15, 50, 100, 400, 1600, 6400),
extent = 384000,
models = c("Nachman", "PL", "Logis", "GNB", "FNB"),
plot = TRUE)
``` |