| ensemble.downscale {downscale} | R Documentation |
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
ensemble.downscale(occupancies, new.areas, extent, cell.width = NULL,
models = "all", tolerance_mod = 1e-6, tolerance_pred = 1e-6,
tolerance_hui = 1e-6, starting_params = NULL, plot = TRUE,
verbose = TRUE)
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 <charlie.marsh@mailbox.org> 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.
Groom, Q., Marsh, C.J., Gavish, Y. Kunin, W.E. (2018). How to predict fine resolution occupancy from coarse occupancy data, Methods in Ecology and Evolution. 9(11), 2273-2284.
Marsh, C.J, Barwell, L.J., Gavish, Y., Kunin, W.E. (2018). downscale: An R package for downscaling species occupancy from coarse-grain data to predict occupancy at fine-grain sizes, Journal of Statistical Software 86(Code Snippet 3), 1-20.
Marsh, C.J, Gavish, Y., Kunin, W.E., Brummitt N.A. (2019). Mind the gap: Can downscaling Area of Occupancy overcome sampling gaps when assessing IUCN Red List status?, Diversity and Distributions 25, 1832-1845.
See Also
See upgrain for creating objects of class "upgrain". See downscale and predict.downscale, and link{hui.downscale} for downscaling models individually.
Examples
## 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 "x", "y"
## 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)