make.mask {secr} | R Documentation

## 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.(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.

### 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 `buffer.contour` 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`, `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 `rgdal' package of Roger Bivand, Tim Keitt and Barry Rowlingson

    ## Not run:

    datadir <- system.file("extdata", package = "secr")
    possumarea <- rgdal::readOGR(dsn = datadir, 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!

    ## End(Not run)

[Package secr version 3.2.1 Index]