make.mask: Build Habitat Mask

In secr: Spatially Explicit Capture-Recapture

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

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.

Value

An object of class mask. When keep.poly = TRUE, poly and poly.habitat are saved as attributes of the mask.

Note

A warning is displayed if type = "pdot" and the buffer is too small to include all points with p. > pdotmin.

A habitat mask is needed to fit an SECR model and for some related computations. The default mask settings in secr.fit may be good enough, but it is preferable to use make.mask to construct a mask in advance and to pass that mask as an argument to secr.fit.

The function bufferContour displays the extent of one or more ‘trapbuffer’ zones - i.e. the effect of buffering the detector array with varying strip widths.

See Also

mask, read.mask, subset.mask, pdot, bufferContour, deleteMaskPoints, as.mask

Examples

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)

## Not run: 

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


## End(Not run)

secr documentation built on Nov. 4, 2024, 9:06 a.m.