sim.secr {secr} | R Documentation

## Simulate From Fitted secr Model

### Description

Simulate a spatially distributed population, sample from that population with an array of detectors, and optionally fit an SECR model to the simulated data.

### Usage

    ## S3 method for class 'secr':
    simulate(object, nsim = 1, seed = NULL, chat = 1, ...)

    sim.secr(object, nsim = 1, extractfn = function(x) c(deviance =
        deviance(x), df = df.residual(x)), seed = NULL, data = NULL,
        tracelevel = 1, hessian = "none", start = object$fit$par)

### Arguments

`object` | an secr object
`nsim` | number of replicates
`seed` | value for setting .Random.seed - either NULL or an integer
`chat` | real value for overdispersion parameter
`extractfn` | function to extract output values from fitted model
`data` | optional list of simulated data saved from previous call to `simulate.secr`
`tracelevel` | integer for level of detail in reporting (0,1,2)
`hessian` | character string controlling the computation of the Hessian matrix
`start` | vector of starting 'beta' values for `secr.fit`
`...` | other arguments (not used)

### Details

For each replicate, `simulate.secr` calls `sim.popn` to generate session- and group-specific realizations of the (possibly inhomogeneous) 2-D Poisson distribution fitted in `object`, across the habitat mask(s) in `object`. Group subpopulations are combined using `rbind.popn` within each session; information to reconstruct groups is retained in the individual-level factor covariate(s) of the resulting `popn` object (corresponding to `object\$groups`). Each population is then sampled using the fitted detection model and detector (trap) array(s) in `object`.

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

`simulate.secr` does not yet work with models fitted using conditional likelihood (`object$CL = TRUE`). Detector type is determined by `detector(traps(object$capthist))`, which should be one of 'single', 'multi', 'proximity', 'areasearch' or 'count'.

`sim.secr` is a wrapper function. If `data = NULL` (the default) then it calls `simulate.secr` to generate new datasets. If `data` is provided then `nsim` is taken to be `length(data)`. `secr.fit` is called to fit the original model to each new dataset. Results are summarized according to the user-provided function `extractfn`. The default `extractfn` returns the deviance and its degrees of freedom; a NULL value for `extractfn` returns the fitted secr objects after `trim`ming to reduce bulk. Simulation uses the detector type of the data, even when another likelihood is fitted (this is the case with single-catch data, for which a multi-catch likelihood is fitted). Warning messages from `secr.fit` are suppressed.

`extractfn` should be a function that takes an `secr` object as its only argument.

`tracelevel=0` suppresses most messages; `tracelevel=1` gives a terse message at the start of each fit; `tracelevel=2` also sets 'details\$trace = TRUE' for `secr.fit`, causing each likelihood evaluation to be reported.

It is OK (and faster) to use `hessian='none'` unless `extractfn` needs variances or covariances.

`sim.capthist` is a more direct way to simulate data from a null model (i.e. one with constant parameters for density and detection). It is limited to a single session.

### Value

For `simulate.secr`, a list of data sets ('capthist' objects). This list has class=('list','secrdata'); the initial state of the random number generator (roughly, the value of .Random.seed) is stored as the attribute 'seed'.
The value from `sim.secr` depends on `extractfn`: if that returns a numeric vector of length `n.extract` then the value is a matrix with `dim = c(nsim, n.extract)` (i.e., the matrix has one row per replicate and one column for each extracted value). Otherwise, the value returned by `sim.secr` is a list with one component per replicate (strictly, an object of class = c('list','secrlist')). Each simulated fit may be retrieved in toto by specifying `extractfn = identity`, or slimmed down by specifying `extractfn = NULL` or `extractfn = trim`, which are equivalent.
For either form of output from `sim.secr` the initial state of the random number generator is stored as the attribute 'seed'.

### Note

The value returned by `simulate.secr` is a list of 'capthist' objects; if there is more than one session, each 'capthist' is itself a sort of list .

The classes 'secrdata' and 'secrlist' are used only to override the ugly and usually unwanted printing of the seed attribute.

The default value for `start` in `sim.secr` is the previously fitted parameter vector. Alternatives are NULL or `object$start`.

### Author(s)

Murray Efford murray.efford@otago.ac.nz

### See Also

`sim.capthist`, `secr.fit`, `simulate`

### Examples

    data(secrdemo)
    simulate(secrdemo.0, nsim = 2)

    ## Not run:

    ## this would take a long time...
    sims <- sim.secr(secrdemo.0, nsim = 99)
    deviance(secrdemo.0)
    devs <- c(deviance(secrdemo.0),sims$deviance)
    quantile(devs, probs=c(0.95))
    rank(devs)[1] / length(devs)

    ## to assess bias
    extrfn <- function (object) unlist(predict(object)['D',-1])
    sims <- sim.secr(secrdemo.0, nsim = 50, extractfn=extrfn)
    sims

    ## End(Not run)

[Package secr version 1.3.0 Index]