sim.capthist {secr} | R Documentation

## Simulate Detection Histories

### Description

Create a set of capture or marking-and-resighting histories by simulated sampling of a 2-D population using an array of detectors.

### Usage

    sim.capthist(traps, popn = list(D = 5, buffer = 100, Ndist = 'poisson'),
        detectfn = 0, detectpar = list(),
        noccasions = 5, renumber = TRUE, seed = NULL)
    sim.resight(traps, ..., q = 1, pID = 1, unmarked = TRUE, nonID = TRUE)

### Arguments

`traps` | `traps` object with the locations and other attributes of detectors
`popn` | locations of individuals in the population to be sampled, either as a `popn` object or a list with named elements 'D' (density) and 'buffer'
`detectfn` | code for type of detection function
`detectpar` | list of values for named parameters of detection function
`noccasions` | number of occasions to simulate
`renumber` | logical for whether output rows should labeled sequentially (TRUE) or retain the numbering of the population from which they were drawn (FALSE)
`seed` |
`...` | arguments to pass to `sim.capthist`
`q` | number of marking occasions
`pID` | probability of individual identification for marked animals
`unmarked` | logical, if true unmarked individuals are not recorded during 'sighting'
`nonID` | logical, if true then unidentified marked individuals are not recorded during 'sighting'

### Details

If `popn` is not of class 'popn' then a homogeneous Poisson population with the desired density (animals/ha) is first simulated over the rectangular area of the bounding box of `traps` plus a buffer of the requested width (metres). The detection algorithm depends on the detector type of `traps`. For 'proximity' detectors, the actual detection probability of animal i at detector j is the naive probability given by the detection function. For 'single' and 'multi' detectors the naive probability is modified by competition between detectors and, in the case of 'single' detectors, between animals. See Efford (2004) and other papers below for details.

Detection parameters are specific to the detection function, which is indicated by a numeric code (`detection functions`). Parameters may vary with time - for this provide a vector of length `noccasion`. The default detection parameters are `list(g0 = 0.2, sigma = 25, z = 1)`.

`detectpar` may also include 'binomN' and other arguments for detectors that have yet to be documented. A zero value for `binomN` indicates that counts should be modelled with a Poisson distribution.

If `popn` is specified by an object of class 'popn' then any individual covariates will be passed on; the `covariates` attribute of the output is otherwise set to NULL.

The random number seed is managed as in `simulate.lm`.

`sim.resight` generates mark-resight data for 'q' marking occasions followed by 'noccasion – q' sighting occasions. `sim.capthist` is first called with the arguments 'traps' and .... The detector type must be 'proximity'. The 'usage' attribute of `traps` is ignored at present, so the same detectors are operated on all occasions. Any detection-parameter vector of length 2 in ... is interpreted as providing differing constant values for the marking and sighting phases.

### Value

For `sim.capthist`, an object of class `capthist`, a matrix or 3-dimensional array with additional attributes. Rows represent individuals and columns represent occasions; the third dimension, used when detector type = 'proximity', codes presence or absence at each detector. For trap detectors ('single', 'multi') each entry in `capthist` is either zero (no detection) or the sequence number of the trap.
The initial state of the R random number generator is stored in the 'seed' attribute.
For `sim.resight`, an object of class `capthist`, always a 3-dimensional array, with additional attributes Tu and Tm containing counts of 'unmarked' and 'marked, not identified' sightings.

### Note

External code is called to speed the simulations. The present version assumes a 'null model' i.e. naive detection probability is constant except for effects of distance and possibly time (using vector-valued detection parameters from 1.2.10). You can, however, use `rbind.capthist` to combine detections of population subclasses (e.g. males and females) simulated with different parameter values. This is not valid for detector type 'single' because it fails to allow for competition for traps between subclasses. Future versions may allow more complex models.

### Author(s)

Murray Efford murray.efford@otago.ac.nz

### References

Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximum likelihood methods for capture–recapture studies. Biometrics 64, 377–385.

Efford, M. G. (2004) Density estimation in live-trapping studies. Oikos 106, 598–610.

Efford, M. G., Borchers D. L. and Byrom, A. E. (2009) Density estimation by spatially explicit capture-recapture: likelihood-based methods. In: D. L. Thomson, E. G. Cooch and M. J. Conroy (eds) Modeling Demographic Processes in Marked Populations. Springer, New York. Pp. 255–269.

Efford, M. G., Dawson, D. K. and Borchers, D. L. (2009) Population density estimated from locations of individuals on a passive detector array. Ecology 90, 2676–2682.

### See Also

`sim.popn`, `capthist`, `traps`, `popn`, `detection functions`, `simulate`

### Examples

    ## simple example
    ## detector = 'multi' (default)
    temptrap <- make.grid(nx = 6, ny = 6, spacing = 20)
    sim.capthist (temptrap, detectpar = list(g0 = 0.2, sigma = 20))

    ## with detector = 'proximity, there may be more than one
    ## detection per individual per occasion
    temptrap <- make.grid(nx = 6, ny = 6, spacing = 20, detector =
        'proximity')
    summary(sim.capthist (temptrap, detectpar =
        list(g0 = 0.2, sigma = 20)))

[Package secr version 1.3.0 Index]