downscale {downscale} | R Documentation |
Fits the log observed proportion of occupancies against log grain size (cell area) for coarse-scale data (typically atlas data) for nine commonly used downscaling models (see Azaele et al. 2012 and Barwell et al. 2014). See hui.downscale
for downscaling using the Hui model. The parameters of the fitted models may then be used to estimate the area of occupancy at finer grain sizes than the observed data using predict.downscale
. Presence-absence atlas data can be prepared for downscaling using upgrain
.
downscale(occupancies, model, extent = NULL, tolerance = 1e-06,
starting_params = NULL)
occupancies |
Either a data frame containing two columns or an object of class |
model |
selected downscaling model, chosen from one of |
extent |
total area in same units as occupancy. If using an object of class |
tolerance |
only applicable for the |
starting_params |
a list of starting values for model parameters. Useful if the default values are not converging during optimisation. The parameter names must be the same for the default values (see |
Nine downscaling models are available. area
is the grain size (cell area) and extent
the total area in the same units:
"Nachman" | Nachman model | log(1 - exp(-C * area ^ z)) | |
"PL" | Power law model | log(C * area ^ z) | |
"Logis" | Logistic model | log((C * (area ^ z)) / (1 + (C * (area ^ z)))) | |
"Poisson" | Poisson model | log(1 - (exp(-gamma * area))) | |
"NB" | Negative binomial model | log(1 - (1 + (gamma * area) / k) ^ -k) | |
"GNB" | Generalised negative binomial model | log(1 - (1 + (C * area ^ z) / k) ^ -k) | |
"INB" | Improved negative binomial model | log(1 - ((C * area ^ (b - 1)) ^ ((gamma * area) / (1 - C * area ^ (b - 1))))) | |
"FNB" | Finite negative binomial model | log(1 - ((gamma(N + ((extent * k) / area) - k) * gamma(extent * k) / area) / (gamma(N + ((extent * k) / area)) * gamma(((extent * k) / area) - k))) | |
"Thomas" | Thomas model | see below | |
The finite negative binomial model ("FNB"
) incorporates several gamma
functions. This may result in integers larger than is possible to store in
R. Therefore multiple precision floating point numbers (mpfr
function in package Rmpfr) are used to make calculations possible.
The Thomas model incorporates spatial point processes in order to estimate species aggregations. This involves multi-dimensional integration which may be time-consuming. Users can alter the tolerance value during the integration process - a smaller value will give more accurate estimates but longer processing times.
The optimisation procedure requires initial starting values for all model parameters. In most cases the default values should work, however if the model is not converging adequately it is possible to input the starting parameters. The parameters must be in the form of a list with the same parameter names as in the table below. For example for the Nachman
model the code would be starting_params = list("C" = 0.1, "z" = 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" | gamma = 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 | |||||||
NOTE: for downscaling it is important that occupancies above the scale of saturation (the grain size at which all cells are occupied) and the scale of saturation (the grain size where only a single cell is occupied) are not included for modelling. The downscale
functions will automatically set these occupancies to NA.
downscale
returns an object of class "downscale"
containing
four objects:
model |
Downscaling model selected. | |||||||
pars |
Estimated parameters for the downscaling model. | |||||||
observed |
Data frame containing two columns:
| |||||||
extent |
Only for |
Charles Marsh <charliem2003@gmail.com> with input from Louise Barwell.
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, Code Snippets 86(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 upgrain
for the preparation of presence-absence atlas data to occupancy data at several spatial scales.
The function output may be used as the input for predict.downscale
for extrapolating downscaling functions to smaller grain sizes using the estimated parameters from the downscale output.
See hui.downscale
for downscaling using the Hui model.
## 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)
## explore thresholds using upgrain.threshold
thresh <- upgrain.threshold(atlas.data = atlas.data,
cell.width = 10,
scales = 3,
thresholds = seq(0, 1, 0.1))
## upgrain data (using All Sampled threshold)
occupancy <- upgrain(atlas.data,
cell.width = 10,
scales = 3,
method = "All_Sampled")
## Logistic model
(logis <- downscale(occupancies = occupancy,
model = "Logis"))
### predict occupancy at finer grain sizes
pred <- predict(logis,
new.areas = c(1, 2, 5, 25, 100, 400, 1600, 6400))
### Plot predictions
plot(pred)
## Improved Negative Binomial model
(inb <- downscale(occupancies = occupancy,
model = "INB"))
## Specifying the starting parameters (gives a poorer fit in this case)
new.params <- list("C" = 0.1, "gamma" = 0.00001, "b" = 0.1)
(inb.new <- downscale(occupancies = occupancy,
model = "INB",
starting_params = new.params))
## plot the predictions of two FNB models using predict.downscale
predict(inb,
new.areas = c(1, 2, 5, 25, 100, 400, 1600, 6400),
plot = TRUE)
predict(inb.new,
new.areas = c(1, 2, 5, 25, 100, 400, 1600, 6400),
plot = TRUE)