plot.mask {secr} | R Documentation

## Plot Habitat Mask, Density or Resource Surface

### Description

Plot a habitat mask either as points or as an `image` plot. Colours maybe used to show the value of one mask covariate.

### Usage

    ## S3 method for class 'mask'
    plot(x, border = 20, add = FALSE, covariate = NULL, axes = FALSE,
        dots = TRUE, col = "grey", breaks = 10, meshcol = NA, ppoly = TRUE,
        polycol = "red", legend = TRUE, ...)

    ## S3 method for class 'Dsurface'
    plot(x, covariate, group = NULL, plottype =
        "shaded", scale = 1, ...)

    ## S3 method for class 'Rsurface'
    plot(x, covariate = "Resource", plottype =
        "shaded", scale = 1, ...)

    spotHeight (object, prefix = NULL, dec = 2, point = FALSE, text = TRUE,
        sep = ", ",  session = 1, scale = 1, ...)

### Arguments

`x, object` | mask or Dsurface object
`border` | width of blank display border (metres)
`add` | logical for adding mask points to an existing plot
`covariate` | name (as character string in quotes) or column number of a covariate to use for colouring
`axes` | logical for plotting axes
`dots` | logical for plotting mask points as dots, rather than as square pixels
`col` | colour(s) to use for plotting
`breaks` | an integer or a numeric vector – see `cut`
`meshcol` | colour for pixel borders (NA for none)
`ppoly` | logical for whether the bounding polygon should be plotted (if ‘poly’ specified)
`polycol` | colour for outline of polygon (`ppoly` = TRUE)
`legend` | logical; if TRUE a legend is plotted
`...` | other arguments passed to `eqscplot` (in the case of `plot.mask`), `plot.mask` (in the case of `plot.Dsurface` and `plot.Rsurface`), and `points` or `text` (in the case of `spotHeight`)
`group` | group for which plot required, if more than 1
`plottype` | character string c("dots", "shaded", "contour", "persp")
`scale` | numeric multiplier for density or other numeric covariate (see `Dsurface`)
`prefix` | character vector for name(s) of covariate(s) to retrieve
`dec` | number of decimal places for rounding density
`point` | logical for whether to plot point
`text` | logical for whether to place density label on plot
`sep` | character separator for elements if length(prefix)>1
`session` | session number or identifier

### Details

The argument `dots` of `plot.mask` selects between two distinct types of plot (dots and shaded (coloured) pixels).

`plot.Dsurface` and `plot.Rsurface` offer contour and perspective plots in addition to the options in `plot.mask`. It may take some experimentation to get what you want - see `contour` and `persp`.

For plot.Dsurface the default value of ‘covariate’ is ‘D’ unless the Dsurface has a ‘parameter’ attribute of ‘noneuc’,

If using a covariate or Dsurface or Rsurface to colour dots or pixels, the `col` argument should be a colour vector of length equal to the number of levels (the default palette from 2.9.0 is `terrain.colors`, and this palette will also be used whenever there are too few levels in the palette provided; see Notes for more on palettes). Border lines around pixels are drawn in ‘meshcol’. Set this to NA to eliminate pixel borders.

If a `covariate` is specified in a call to `plot.Dsurface` then that covariate will be plotted instead of density. This is a handy way to contour a covariate (contouring is not available in `plot.mask`).

If ‘breaks’ is an integer then the range of the covariate is divided into this number of equal intervals. Alternatively, ‘breaks’ may be a vector of break points (length one more than the number of intervals). This gives more control and often ‘prettier’

`spotHeight` may be used to interrogate a plot produced with `plot.Dsurface` or `plot.Rsurface`, or by `plot.mask` if the mask has covariates. `prefix` defaults to ‘density.’ for Dsurface objects and to '' (all covariates) for mask objects. The predicted density or covariate at the nearest point is returned when the user clicks on the plot. Multiple values may be displayed (e.g., `prefix = c("lcl","ucl")` if Dsurface includes confidence limits). Click outside the mask or hit the Esc key to end. `spotHeight` deals with one session at a time.

Legend plotting is enabled only when a covariate is specified. It uses `legend` when `dots = TRUE` and `strip.legend` otherwise.

### Value

If `covariate` is specified and `plottype = "shaded"` then `plot.mask` invisibly returns a character vector of the intervals defined by ‘breaks’ (useful for plotting a legend).

If `plottype = "persp"` then `plot.mask` invisibly returns a the perspective matrix that may be used to add to the plot with `trans3d`.

`spotHeight` invisibly returns a dataframe of the extracted values and their coordinates.

### Note

`plot.mask()` acquired the argument ‘legend’ in version 2.9.0, and other chages (e.g., `breaks = 10`) may alter the output.

Contouring requires a rectangular grid; if a Dsurface is not rectangular then plot.Dsurface with `plottype = "contour"` triggers a call to `rectangularMask`.

The colour palettes `topo.colors`, `heat.colors` and `terrain.colors` may be viewed with the `demo.pal` function in the Examples code of their help page palettes.

The package RColorBrewer is a good source of palettes. Try `display.brewer.all()` and e.g., `col = brewer.pal(7, "YlGn")`.

### See Also

`colours`, `mask`, `Dsurface`, `rectangularMask`, `contour` `persp` `strip.legend`

### Examples

    # simple

    temptrap <- make.grid()
    tempmask <- make.mask(temptrap)
    plot (tempmask)

    ## restrict to points over an arbitrary detection threshold,
    ## add covariate, plot image and overlay traps

    tempmask <- subset(tempmask, pdot(tempmask, temptrap,
        noccasions = 5)>0.001)
    covariates (tempmask) <- data.frame(circle =
        exp(-(tempmask$x^2 + tempmask$y^2)/10000) )
    plot (tempmask, covariate = "circle", dots = FALSE, axes = TRUE,
        add = TRUE, breaks = 8, col = terrain.colors(8), mesh = NA)
    plot (temptrap, add = TRUE)

    ## add a legend
    par(cex = 0.9)
    covrange <- range(covariates(tempmask)$circle)
    step <- diff(covrange)/8
    colourlev <- terrain.colors(9)
    zlev <- format(round(seq(covrange[1],covrange[2],step),2))
    legend (x = "topright", fill = colourlev, legend = zlev,
        y.intersp = 0.8, title = "Covariate")

    title("Colour mask points with p.(X) > 0.001")
    mtext(side=3,line=-1, "g0 = 0.2, sigma = 20, nocc = 5")

    ## Not run:

    ## Waitarere possum density surface extrapolated across region

    regionmask <- make.mask(traps(possumCH), buffer = 1000, spacing = 10,
        poly = possumremovalarea)
    dts <- distancetotrap(regionmask, possumarea)
    covariates(regionmask) <- data.frame(d.to.shore = dts)
    shorePossums <- predictDsurface(possum.model.Ds, regionmask)

    ## plot as coloured pixels with white lines
    colourlev <- terrain.colors(7)
    plot(shorePossums, breaks = seq(0,3.5,0.5), plottype = "shaded",
        poly = FALSE, col = colourlev, mesh = NA)
    plot(traps(possumCH), add = TRUE, detpar = list(col = "black"))
    polygon(possumremovalarea)

    ## check some point densities
    spotHeight(shorePossums, dec = 1, col = "black")

    ## add a legend
    zlev <- format(seq(0,3,0.5), digits = 1)
    legend (x = "topright", fill = colourlev, legend =
        paste(zlev,"--"), y.intersp = 1, title = "Density / ha")

    ## End(Not run)

[Package secr version 3.2.1 Index]