secr (version 3.0.1)

mask.check:

Description

mask.check evaluates the effect of varying buffer width and mask spacing on either the likelihood or density estimates from secr.fit()

Usage

mask.check(object, buffers = NULL, spacings = NULL, poly = NULL,
    LLonly = TRUE, realpar = NULL, session = 1, file = NULL,
    drop = "", tracelevel = 0, ncores = 1, ...)

Arguments

object

object of class `capthist' or `secr'

buffers

vector of buffer widths

spacings

vector of mask spacings

poly

matrix of two columns, the x- and y-coordinates of a bounding polygon (optional)

LLonly

logical; if TRUE then only the log likelihood is computed

realpar

list of parameter values

session

vector of session indices (used if object spans multiple sessions)

file

name of output file (optional)

drop

character vector: names of fitted secr object to omit

tracelevel

integer for level of detail in reporting (0,1,2)

ncores

integer number of cores available for parallel processing

…

other arguments passed to secr.fit

Value

Array of log-likelihoods (LLonly = TRUE) or estimates (LLonly = FALSE) for each combination of buffers and spacings. The array has 3 dimensions if LLonly = FALSE and both buffers and spacings have multiple levels; otherwise it collapses to a matrix. Rows generally represent buffers, but rows represent spacings if a single buffer is specified.

Warning

mask.check() may fail if object is a fitted `secr' model and a data object named in the original call of secr.fit() (i.e. object$call) is no longer in the working environment (secr.fit arguments capthist, mask, verify & trace are exempt). Fix by any of (1) applying mask.check directly to the `capthist' object, specifying other arguments (buffers, spacings, realpar) as needed, (2) re-fitting the model and running mask.check in the same environment, (3) specifying the offending argument(s) in …, or (4) re-creating the required data objects(s) in the working environment, possibly from saved inputs in object (e.g., mytimecov <- myfit$timecov).

Details

Masks of varying buffer width and spacing are constructed with the `trapbuffer' method in make.mask, using the detector locations (`traps') from either a capthist object or a previous execution of secr.fit. Default values are provided for buffers and spacings if object is of class `secr' (respectively c(1, 1.5, 2) and c(1, 0.75, 0.5) times the values in the existing mask). The default for buffers will not work if a detector is on the mask boundary, as the inferred buffer is then 0.

Variation in the mask may be assessed for its effect on --

• the log-likelihood evaluated for given values of the parameters (LLonly = TRUE)
• estimates from maximizing the likelihood with each mask (LLonly = FALSE)

realpar should be a list with one named component for each real parameter (see Examples). It is relevant only if LLonly = TRUE. realpar may be omitted if object is of class `secr'; parameter values are then extracted from object.

session should be an integer or character vector suitable for indexing sessions in object, or in object$capthist if object is a fitted model. Each session is considered separately; a model formula that refers to session or uses session covariates will cause an error.

If file is specified and ncores = 1 then detailed results (including each model fit when LLonly = FALSE) are saved to an external .RData file. Loading this file creates or overwrites object(s) in the workspace: mask.check.output if LLonly = TRUE, otherwise mask.check.output and mask.check.fit. For multiple sessions these are replaced by lists with one component per session (mask.check.outputs and mask.check.fits). The drop argument is passed to trim and applied to each fitted model; use it to save space, at the risk of limiting further computation on the fitted models.

tracelevel>0 causes more verbose reporting of progress during execution.

If ncores > 1 the parallel package is used to create processes on multiple cores (see Parallel for more), progress messages are suppressed, and nothing is output to file.

The … argument may be used to override existing settings in object - for example, a conditional likelihood fit (CL = T) may be selected even if the original model was fitted by maximizing the full likelihood.

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. (2012) DENSITY 5.0: software for spatially explicit capture--recapture. Department of Mathematics and Statistics, University of Otago, Dunedin, New Zealand. http://www.otago.ac.nz/density.

See Also

esa.plot, make.mask, secr.fit

Examples

<!-- % not run because (1) slow (2) writes output file -->
## Not run: ------------------------------------
# 
# ## from a capthist object, specifying almost everything
# mask.check (possumCH, spacings = c(20, 30), buffers =c(200, 300),
#     realpar = list(g0 = 0.2, sigma = 50), CL = TRUE)
# 
# ## from a fitted model, using defaults
# mask.check (stoat.model.HN)
# ## LL did not change with varying buffer (rows) or spacing (cols):
# ##         78.125  58.59375   39.0625
# ## 1000 -144.0015 -144.0015 -144.0015
# ## 1500 -144.0017 -144.0017 -144.0017
# ## 2000 -144.0017 -144.0017 -144.0017
# 
# ## fit new models for each combination of buffer & spacing,
# ## and save fitted models to a file
# mask.check (stoat.model.HN, buffers = 1500, spacings =
#     c(40,60,80), LLonly = FALSE, file = "test", CL = TRUE)
# 
# ## look in more detail at the preceding fits
# ## restores objects `mask.check.output' and `mask.check.fit'
# load("test.RData")  
# lapply(mask.check.fit, predict)
# lapply(mask.check.fit, derived)
# 
# ## multi-session data
# mask.check(ovenbird.model.1, session = c("2005","2009"))
# 
# ## clipping mask
# olddir <- setwd(system.file("extdata", package = "secr"))
# possumarea <- read.table("possumarea.txt", header = TRUE)
# setwd(olddir)
# data (possum)
# mask.check (possum.model.0, spacings = c(20, 30), buffers =
#     c(200, 300), poly = possumarea, LLonly = FALSE,
#     file = "temp", CL = TRUE)
# 
# ## review fitted models
# load ("temp.RData")
# par(mfrow = c(2,2), mar = c(1,4,4,4))
# for (i in 1:4) {
#     plot(traps(mask.check.fit[[i]]$capthist), border = 300,
#         gridlines = FALSE)
#     plot(mask.check.fit[[i]]$mask, add = TRUE)
#     lines(possumarea)
#     text ( 2698618, 6078427, names(mask.check.fit)[i])
#     box()
# }
# par(mfrow = c(1,1), mar = c(5,4,4,2) + 0.1)    ## defaults
# 
## ---------------------------------------------