openCR.fit: Fit Open Population Capture-Recapture Model

In openCR: Open Population Capture-Recapture

Fit Open Population Capture–Recapture Model

Description

Nonspatial or spatial open-population analyses are performed on data formatted for ‘secr’. Several parameterisations are provided for the nonspatial Jolly-Seber Schwarz-Arnason model (‘JSSA’, also known as ‘POPAN’). Corresponding spatial models are designated ‘JSSAsecr’. The prefix ‘PLB’ (Pradel-Link-Barker) is used for versions of the JSSA models that are conditional on the number observed. Cormack-Jolly-Seber (CJS) models are also fitted.

Usage

openCR.fit (capthist, type = "CJS", model = list(p~1, phi~1, sigma~1), 
    distribution = c("poisson", "binomial"), mask = NULL, 
    detectfn = c("HHN", "HHR", "HEX", "HAN", "HCG", "HVP", "HPX"), binomN = 0, 
    movementmodel = c('static', 'BVN', 'BVE', 'BVT', 'RDE', 'RDG','RDL','IND', 'UNI',
      'BVNzi', 'BVEzi', 'RDEzi', 'INDzi', 'UNIzi'), edgemethod = 
    c("truncate", "wrap", "none"), kernelradius = 30, sparsekernel = TRUE, 
    start = NULL, link = list(), fixed = list(), stratumcov = NULL, 
    sessioncov = NULL, timecov = NULL, agecov = NULL, dframe = NULL, 
    dframe0 = NULL, details = list(), method = "Newton-Raphson", trace = NULL, 
    ncores = NULL, stratified = FALSE, ...)

Arguments

capthist	capthist object from ‘secr’
type	character string for type of analysis (see Details)
model	list with optional components, each symbolically defining a linear predictor for the relevant real parameter using formula notation. See Details for names of real parameters.
distribution	character distribution of number of individuals detected
mask	single-session mask object; required for spatial (secr) models
detectfn	character code
binomN	integer code for distribution of counts (see secr.fit)
movementmodel	character; model for movement between primary sessions (see Details)
edgemethod	character; method for movement at edge of mask (see Details)
kernelradius	integer; radius in mask cells of discretized kernel (movement models only)
sparsekernel	logical; if TRUE then only cardinal and intercardinal axes are included
start	vector of initial values for beta parameters, or fitted model(s) from which they may be derived
link	list with named components, each a character string in {"log", "logit", "loglog", "identity", "sin", "mlogit"} for the link function of the relevant real parameter
fixed	list with optional components corresponding to each ‘real’ parameter, the scalar value to which parameter is to be fixed
stratumcov	optional dataframe of values of stratum-specific covariate(s).
sessioncov	optional dataframe of values of session-specific covariate(s).
timecov	optional dataframe of values of occasion-specific covariate(s).
agecov	optional dataframe of values of age-specific covariate(s)
dframe	optional data frame of design data for detection parameters (seldom used)
dframe0	optional data frame of design data for detection parameters of naive (undetected) animals (seldom used)
details	list of additional settings (see Details)
method	character string giving method for maximizing log likelihood
trace	logical or integer; output log likelihood at each evaluation, or at some lesser frequency as given
ncores	integer number of cores for parallel processing (see Details)
stratified	logical; if TRUE then sessions of capthist interpreted as indpendent strata
...	other arguments passed to join()

Details

The permitted nonspatial models are CJS, Pradel, Pradelg, JSSAbCL = PLBb, JSSAfCL = PLBf, JSSAgCL = PLBg, JSSAlCL = PLBl, JSSAb, JSSAf, JSSAg, JSSAl, JSSAB and JSSAN.

The permitted spatial models are CJSsecr, JSSAsecrbCL = PLBsecrb, JSSAsecrfCL = PLBsecrf, JSSAsecrgCL = PLBsecrg, JSSAsecrlCL = PLBsecrl, JSSAsecrb, JSSAsecrf, JSSAsecrg, JSSAsecrl, JSSAsecrB, JSSAsecrN, secrCL, and secrD.

See openCR-vignette.pdf for a table of the ‘real’ parameters associated with each model type.

