secr (version 3.0.1)

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

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"

Value

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

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 cnstructs a mask by buffering around the polygon specified in the `poly' argument. If that inherits from `SpatialPolygons' then the buffering is performed with rgeos::gBuffer. 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
• a SpatialPolygons or SpatialPolygonsDataFrame object as defined in the package `sp', possibly imported by reading a shapefile with readOGR() from package rgdal.

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.

See Also

mask, read.mask, subset.mask, pdot, buffer.contour, 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)

## 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).
## Requires the `maptools' package of Nicholas J. Lewin-Koh, Roger
## Bivand, and others; `maptools' uses the `sp' package of spatial
## classes by Ed Pebesma and Roger Bivand.

## Not run: ------------------------------------
# 
# datadir <- system.file("extdata", package = "secr")
# possumareafile <- paste0(datadir, "/possumarea.shp")
# possumarea <- rgdal::readOGR(dsn = possumareafile, layer = "possumarea")
# 
# 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 = T)
# 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 = T)
# ## this mask is not useful!
# 
## ---------------------------------------------

<!-- %% ## OR, as this is a simple polygon, just... -->
<!-- %% possumarea <- possumarea@polygons[[1]]@Polygons[[1]]@coords -->
<!-- %% possummask2 <- make.mask(traps(possumCH), spacing = 20, poly = possumarea, -->
<!-- %%     buffer = 250, type = "trapbuffer") -->