Description Usage Arguments Details Value Author(s) References See Also Examples
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
.
1 2 
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 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"  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 = 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.
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, 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.
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), 22732284.
Marsh, C.J, Barwell, L.J., Gavish, Y., Kunin, W.E. (2018). downscale: An R package for downscaling species occupancy from coarsegrain data to predict occupancy at finegrain sizes, Journal of Statistical Software, Code Snippets 86(3), 120.
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, 18321845.
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.
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 "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)

Loading required package: raster
Loading required package: sp
x y presence
1 8170 10 0
2 8130 20 0
3 8140 20 0
4 8160 20 0
5 8170 20 0
6 8140 30 0
Loading required namespace: rgeos
Failed with error: 'there is no package called 'rgeos''
Loading required namespace: rgeos
Failed with error: 'there is no package called 'rgeos''
In addition: Warning message:
In raster::rasterToPolygons(boundary_raster, dissolve = TRUE) :
package rgeos is not available. Cannot dissolve
Loading required namespace: rgeos
Failed with error: 'there is no package called 'rgeos''
In addition: Warning message:
In raster::rasterToPolygons(max_raster_thresh_extent, dissolve = TRUE) :
package rgeos is not available. Cannot dissolve
Loading required namespace: rgeos
Failed with error: 'there is no package called 'rgeos''
In addition: Warning message:
In raster::rasterToPolygons(max_raster_thresh_extent, dissolve = TRUE) :
package rgeos is not available. Cannot dissolve
Loading required namespace: rgeos
Failed with error: 'there is no package called 'rgeos''
In addition: Warning message:
In raster::rasterToPolygons(max_raster_thresh_extent, dissolve = TRUE) :
package rgeos is not available. Cannot dissolve
Warning message:
In raster::rasterToPolygons(max_raster_thresh_extent, dissolve = TRUE) :
package rgeos is not available. Cannot dissolve
$model
[1] "Logis"
$pars
C z
0.06367064 0.38279174
$observed
Cell.area Occupancy
1 100 0.2713542
2 400 0.3916667
3 1600 0.4958333
4 6400 0.6666667
$extent
[1] 384000
attr(,"class")
[1] "downscale"
$model
[1] "INB"
$pars
C gamma b
451.695529 5.362129 1.778826
$observed
Cell.area Occupancy
1 100 0.2713542
2 400 0.3916667
3 1600 0.4958333
4 6400 0.6666667
$extent
[1] 384000
attr(,"class")
[1] "downscale"
$model
[1] "INB"
$pars
C gamma b
7.093983e28 1.666676e05 3.683285e01
$observed
Cell.area Occupancy
1 100 0.2713542
2 400 0.3916667
3 1600 0.4958333
4 6400 0.6666667
$extent
[1] 384000
attr(,"class")
[1] "downscale"
$model
[1] "INB"
$predicted
Cell.area Occupancy AOO
1 1 0.07014743 26936.61
2 2 0.08805963 33814.90
3 5 0.11742946 45092.91
4 25 0.18825996 72291.83
5 100 0.27303399 104845.05
6 400 0.38214624 146744.15
7 1600 0.51314904 197049.23
8 6400 0.65599949 251903.80
$observed
Cell.area Occupancy
1 100 0.2713542
2 400 0.3916667
3 1600 0.4958333
4 6400 0.6666667
attr(,"class")
[1] "predict.downscale"
$model
[1] "INB"
$predicted
Cell.area Occupancy AOO
1 1 0.001041349 399.8780
2 2 0.002113163 811.4545
3 5 0.005378463 2065.3299
4 25 0.027497372 10558.9910
5 100 0.108358858 41609.8016
6 400 0.375879770 144337.8318
7 1600 0.855753764 328609.4455
8 6400 0.999646374 383864.2078
$observed
Cell.area Occupancy
1 100 0.2713542
2 400 0.3916667
3 1600 0.4958333
4 6400 0.6666667
attr(,"class")
[1] "predict.downscale"
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.