downscale {downscale}

Model area of occupancy against grain size for downscaling

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 (and also see hui.downscale for downscaling using the Hui model). 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. 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 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)