hui.downscale {downscale}R Documentation

Predict occupancy at fine grain sizes using the Hui model


Predict area of occupancy at fine grain sizes from atlas data using the Hui model. There is also a simple plot function. Essentially the function is equivalent to downscale and predict.downscale combined.


hui.downscale(, cell.width, new.areas, extent = NULL,
              tolerance = 1e-6, plot = FALSE)


either an object of class "upgrain"; or a raster file where 1 = presence and 0 = absence; or an object of class SpatialPointsDataFrame atlas data where the data frame contains a single column of presence (1) and absences (0); or a data frame containing these columns: presence = presence - absence data; x = easting coordinates of cells; y = northing coordinates of cells.


the cell width of the atlas data.


vector of grain sizes as cell area (in same units as cell.width but squared e.g. km^2) at fine scales for model prediction.


the extent of the atlas data in same units as cell.areas. If the input data is of class "upgrain" this can be left as NULL.


tolerance for root solving to estimate probability of absence at the fine scale (default = 1e-6).


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


The function estimates fine-scale occupancy from atlas-scale data using the model developed by Hui. The model requires presence-absence data only at a single scale (the atlas scale) and calculates the probability of occupancy at a fine scale through the conditional probability that at the atlas scale a randomly chosen cell adjacent to an occupied cell is also occupied. Plotting can be called directly from hui.downscale or from plot.predict.downscale.

NOTE: if comparing occupancy predictions from the Hui model with those from other models using downscale it is important that the atlas data used here is the standardised atlas data whose extent is the same as the largest grain size used in the other models. This ensures that all models are modelling the proportion of occupancy of the same extent. This standardised atlas raster can be obtained through the upgrain function (see vignette("Upgraining", package = "downscale") for more details.


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


Downscaling model used (Hui model in this case).


Data frame containing two columns:

Cell.area Grain sizes for which occupancy have been estimated
Occupancy Predicted area of occupancy for each grain size

Data frame containing two columns:

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


Charles Marsh <> with input from Louise Barwell and Cang Hui.


Hui, C. (2009). On the scaling patterns of species spatial distribution and association. Journal of Theoretical Biology 261, 481-487.

Hui, C., McGeoch, M.A., & Warren, M. (2006). A spatially explicit approach to estimating species occupancy and spatial correlation. Journal of Animal Ecology 7, 140-147.

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 86(Code Snippet 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 downscale for estimating parameters of a downscaling function from observed occupancies at coarse grain sizes using other downscaling models.

See upgrain for creating extent-standardised atlas data as an input.

See ensemble.downscale for ensemble modelling of multiple downscaling models.


## example species data
data.file <- system.file("extdata", "atlas_data.txt", package = "downscale") <- read.table(data.file, header = TRUE)

## if the input data is a data frame it must have the columns "x", "y"
## and "presence"

## Fit Hui model to
(hui <- hui.downscale(, 
                      cell.width = 10,
                      extent = 228900,
                      new.areas = c(1, 2, 5, 15, 50,75),
                      plot = TRUE))

## Fit Hui model to standardised atlas data for comparison with other models
## First, upgrain data (using All Sampled threshold)
occupancy <- upgrain(,
                     cell.width = 10,
                     scales = 3,
                     method = "All_Sampled")
## the "upgrain" object can be used as input for the Hui model
(hui.stand <- hui.downscale(occupancy,
                            cell.width = 10,
                            new.areas = c(1, 2, 5, 15, 50,75),
                            plot = TRUE))

## compare the area of occupancy (AOO) predictions of the two models

[Package downscale version 4.2-0 Index]