sim.secr:

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 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

value for setting .Random.seed - either NULL or an integer

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

Value

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

For sim.detect a list of `capthist' objects.

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 trimming 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.

Examples

Run this code


## 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))
# 
## ---------------------------------------------

Run the code above in your browser using DataLab