Parameterisations of the JSSA models differ in how they include recruitment: the core parameterisations express recruitment either as a per capita rate (‘f’), as a finite rate of increase for the population (‘l’ for lambda) or as per-occasion entry probability (‘b’ for the classic JSSA beta parameter, aka PENT in MARK). Each of these models may be fitted by maximising either the full likelihood, or the likelihood conditional on capture in the Huggins (1989) sense, distinguished by the suffix ‘CL’. Full-likelihood JSSA models may also be parameterized in terms of the time-specific absolute recruitment (BN, BD) or the time-specific population size(N) or density (D).

‘secrCL’ and ‘secrD’ are closed-population spatial models.

Data are provided as secr ‘capthist’ objects, with some restrictions. For nonspatial analyses, ‘capthist’ may be single-session or multi-session, with any of the main detector types. For spatial analyses ‘capthist’ should be a single-session dataset of a point detector type (‘multi’, ‘proximity’ or ‘count’) (see also details$distribution below). In openCR the occasions of a single-session dataset are treated as open-population temporal samples except that occasions separated by an interval of zero (0) are from the same primary session (multi-session input is collapsed to single-session if necessary).

model formulae may include the pre-defined terms ‘session’,‘Session’, ‘h2’, and ‘h3’ as in secr. ‘session’ is the name given to primary sampling times in ‘secr’, so a fully time-specific CJS model is list(p ~ session, phi ~ session). ‘t’ is a synonym of ‘session’. ‘Session’ is for a trend over sessions. ‘h2’ and ‘h3’ allow finite mixture models.

Learned (behavioural) responses (‘b’, ‘B’, etc.) were redefined and extended in version 1.3.0. The vignette should be consulted for current definitions.

Formulae may also include named occasion-specific and session-specific covariates in the dataframe arguments ‘timecov’ and ‘sessioncov’ (occasion = secondary session of robust design). Named age-specific covariates in 'agecov' are treated similarly. Individual covariates present as an attribute of the ‘capthist’ input may be used in CJS and ..CL models. Groups are not supported in this version, but may be implemented via a factor-level covariate in ..CL models.

distribution specifies the distribution of the number of individuals detected; this may be conditional on the population size (or number in the masked area) ("binomial") or unconditional ("poisson"). distribution affects the sampling variance of the estimated density. The default is "poisson" as in secr.

Movement models are list at Movement models. Their use is described in the vignette.

edgemethod controls movement probabilities at the mask edge in spatial models that include movement. "none" typically causes bias in estimates; "wrap" wraps kernel probabilities to the opposing edge of a rectangular mask; "truncate" scales the values of an edge-truncated kernel so that they always sum to 1.0 (safer and more general than "wrap").

The mlogit link function is used for the JSSA (POPAN) entry parameter ‘b’ (PENT in MARK) and for mixture proportions, regardless of link.

Spatial models use one of the hazard-based detection functions (see detectfn) and require data from independent point detectors (secr detector types ‘multi’, ‘proximity’ or ‘count’).

Code is executed in multiple threads unless the user specifies ncores = 1 or there is only one core available or details$R == TRUE. Setting ncores = NULL uses the existing value from the environment variable RCPP_PARALLEL_NUM_THREADS (see setNumThreads) or 2 if that has not been set.

Optional stratification was introduced in openCR 2.0.0. See openCR-vignette.pdf for details.

The ... argument may be used to pass a vector of unequal intervals to join (interval), or to vary the tolerance for merging detector sites (tol).

The start argument may be

- a vector of beta parameter values, one for each of the NP beta parameters in the model

- a named vector of beta parameter values in any order

- a named list of one or more real parameter values

- a single fitted secr or openCR model whose real parameters overlap with the current model

- a list of two fitted models

In the case of two fitted models, the values are melded. This is handy for initialising an open spatial model from a closed spatial model and an open non-spatial model. If a beta parameter appears in both models then the first is used.

details is a list used for various specialized settings –

