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, maxperpoly = 100,
        chat = 1, ncores = 1, ...)

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

    sim.detect(object, popnlist, maxperpoly = 100, renumber = TRUE)

### Arguments

`object` | a fitted secr model
`nsim` | integer number of replicates
`seed` | either NULL or an integer that will be used in a call to `set.seed`
`maxperpoly` | integer maximum number of detections of an individual in one polygon or transect on any occasion
`chat` | real value for overdispersion parameter
`ncores` | integer number of cores available for parallel processing
`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 or logical controlling the computation of the Hessian matrix
`start` | vector of starting ‘beta’ values for `secr.fit`
`...` | other arguments (not used)
`popnlist` | list of popn objects
`renumber` | logical; if TRUE then

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

Certain model types are not supported by `simulate.secr`. These include models fitted using conditional likelihood (`object$CL = TRUE`), telemetry models and exotic behavioural response models.

Detector type is determined by `detector(traps(object$capthist))`.

`sim.secr` is a wrapper function. If `data = NULL` (the default) then it calls `simulate.secr` to generate `nsim` 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.

`hessian` controls computation of the Hessian matrix from which variances and covariances are obtained. `hessian` replaces the value in `object\$details`. Options are "none" (no variances), "auto" (the default) or "fdhess" (see `secr.fit`). It is OK (and faster) to use `hessian="none"` unless `extractfn` needs variances or covariances. Logical TRUE and FALSE are interpreted by `secr.fit` as "auto" and "none".

If `ncores > 1` the parallel package is used to create processes on multiple cores (see Parallel for more) and progress messages are suppressed. New datasets are generated in the master process, so there is no need to manage the random number streams in the worker processes.

`sim.capthist` is a more direct way to simulate data from a null model (i.e. one with constant parameters for density and detection), or from a time-varying model.

`sim.detect` is a function used internally that will not usually be called directly.

### Value

For `simulate.secr`, a list of data sets (‘capthist’ objects). This list has class `c("secrdata", "list")`; 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("secrlist", "list")`). 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’.

For `sim.detect` a list of ‘capthist’ objects.

### 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. However, a few other methods are available for ‘secrlist’ objects (e.g. `plot.secrlist`).

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

### See Also

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

### Examples

    ## previously fitted model
    simulate(secrdemo.0, nsim = 2)

    ## Not run:

    ## The following has been superceded by secr.test()

    ## this would take a long time...
    ## adjust ncores for your machine (see ?Parallel)
    sims <- sim.secr(secrdemo.0, nsim = 99, ncores = 8)
    deviance(secrdemo.0)
    devs <- c(deviance(secrdemo.0),sims$deviance)
    quantile(devs, probs=c(0.95))
    rank(devs)[1] / length(devs)

    ## to assess bias and CI coverage
    ## adjust ncores for your machine (see ?Parallel)
    extrfn <- function (object) unlist(predict(object)["D",-1])
    sims <- sim.secr(secrdemo.0, nsim = 50, hessian = "auto",
        extractfn = extrfn, ncores = 8)
    sims

    ## with a larger sample, could get parametric bootstrap CI
    quantile(sims[,1], c(0.025, 0.975))

    ## End(Not run)

[Package secr version 3.2.1 Index]