multimarkCJS {multimark}

Fit open population survival models for capture-mark-recapture data consisting of multiple non-invasive marks

Description

This function fits Cormack-Jolly-Seber (CJS) open population models for survival probability (\phi) and capture probability (p) from capture-mark-recapture data consisting of multiple non-invasive marks. Using Bayesian analysis methods, Markov chain Monte Carlo (MCMC) is used to draw samples from the joint posterior distribution.

Usage

multimarkCJS(
  Enc.Mat,
  data.type = "never",
  covs = data.frame(),
  mms = NULL,
  mod.p = ~1,
  mod.phi = ~1,
  mod.delta = ~type,
  parms = c("pbeta", "phibeta", "delta"),
  nchains = 1,
  iter = 12000,
  adapt = 1000,
  bin = 50,
  thin = 1,
  burnin = 2000,
  taccept = 0.44,
  tuneadjust = 0.95,
  proppbeta = 0.1,
  propzp = 1,
  propsigmap = 1,
  propphibeta = 0.1,
  propzphi = 1,
  propsigmaphi = 1,
  maxnumbasis = 1,
  pbeta0 = 0,
  pSigma0 = 1,
  phibeta0 = 0,
  phiSigma0 = 1,
  l0p = 1,
  d0p = 0.01,
  l0phi = 1,
  d0phi = 0.01,
  a0delta = 1,
  a0alpha = 1,
  b0alpha = 1,
  a0psi = 1,
  b0psi = 1,
  initial.values = NULL,
  known = integer(),
  link = "probit",
  printlog = FALSE,
  ...
)

Arguments

Enc.Mat

A matrix of observed encounter histories with rows corresponding to individuals and columns corresponding to sampling occasions (ignored unless mms=NULL).

data.type

Specifies the encounter history data type. All data types include non-detections (type 0 encounter), type 1 encounter (e.g., left-side), and type 2 encounters (e.g., right-side). When both type 1 and type 2 encounters occur for the same individual within a sampling occasion, these can either be "non-simultaneous" (type 3 encounter) or "simultaneous" (type 4 encounter). Three data types are currently permitted:

data.type="never" indicates both type 1 and type 2 encounters are never observed for the same individual within a sampling occasion, and observed encounter histories therefore include only type 1 or type 2 encounters (e.g., only left- and right-sided photographs were collected). Observed encounter histories can consist of non-detections (0), type 1 encounters (1), and type 2 encounters (2). See bobcat. Latent encounter histories consist of non-detections (0), type 1 encounters (1), type 2 encounters (2), and type 3 encounters (3).

data.type="sometimes" indicates both type 1 and type 2 encounters are sometimes observed (e.g., both-sided photographs are sometimes obtained, but not necessarily for all individuals). Observed encounter histories can consist of non-detections (0), type 1 encounters (1), type 2 encounters (2), type 3 encounters (3), and type 4 encounters (4). Type 3 encounters can only be observed when an individual has at least one type 4 encounter. Latent encounter histories consist of non-detections (0), type 1 encounters (1), type 2 encounters (2), type 3 encounters (3), and type 4 encounters (4).

data.type="always" indicates both type 1 and type 2 encounters are always observed, but some encounter histories may still include only type 1 or type 2 encounters. Observed encounter histories can consist of non-detections (0), type 1 encounters (1), type 2 encounters (2), and type 4 encounters (4). Latent encounter histories consist of non-detections (0), type 1 encounters (1), type 2 encounters (2), and type 4 encounters (4).

covs

A data frame of temporal covariates for detection probabilities (ignored unless mms=NULL). The number of rows in the data frame must equal the number of sampling occasions. Covariate names cannot be "time", "age", or "h"; these names are reserved for temporal, behavioral, and individual effects when specifying mod.p and mod.phi.

mms

An optional object of class multimarksetup-class; if NULL it is created. See processdata.

mod.p

Model formula for detection probability (p). For example, mod.p=~1 specifies no effects (i.e., intercept only), mod.p~time specifies temporal effects, mod.p~age specifies age effects, mod.p~h specifies individual heterogeneity, and mod.p~time+age specifies additive temporal and age effects.

mod.phi

Model formula for survival probability (\phi). For example, mod.phi=~1 specifies no effects (i.e., intercept only), mod.phi~time specifies temporal effects, mod.phi~age specifies age effects, mod.phi~h specifies individual heterogeneity, and mod.phi~time+age specifies additive temporal and age effects.

mod.delta

Model formula for conditional probabilities of type 1 (delta_1) and type 2 (delta_2) encounters, given detection. Currently only mod.delta=~1 (i.e., \delta_1 = \delta_2) and mod.delta=~type (i.e., \delta_1 \ne \delta_2) are implemented.

parms

