openCR.fit {openCR}

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
agebreaks	minimumage:maximumage	Limits of age classes (vector passed to cut)
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.
userdist	NULL	Function to compute distances (see secr)
stepmax	NULL	stepmax argument of nlm (step on link scale)

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

Numeric ages may be grouped into age classes by providing ‘agebreaks’. In models, ~age then refers to the age-class factor. See the vignette for more detail.

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

primaryintervals

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)