downscale: Model area of occupancy against grain size for downscaling

In downscale: Downscaling Species Occupancy

Description

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.

Usage

downscale(occupancies, model, extent = NULL, tolerance = 1e-06,
          starting_params = NULL)

Arguments

occupancies	Either a data frame containing two columns or an object of class "upgrain" from the upgrain function. 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.
model	selected downscaling model, chosen from one of "Nachman", "PL", "Logis", "Poisson", "NB", "GNB", "INB", "FNB", "Thomas". See Details below for model descriptions.
extent	total area in same units as occupancy. If using an object of class "upgrain", this is automatically inputted.
tolerance	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).
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 for information on the parameters).

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

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: Cell.area Grain sizes for which occupancy have been observed. Occupancy Observed area of occupancy for each grain size.
extent	Only for FNB and Thomas models.

Author(s)

Charles Marsh <[e-mail]> 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. In press.

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.

See Also

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.

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)

## 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)

Example output

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.093983e-28  1.666676e-05 -3.683285e-01 

$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"

downscale documentation built on May 2, 2019, 5:24 p.m.