Component	Default	Description
autoini	1	Number of the session used to determine initial values of D, lambda0 and sigma (secr types only)
CJSp1	FALSE	Modified CJS model including initial detection (estimable with robust design and many spatial models)
contrasts	NULL	Value suitable for the `contrasts.arg' argument of model.matrix used to specify the coding of factor predictors
control	list()	Components may be named arguments of nlm, or passed intact as argument `control' of optim - useful for increasing maxit for method = Nelder-Mead (see vignette)
debug	0	debug=1 prints various intermediate values; debug>=2 interrupts execution by calling browser() (position variable)
fixedbeta	NULL	Vector with one element for each coefficient (beta parameter) in the model. Only 'NA' coefficients will be estimated; others will be fixed at the value given (coefficients define a linear predictor on the link scale). The number and order of coefficients may be determined by calling openCR.fit with trace = TRUE and interrupting execution after the first likelihood evaluation.
grain	1	Obscure setting for multithreading - see RcppParallel package
hessian	"auto"	Computation of the Hessian matrix from which variances and covariances are obtained. Options are "none" (no variances), "auto" or "fdhess" (use the function fdHess in nlme). If "auto" then the Hessian from the optimisation function is used.
ignoreusage	FALSE	Overrides usage in traps object of capthist
initialage	0	Numeric (uniform age at first capture) or character value naming an individual covariate; see age.matrix
initialstratum	1	Number of stratum to use for finding default starting values (cf autoini in secr)
LLonly	FALSE	TRUE causes the function to return a single evaluation of the log likelihood at the initial values, followed by the initial values
minimumage	0	Sets a minimum age; see age.matrix
maximumage	1	Sets a maximum age; older animals are recycled into this age class; see age.matrix
multinom	FALSE	Include the multinomial constant in the reported log-likelihood.
r0	0.5	effective radius of zero cell in movement kernel (multiple of cell width)
R	FALSE	Switch from the default C++ code to slower functions in native R (useful for debugging; not all models)
squeeze	TRUE	Apply squeeze to capthist before analysis. Non-spatial models fit faster, because histories often non-unique.

If method = "Newton-Raphson" then nlm is used to maximize the log likelihood (minimize the negative log likelihood); otherwise optim is used with the chosen method ("BFGS", "Nelder-Mead", etc.). If maximization fails a warning is given appropriate to the method. method = "none" may be used to compute or re-compute the variance-covariance matrix at given starting values (i.e. providing a previously fitted model as the value of start).

Parameter redundancies are common in open-population models. The output from openCR.fit includes the singular values (eigenvalues) of the Hessian - a useful post-hoc indicator of redundancy (e.g., Gimenez et al. 2004). Eigenvalues are scaled so the largest is 1.0. Very small scaled values represent redundant parameters - in my experience with simple JSSA models a threshold of 0.00001 seems effective.

[There is an undocumented option to fix specific ‘beta’ parameters.]

Value

If details$LLonly == TRUE then a numeric vector is returned with logLik in position 1, followed by the named coefficients.

Otherwise, an object of class ‘openCR’ with components

call	function call
capthist	saved input (unique histories; see covariates(capthist)$freq for frequencies)
type	saved input
model	saved input
distribution	saved input
mask	saved input
detectfn	saved input
binomN	saved input
movementmodel	saved input
edgemethod	saved input
usermodel	saved input
moveargsi	relative positions of move.a and move.b arguments
kernel	coordinates of kernel (movement models only)
start	vector of starting values for beta parameters
link	saved input
fixed	saved input
timecov	saved input
sessioncov	saved input
agecov	saved input
dframe	saved input
dframe0	saved input
details	saved input
method	saved input
ncores	saved input (NULL replaced with default)
design	reduced design matrices, parameter table and parameter index array for actual animals (see openCR.design)
design0	reduced design matrices, parameter table and parameter index array for ‘naive’ animal (see openCR.design)
parindx	list with one component for each real parameter giving the indices of the ‘beta’ parameters associated with each real parameter
intervals	intervals between primary sessions
vars	vector of unique variable names in model
betanames	names of beta parameters
realnames	names of fitted (real) parameters
sessionlabels	name of each primary session
fit	list describing the fit (output from nlm or optim)
beta.vcv	variance-covariance matrix of beta parameters
eigH	vector of eigenvalue corresponding to each beta parameter
version	openCR version number
starttime	character string of date and time at start of fit
proctime	processor time for model fit, in seconds

