predict.downscale {downscale}

Predict occupancy at fine grain sizes

Description

Predict proportion of occupancy at fine grain sizes using parameters from an object of class downscale estimated from coarse grain sizes using downscale. Proportion of occupancy is converted to area of occupancy (AOO) by multiplying by the extent. There is also a simple plot function.

Usage

## S3 method for class 'downscale'
predict(object, new.areas, tolerance = 1e-6, plot = TRUE, ...)

Arguments

object

a fitted object of class 'downscale'.

new.areas

vector of grain sizes (in squared units e.g. km^2) for which area of occupancy will be predicted.

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

plot

if plot = TRUE (default) plots observed and predicted occupancies against grain size on a log-log plot using plot.predict.downscale.

...

arguments, including graphical parameters for plot.predict.downscale, passed to other methods.

Details

The function takes the parameters for a downscaling model estimated through downscale and uses the model to predict area of occupancy at finer grain sizes. See downscale for details on the downscaling models and their parameterisation. Plotting can be called directly from predict.downscale or from plot.predict.downscale.

For predictions using the Thomas model, if the tolerance value is not sufficiently low it may lead to innacurate results. Typically, this will be indicated by fine grain sizes with higher predicted occupancies than those at larger grain sizes. In these cases try a lower tolerance value in the arguments.

Value

predict returns an object of class 'predict.downscale' with three objects:

model

Downscaling model used.

predicted

Data frame containing two columns:

Cell.area		Grain sizes for which occupancies have been estimated
Occupancy		Predicted proportion of occupancy for each grain size
AOO		Predicted area of occupancy (proportion of area occupancy multiplied by extent)

observed

Data frame containing two columns:

Cell.area		Grain sizes for which occupancies have been observed
Occupancy		Observed proportion of occupancy for each grain size

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.

See Also

See downscale for estimating parameters of a downscaling function from observed occupancies at coarse grain sizes.

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

## Predictions occupancy at finer scales
logis.pred <- predict(logis,
                      new.areas = c(1, 2, 5, 25, 100),
                      plot = FALSE)
logis.pred
plot(logis.pred)

## It can also be a good idea to include the observed cell sizes in the
## predictions to observe the fit of the model (this time run plot = TRUE)
predict(logis,
        new.areas = c(1, 2, 5, 25, 100, 400, 1600, 6400),
        plot = TRUE)