Model area of occupancy against grain size for downscaling
Description
Fits the log observed proportion of occupancies against log grain size (cell area) for coarsescale 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
. Presenceabsence atlas data can be prepared for downscaling using upgrain
.
Usage
1 2 
Arguments
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 
Details
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 multidimensional integration which may be timeconsuming. 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 = 1e8  
"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 = 1e8;  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.
Value
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 
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, 10041014.
Barwell, L.J., Azaele, S., Kunin, W.E., & Isaac, N.J.B. (2014). Can coarsegrain patterns in insect atlas data predict local occupancy? Diversity and Distributions 20, 895907.
See Also
See upgrain
for the preparation of presenceabsence 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.
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 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48  ## 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)
## 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)
