downscale (version 5.1.4)

ensemble.downscale: 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)

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.

Arguments

occupancies

Either a data frame containing two columns or an object of class "upgrain" from the upgrain function. If using the Hui model (or model = "all") occupancies must be of class "upgrain". If using a data frame the first column must be the grain sizes (cell area in squared units e.g. \(km^2\)). The second column is the proportion of occupancies at each grain size.

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 Hui model.

tolerance_mod

only applicable for the Thomas model. The tolerance used during integration in the Thomas model during optimisation of parameters. Lower numbers allow for greater accuracy but require longer processing times (default = 1e-6).

tolerance_pred

only applicable for the Thomas model. The tolerance used during the prediction stage.

tolerance_hui

only applicable for the Hui model. The tolerance used during integration in the Thomas model during optimisation of parameters. Lower numbers allow for greater accuracy but require longer processing times (default = 1e-6).

models

vector of chosen downscaling models. Default models = "all" runs all available models. See downscale for list of available models.

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 Details for information on the parameters and how to specify them).

plot

if TRUE predictions of all models (red) are plotted against grain size along with the mean of all models (grey) and observed occupancies (black).

verbose

if TRUE prints updates on modelling status.

Author

Charles Marsh <> with input from Louise Barwell.

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

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)