The environment variable RCPP_PARALLEL_NUM_THREADS is updated with the value of ncores if provided.

Note

Different parameterisations lead to different model fits when used with the default ‘model’ argument in which each real parameter is constrained to be constant over time.

The JSSA implementation uses summation over feasible 'birth' and 'death' times for each capture history, following Pledger et al. (2010). This enables finite mixture models for individual capture probability (not fully tested), flexible handling of additions and losses on capture (aka removals) (not yet programmed), and ultimately the extension to 'unknown age' as in Pledger et al. (2009).

openCR uses the generalized matrix inverse ‘ginv’ from the MASS package rather than ‘solve’ from base R, as this seems more robust to singularities in the Hessian. Also, the default maximization method is ‘BFGS’ rather than ‘Newton-Raphson’ as BFGS appears more robust in the presence of redundant parameters.

Earlier versions of openCR.fit computed latent class membership probabilities for each individual in finite mixture models and saved them in component ‘posterior’. Now see classMembership for that functionality.

From 1.5.0 onwards the number of threads uses the environment variable RCPP_PARALLEL_NUM_THREADS, as in secr.fit. This may be set once in a session with secr::setNumThreads.

The default movement arguments changed in openCR 2.1.1. Now kernelradius = 30, sparsekernel = TRUE.

References

Gimenez, O., Viallefont, A., Catchpole, E. A., Choquet, R. and Morgan, B. J. T. (2004) Methods for investigating parameter redundancy. Animal Biodiversity and Conservation 27, 561–572.

Huggins, R. M. (1989) On the statistical analysis of capture experiments. Biometrika 76, 133–140.

Pledger, S., Efford, M., Pollock. K., Collazo, J. and Lyons, J. (2009) Stopover duration analysis with departure probability dependent on unknown time since arrival. In: D. L. Thompson, E. G. Cooch and M. J. Conroy (eds) Modeling Demographic Processes in Marked Populations. Springer. Pp. 349–363.

Pledger, S., Pollock, K. H. and Norris, J. L. (2010) Open capture–recapture models with heterogeneity: II. Jolly-Seber model. Biometrics 66, 883–890.

Pradel, R. (1996) Utilization of capture-mark-recapture for the study of recruitment and population growth rate. Biometrics 52, 703–709.

Schwarz, C. J. and Arnason, A. N. (1996) A general methodology for the analysis of capture-recapture experiments in open populations. Biometrics 52, 860–873.

See Also

classMembership.openCR, derived.openCR, openCR.design, par.openCR.fit, predict.openCR, summary.openCR

Examples

## Not run: 

## CJS default
openCR.fit(ovenCH)

## POPAN Jolly-Seber Schwarz-Arnason, lambda parameterisation
L1 <- openCR.fit(ovenCH, type = 'JSSAl')
predict(L1)

JSSA1 <- openCR.fit(ovenCH, type = 'JSSAf')
JSSA2 <- openCR.fit(ovenCH, type = 'JSSAf', model = list(phi~t))
JSSA3 <- openCR.fit(ovenCH, type = 'JSSAf', model = list(p~t,phi~t))
AIC (JSSA1, JSSA2, JSSA3)
predict(JSSA1)

RMdata <- RMarkInput (join(reduce(ovenCH, by = "all")))
if (require(RMark)) {
    MarkPath <- 'c:/Mark/'
    if (!all (nchar(Sys.which(c('mark.exe', 'mark64.exe', 'mark32.exe'))) < 2)) {
        openCHtest <- process.data(RMdata, model = 'POPAN')
        openCHPOPAN <- mark(data = openCHtest, model = 'POPAN',
            model.parameters = list(p = list(formula = ~1),
            pent = list(formula = ~1),
            Phi = list(formula = ~1)))
        popan.derived(openCHtest, openCHPOPAN)
        cleanup(ask = FALSE)
    } else message ("mark.exe not found")
} else message ("RMark not found")


## End(Not run)

openCR documentation built on Sept. 25, 2022, 5:06 p.m.