A character vector giving the names of the parameters and latent variables to monitor. Possible parameters are probit-scale detection probability parameters ("pbeta" for p and "phibeta" for \phi), conditional probability of type 1 or type 2 encounter, given detection ("delta)", probability of simultaneous type 1 and type 2 detection, given both types encountered ("alpha"), probit-scale individual heterogeneity variance terms ("sigma2_zp" for p and "sigma2_zphi" for \phi), probit-scale individual effects ("zp" and "zphi"), and the probability that a randomly selected individual from the M = nrow(Enc.Mat) observed individuals belongs to the n unique individuals encountered at least once ("psi"). Individual encounter history indices ("H"), latent variable indicators for whether each individual was alive (1) or dead (0) during each sampling occasion ("q"), and the log likelihood ("loglike") may also be monitored. Setting parms="all" monitors all possible parameters and latent variables.

nchains

The number of parallel MCMC chains for the model.

iter

The number of MCMC iterations.

adapt

Ignored; no adaptive phase is needed for "probit" link.

bin

Ignored; no adaptive phase is needed for "probit" link.

thin

Thinning interval for monitored parameters.

burnin

Number of burn-in iterations (0 <= burnin < iter).

taccept

Ignored; no adaptive phase is needed for "probit" link.

tuneadjust

Ignored; no adaptive phase is needed for "probit" link.

proppbeta

Ignored; no adaptive phase is needed for "probit" link.

propzp

Ignored; no adaptive phase is needed for "probit" link.

propsigmap

Ignored; no adaptive phase is needed for "probit" link.

propphibeta

Ignored; no adaptive phase is needed for "probit" link.

propzphi

Ignored; no adaptive phase is needed for "probit" link.

propsigmaphi

Ignored; no adaptive phase is needed for "probit" link.

maxnumbasis

Maximum number of basis vectors to use when proposing latent history frequency updates. Default is maxnumbasis = 1, but higher values can potentially improve mixing.

pbeta0

Scaler or vector (of length k) specifying mean of pbeta ~ multivariateNormal(pbeta0, pSigma0) prior. If pbeta0 is a scaler, then this value is used for all j = 1, ..., k. Default is pbeta0 = 0.

pSigma0

Scaler or k x k matrix specifying covariance matrix of pbeta ~ multivariateNormal(pbeta0, pSigma0) prior. If pSigma0 is a scaler, then this value is used for all pSigma0[j,j] for j = 1, ..., k (with pSigma[j,l] = 0 for all j \ne l). Default is pSigma0 = 1.

phibeta0

Scaler or vector (of length k) specifying mean of phibeta ~ multivariateNormal(phibeta0, phiSigma0) prior. If phibeta0 is a scaler, then this value is used for all j = 1, ..., k. Default is phibeta0 = 0.

phiSigma0

Scaler or k x k matrix specifying covariance matrix of phibeta ~ multivariateNormal(phibeta0, phiSigma0) prior. If phiSigma0 is a scaler, then this value is used for all phiSigma0[j,j] for j = 1, ..., k (with phiSigma[j,l] = 0 for all j \ne l). Default is phiSigma0 = 1.

l0p

Specifies "shape" parameter for [sigma2_zp] ~ invGamma(l0p,d0p) prior. Default is l0p = 1.

d0p

Specifies "scale" parameter for [sigma2_zp] ~ invGamma(l0p,d0p) prior. Default is d0p = 0.01.

l0phi

Specifies "shape" parameter for [sigma2_zphi] ~ invGamma(l0phi,d0phi) prior. Default is l0phi = 1.

d0phi

Specifies "scale" parameter for [sigma2_zphi] ~ invGamma(l0phi,d0phi) prior. Default is d0phi = 0.01.

a0delta

Scaler or vector (of length d) specifying the prior for the conditional (on detection) probability of type 1 (delta_1), type 2 (delta_2), and both type 1 and type 2 encounters (1-delta_1-delta_2). If a0delta is a scaler, then this value is used for all a0delta[j] for j = 1, ..., d. For mod.delta=~type, d=3 with [delta_1, delta_2, 1-delta_1-delta_2] ~ Dirichlet(a0delta) prior. For mod.delta=~1, d=2 with [tau] ~ Beta(a0delta[1],a0delta[2]) prior, where (delta_1,delta_2,1-delta_1-delta_2) = (tau/2,tau/2,1-tau). See McClintock et al. (2013) for more details.

a0alpha

Specifies "shape1" parameter for [alpha] ~ Beta(a0alpha, b0alpha) prior. Only applicable when data.type = "sometimes". Default is a0alpha = 1. Note that when a0alpha = 1 and b0alpha = 1, then [alpha] ~ Unif(0,1).

b0alpha

Specifies "shape2" parameter for [alpha] ~ Beta(a0alpha, b0alpha) prior. Only applicable when data.type = "sometimes". Default is b0alpha = 1. Note that when a0alpha = 1 and b0alpha = 1, then [alpha] ~ Unif(0,1).

a0psi

Specifies "shape1" parameter for [psi] ~ Beta(a0psi,b0psi) prior. Default is a0psi = 1.

b0psi

Specifies "shape2" parameter for [psi] ~ Beta(a0psi,b0psi) prior. Default is b0psi = 1.

initial.values

Optional list of nchain list(s) specifying initial values for parameters and latent variables. Default is initial.values = NULL, which causes initial values to be generated automatically. In addition to the parameters ("pbeta", "phibeta", "delta_1", "delta_2", "alpha", "sigma2_zp", "sigma2_zphi", "zp", "zphi", and "psi"), initial values can be specified for the initial latent history frequencies ("x"), initial individual encounter history indices ("H"), and initial latent variable indicators for whether each individual was alive (1) or dead (0) during each sampling occasion ("q").

known

Optional integer vector indicating whether the encounter history of an individual is known with certainty (i.e., the observed encounter history is the true encounter history). Encounter histories with at least one type 4 encounter are automatically assumed to be known, and known does not need to be specified unless there exist encounter histories that do not contain a type 4 encounter that happen to be known with certainty (e.g., from independent telemetry studies). If specified, known = c(v_1,v_2,...,v_M) must be a vector of length M = nrow(Enc.Mat) where v_i = 1 if the encounter history for individual i is known (v_i = 0 otherwise). Note that known all-zero encounter histories (e.g., ‘000’) are ignored.

link

Link function for survival and capture probabilities. Only probit link is currently implemented.

printlog

Logical indicating whether to print the progress of chains and any errors to a log file in the working directory. Ignored when nchains=1. Updates are printed to log file as 1% increments of iter of each chain are completed. With >1 chains, setting printlog=TRUE is probably most useful for Windows users because progress and errors are automatically printed to the R console for "Unix-like" machines (i.e., Mac and Linux) when printlog=FALSE. Default is printlog=FALSE.

...

Additional "parameters" arguments for specifying mod.p and mod.phi. See RMark::make.design.data.

Details

The first time multimarkCJS (or multimarkClosed) is called, it will likely produce a firewall warning alerting users that R has requested the ability to accept incoming network connections. Incoming network connections are required to use parallel processing as implemented in multimarkCJS. Note that setting parms="all" is required for any multimarkCJS model output to be used in multimodelCJS.

Value

A list containing the following:

mcmc

Markov chain Monte Carlo object of class mcmc.list.

mod.p

Model formula for detection probability (as specified by mod.p above).

mod.phi

Model formula for survival probability (as specified by mod.phi above).

mod.delta

Formula always NULL; only for internal use in multimodelCJS.

DM

A list of design matrices for detection and survival probability respectively generated by mod.p and mod.phi, where DM$p is the design matrix for capture probability (p) and DM$phi is the design matrix for survival probability (\phi).

initial.values

A list containing the parameter and latent variable values at iteration iter for each chain. Values are provided for "pbeta", "phibeta", "delta_1", "delta_2", "alpha", "sigma2_zp" "sigma2_zphi", "zp", "zphi", "psi", "x", "H", and "q".

mms

An object of class multimarksetup

Author(s)

Brett T. McClintock

References

Bonner, S. J., and Holmberg J. 2013. Mark-recapture with multiple, non-invasive marks. Biometrics 69: 766-775.

McClintock, B. T., Conn, P. B., Alonso, R. S., and Crooks, K. R. 2013. Integrated modeling of bilateral photo-identification data in mark-recapture analyses. Ecology 94: 1464-1471.

McClintock, B. T., Bailey, L. L., Dreher, B. P., and Link, W. A. 2014. Probit models for capture-recapture data subject to imperfect detection, individual heterogeneity and misidentification. The Annals of Applied Statistics 8: 2461-2484.

See Also

processdata, multimodelCJS

Examples

# This example is excluded from testing to reduce package check time
# Example uses unrealistically low values for nchain, iter, and burnin

#Simulate open population data using defaults
data <- simdataCJS()

#Fit default open population model
sim.dot <- multimarkCJS(data$Enc.Mat)

#Posterior summary for monitored parameters
summary(sim.dot$mcmc)
plot(sim.dot$mcmc)

#' #Fit ``age'' model with 2 age classes (e.g., juvenile and adult) for survival
#using 'parameters' and 'right' arguments from RMark::make.design.data
sim.age <- multimarkCJS(data$Enc.Mat,mod.phi=~age,
           parameters=list(Phi=list(age.bins=c(0,1,4))),right=FALSE)
summary(getprobsCJS(sim.age))