make.mask: Build Habitat Mask

Description

Construct a habitat mask object for spatially explicit capture-recapture. A mask object is a set of points with optional attributes.

Usage

make.mask(traps, buffer = 100, spacing = NULL, nx = 64, ny = 64, type =
    c("traprect", "trapbuffer", "pdot", "polygon", "clusterrect",
    "clusterbuffer", "rectangular", "polybuffer"), poly = NULL, poly.habitat = TRUE,
    cell.overlap = c("centre","any","all"), keep.poly = TRUE, check.poly = TRUE, 
    pdotmin = 0.001, random.origin = FALSE,
    ...)

Value

An object of class mask. When keep.poly = TRUE,

poly and poly.habitat are saved as attributes of the mask.

Arguments

traps: object of class traps
buffer: width of buffer in metres
spacing: spacing between grid points (metres)
nx: number of grid points in `x' direction
ny: number of grid points in `y' direction (type = `rectangular')
type: character string for method
poly: bounding polygon to which mask should be clipped (see Details)
poly.habitat: logical for whether poly represents habitat or its inverse (non-habitat)
cell.overlap: character string for cell vertices used to determine overlap with `poly'
keep.poly: logical; if TRUE any bounding polygon is saved as the attribute `polygon'
check.poly: logical; if TRUE a warning is given for traps that lie outside a bounding polygon
pdotmin: minimum detection probability for inclusion in mask when type = "pdot" (optional)
random.origin: logical; if TRUE the mask coordinates are jittered
...: additional arguments passed to pdot when type = "pdot"

Details

The `traprect' method constructs a grid of points in the rectangle formed by adding a buffer strip to the minimum and maximum x-y coordinates of the detectors in traps. Both `trapbuffer' and `pdot' start with a `traprect' mask and drop some points.

The `trapbuffer' method restricts the grid to points within distance buffer of any detector.

The `pdot' method restricts the grid to points for which the net detection probability \(p.(\mathbf{X})\) (see pdot) is at least pdotmin. Additional parameters are used by pdot (detectpar, noccasions). Set these with the ... argument; otherwise make.mask will silently use the arbitrary defaults. pdot is currently limited to a halfnormal detection function.

The `clusterrect' method constructs a grid of rectangular submasks centred on `clusters' of detectors generated with trap.builder (possibly indirectly by make.systematic). The `clusterbuffer' method resembles `trapbuffer', but is usually faster when traps are arranged in clusters because it starts with a `clusterrect' mask.

The `rectangular' method constructs a simple rectangular mask with the given nx, ny and spacing.

The `polybuffer' method constructs a mask by buffering around the polygon specified in the `poly' argument. If that inherits from `SpatialPolygons' or `sfc' then the buffering is performed with sf::st_buffer. Otherwise, buffering is approximate, based on the distance to points on an initial discretized mask enclosed by `poly' (points at half the current `spacing').

If poly is specified, points outside poly are dropped (unless type = "polybuffer"). The default is to require only the centre to lie within poly; use cell.overlap = "all" to require all cell corners to lie within poly, or cell.overlap = "any" to accept cells with any corner in poly. The `polygon' method places points on a rectangular grid clipped to the polygon (buffer is not used). Thus `traprect' is equivalent to `polygon' when poly is supplied. poly may be either

a matrix or dataframe of two columns interpreted as x and y coordinates, or
an object from package `sf' with polygon geometries, or
a SpatialPolygons or SpatialPolygonsDataFrame object as defined in the package `sp', possibly imported by reading a shapefile.

If spacing is not specified then it is determined by dividing the range of the x coordinates (including any buffer) by nx.

random.origin shifts the origin of the mask by a uniform random displacement within a spacing x spacing grid cell, while ensuring that the mask also satisfies the buffer requirement. random.origin is available only for `traprect', `trapbuffer', `polygon', and `rectangular' types, and spacing must be specified.

Examples

Run this code


temptrap <- make.grid(nx = 10, ny = 10, spacing = 30)

## default method: traprect
tempmask <- make.mask(temptrap, spacing = 5)
plot(tempmask)
summary (tempmask)

## make irregular detector array by subsampling 
## form mask by `trapbuffer' method
temptrap <- subset (temptrap, sample(nrow(temptrap), size = 30))
tempmask <- make.mask (temptrap, spacing = 5, type = "trapbuffer")
plot (tempmask)
plot (temptrap, add = TRUE)

if (FALSE) {

## form mask by "pdot" method
temptrap <- make.grid(nx = 6, ny = 6)
tempmask <- make.mask (temptrap, buffer = 150, type = "pdot", 
    pdotmin = 0.0001, detectpar = list(g0 = 0.1, sigma = 30),
    noccasions = 4)
plot (tempmask)
plot (temptrap, add = TRUE)

## Using an ESRI polygon shapefile for clipping (shapefile
## polygons may include multiple islands and holes).

library(sf)
shpfilename <- system.file("extdata/possumarea.shp", package = "secr")
possumarea <- st_read(shpfilename)

possummask2 <- make.mask(traps(possumCH), spacing = 20,
    buffer = 250, type = "trapbuffer", poly = possumarea)
par(mar = c(1,6,6,6), xpd = TRUE)
plot (possummask2, ppoly = TRUE)
plot(traps(possumCH), add = TRUE)
par(mar = c(5,4,4,2) + 0.1, xpd = FALSE)

## if the polygon delineates non-habitat ...
seaPossumMask <- make.mask(traps(possumCH), buffer = 1000, 
    type = "traprect", poly = possumarea, poly.habitat = FALSE)
plot(seaPossumMask)
plot(traps(possumCH), add = TRUE)
## this mask is not useful!

}