plot.capthist {secr} | R Documentation

## Plot Detection Histories

### Description

Display a plot of detection (capture) histories or telemetry data over a map of the detectors.

### Usage

    ## S3 method for class 'capthist'
    plot(x, rad = 5, hidetraps = FALSE, tracks = FALSE,
        title = TRUE, subtitle = TRUE, add = FALSE, varycol = TRUE,
        icolours = NULL, randcol = FALSE, lab1cap = FALSE, laboffset = 4, ncap = FALSE,
        splitocc = NULL, col2 = "green", type = c("petal", "n.per.detector", "n.per.cluster",
            "sightings", "centres", "telemetry"),
        cappar = list(cex = 1.3, pch = 16, col = "blue"),
        trkpar = list(col = "blue", lwd = 1),
        labpar = list(cex = 0.7, col = "black"), ...)

    plotMCP(x, add = FALSE, col = "black", fill = NA, lab1cap = FALSE, laboffset = 4,
        ncap = FALSE, ...)

### Arguments

`x` | an object of class `capthist`
`rad` | radial displacement of dot indicating each capture event from the detector location (used to separate overlapping points)
`hidetraps` | logical indicating whether trap locations should be displayed
`tracks` | logical indicating whether consecutive locations of individual animals should be joined by a line
`title` | logical or character string for title
`subtitle` | logical or character string for subtitle
`add` | logical for whether to add to existing plot
`varycol` | logical for whether to distinguish individuals by colour
`icolours` | vector of individual colours (when `varycol` = TRUE), or colour scale (non-petal plots)
`randcol` | logical to use random colours (`varycol` = TRUE)
`lab1cap` | logical for whether to label the first capture of each animal
`laboffset` | distance by which to offset labels from points
`ncap` | logical to display the number of detections per trap per occasion
`splitocc` | optional occasion from which second colour is to be used
`col2` | second colour (used with `splitocc`)
`type` | character string ("petal", "n.per.detector" or "n.per.cluster")
`cappar` | list of named graphical parameters for detections (passed to `par`)
`trkpar` | list of named graphical parameters for tracks (passed to `par`)
`labpar` | list of named graphical parameters for labels (passed to `par`)
`...` | arguments to be passed to `plot.traps`
`col` | vector of line colour numbers or names (plotMCP only)
`fill` | vector of fill colour numbers or names (plotMCP only)

### Details

By default, a ‘petal’ plot is generated in the style of Density (Efford 2012) using `eqscplot` from the MASS library.

If `type = "n.per.detector"` or `type = "n.per.cluster"` the result is a colour-coded plot of the number of individuals at each unit, pooled over occasions.

If `type = "sightings"` the sightings of unmarked animals are displayed on a petal-like plot (requires mark-resight data) (see also `sightingPlot`).

If `type = "centres"` then a single point is plotted for each animal, jittered on each axis by a random amount (limits +/- `rad`/2).

If `type = "telemetry"` and the ‘telemetryxy’ attribute is not NULL then the telemetry locations are plotted.

If `title` = FALSE no title is displayed; if `title` = TRUE, the session identifer is used for the title.

If `subtitle` = FALSE no subtitle is displayed; if `subtitle` = TRUE, the subtitle gives the numbers of occasions, detections and individuals.

If `x` is a multi-session capthist object then a separate plot is produced for each session. Use `par(mfrow = c(nr, nc))` to allow a grid of plots to be displayed simultaneously (nr rows x nc columns).

These arguments are used only for petal plots: `rad`, `tracks`, `varycol`, `randcol`, `lab1cap`, `laboffset`, `ncap`, `splitocc`, `col2`, `trkpar`, and `labpar`. Call `occasionKey` to add a key to the petals.

If `icolours = NULL` and `varycol = TRUE` then a vector of colours is generated automatically as topo.colors((nrow(x)+1) * 1.5). If there are too few values in `icolours` for the number of individuals then colours will be re-used.

`plotMCP` plots minimum convex polygons of individual location data over a base plot of detector locations. Usually the data are telemetry locations in the xylist attribute of the capthist object; if this is not present and `x` is a polygon search capthist then the individual xy data are plotted.

### Value

For `type = "petal"`, the number of detections in `x`. For `type = "sightings"`, the number of sightings of unmarked animals in `x`. For `type = "n.per.detector"` or `type = "n.per.cluster"`, a dataframe with data for a legend (see Examples).

`plotMCP` invisibly returns a list in which each component is a 2-column (x,y) dataframe of boundary coordinates for one individual.

### References

Efford, M. G. (2012) DENSITY 5.0: software for spatially explicit capture–recapture. Department of Mathematics and Statistics, University of Otago, Dunedin, New Zealand. https://www.otago.ac.nz/density.

### See Also

`capthist`, `occasionKey`, `sightingPlot`

### Examples

    demotrap <- make.grid()
    tempcapt <- sim.capthist(demotrap,
        popn = list(D = 5, buffer = 50),
        detectpar = list(g0 = 0.15, sigma = 30))
    plot(tempcapt, border = 10, rad = 3, tracks = TRUE,
        lab1cap = TRUE, laboffset = 2.5)

    ## type = n.per.cluster

    ## generate some captures
    testregion <- data.frame(x = c(0,2000,2000,0),
        y = c(0,0,2000,2000))
    popn <- sim.popn (D = 10, core = testregion, buffer = 0,
        model2D = "hills", details = list(hills = c(-2,3)))
    t1 <- make.grid(nx = 1, ny = 1)
    t1.100 <- make.systematic (cluster = t1, spacing = 100,
        region = testregion)
    capt <- sim.capthist(t1.100, popn = popn, noccasions = 1)

    ## now plot captures ...
    temp <- plot(capt, title = "Individuals per cluster",
        type = "n.per.cluster", hidetraps = FALSE,
        gridlines = FALSE, cappar = list(cex = 1.5))

    ## Not run:
    ## add legend; click on map to place top left corner
    legend (locator(1), pch = 21, pt.bg = temp$colour,
        pt.cex = 1.3, legend = temp$legend, cex = 0.8)

    ## End(Not run)

    ## Not run:
    ## try varying individual colours - requires RColorBrewer
    library(RColorBrewer)
    plot(infraCH[[2]], icolours = brewer.pal(12, "Set3"), tracks = T,
        bg = "black", cappar = list(cex = 2), border = 10, rad = 2,
        gridlines=F)

    ## End(Not run)

    ## Not run:
    ## generate telemetry data
    te <- make.telemetry()
    tr <- make.grid(detector = "proximity")
    totalpop <- sim.popn(tr, D = 20, buffer = 100)
    tepop <- subset(totalpop, runif(nrow(totalpop)) < 0.05)
    teCH <- sim.capthist(te, popn = tepop, renumber=FALSE, detectfn = "HHN",
        detectpar = list(lambda0 = 3, sigma = 25))
    plot(teCH, type = 'telemetry', tracks = TRUE)

    ## simple "centres" example
    CH <- sim.capthist(make.poly(), nocc = 20, detectpar = list(g0 = 1, sigma = 10))
    plot(CH, cappar = list(col = 'orange'), varycol = FALSE, border = 10)
    plot(CH, type = 'centres', add = TRUE, rad = 0)

    ## End(Not run)

[Package secr version 3.2.1 Index]