# Fit spatially-explicit population abundance models for capture-mark-recapture data consisting of multiple non-invasive marks This function fits spatially-explicit population abundance models for 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. ```r multimarkClosedSCR( Enc.Mat, trapCoords, studyArea = NULL, buffer = NULL, ncells = 1024, data.type = "never", covs = data.frame(), mms = NULL, mod.p = ~1, mod.delta = ~type, detection = "half-normal", parms = c("pbeta", "delta", "N"), nchains = 1, iter = 12000, adapt = 1000, bin = 50, thin = 1, burnin = 2000, taccept = 0.44, tuneadjust = 0.95, proppbeta = 0.1, propsigma = 1, propcenter = NULL, maxnumbasis = 1, a0delta = 1, a0alpha = 1, b0alpha = 1, sigma_bounds = NULL, mu0 = 0, sigma2_mu0 = 1.75, a0psi = 1, b0psi = 1, initial.values = NULL, known = integer(), scalemax = 10, printlog = FALSE, ... ) ``` ## Arguments - `Enc.Mat`: A matrix containing the observed encounter histories with rows corresponding to individuals and (`ntraps`*`noccas`) columns corresponding to traps and sampling occasions. The first `noccas` columns correspond to trap 1, the second `noccas` columns corresopond to trap 2, etc. Ignored unless `mms=NULL`. - `trapCoords`: A matrix of dimension `ntraps` x (2 + `noccas`) indicating the Cartesian coordinates and operating occasions for the traps, where rows correspond to trap, the first column the x-coordinate (``x''), and the second column the y-coordinate (``y''). The last `noccas` columns indicate whether or not the trap was operating on each of the occasions, where `1' indciates the trap was operating and `0' indicates the trap was not operating. Ignored unless `mms=NULL`. - `studyArea`: is a 3-column matrix containing the coordinates for the centroids of a contiguous grid of cells that define the study area and available habitat. Each row corresponds to a grid cell. The first 2 columns (``x'' and ``y'') indicate the Cartesian x- and y-coordinate for the centroid of each grid cell, and the third column (``avail'') indicates whether the cell is available habitat (=1) or not (=0). All cells must be square and have the same resolution. If `studyArea=NULL` (the default) and `mms=NULL`, then a square study area grid composed of `ncells` cells of available habitat is drawn around the bounding box of `trapCoords` based on `buffer`. Ignored unless `mms=NULL`. Note that rows should be ordered in raster cell order (raster cell numbers start at 1 in the upper left corner, and increase from left to right, and then from top to bottom). - `buffer`: A scaler in same units as `trapCoords` indicating the buffer around the bounding box of `trapCoords` for defining the study area when `studyArea=NULL`. Ignored unless `studyArea=NULL` and `mms=NULL`. - `ncells`: The number of grid cells in the study area when `studyArea=NULL`. The square root of `ncells` must be a whole number. Default is `ncells=1024`. Ignored unless `studyArea=NULL` and `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 time- and/or trap-dependent covariates for detection probabilities (ignored unless `mms=NULL`). The number of rows in the data frame must equal the number of traps times the number of sampling occasions (`ntraps*noccas`), where the first `noccas` rows correspond to trap 1, the second `noccas` rows correspond to trap 2, etc. 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 `multimarkSCRsetup-class`; if `NULL` it is created. See `processdataSCR`. - `mod.p`: Model formula for detection probability as a function of distance from activity centers. For example, `mod.p=~1` specifies no effects (i.e., intercept only) other than distance, `mod.p~time` specifies temporal effects, `mod.p~c` specifies behavioral reponse (i.e., trap "happy" or "shy"), `mod.p~trap` specifies trap effects, and `mod.p~time+c` specifies additive temporal and behavioral 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. - `detection`: Model for detection probability as a function of distance from activity centers . Must be "`half-normal`" (of the form $\exp{(-d^2 / (2*\sigma^2))}$, where $d$ is distance) or "`exponential`" (of the form $\exp{(-d / \lambda)}$). - `parms`: A character vector giving the names of the parameters and latent variables to monitor. Possible parameters are cloglog-scale detection probability parameters ("`pbeta`"), population abundance ("`N`"), 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`"), cloglog-scale distance term for the detection function ("`sigma2_scr`" when ```detection=``half-normal''``` or "`lambda`" when ```detection=``exponential''```), 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 activity centers ("`centers`"), encounter history indices ("`H`"), and the log posterior density ("`logPosterior`") 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`: The number of iterations for proposal distribution adaptation. If `adapt = 0` then no adaptation occurs. - `bin`: Bin length for calculating acceptance rates during adaptive phase (`0 < bin <= iter`). - `thin`: Thinning interval for monitored parameters. - `burnin`: Number of burn-in iterations (`0 <= burnin < iter`). - `taccept`: Target acceptance rate during adaptive phase (`0 < taccept <= 1`). Acceptance rate is monitored every `bin` iterations. Default is `taccept = 0.44`. - `tuneadjust`: Adjustment term during adaptive phase (`0 < tuneadjust <= 1`). If acceptance rate is less than `taccept`, then proposal term (`proppbeta` or `propsigma`) is multiplied by `tuneadjust`. If acceptance rate is greater than or equal to `taccept`, then proposal term is divided by `tuneadjust`. Default is `tuneadjust = 0.95`. - `proppbeta`: Scaler or vector (of length k) specifying the initial standard deviation of the Normal(pbeta[j], proppbeta[j]) proposal distribution. If `proppbeta` is a scaler, then this value is used for all j = 1, ..., k. Default is `proppbeta = 0.1`. - `propsigma`: Scaler specifying the initial Gamma(shape = 1/`propsigma`, scale = sigma_scr * `propsigma`) proposal distribution for sigma_scr = sqrt(sigma2_scr) (or sqrt(lambda) = lambda if ```detection=``exponential''```). Default is `propsigma=1`. - `propcenter`: Scaler specifying the neighborhood distance when proposing updates to activity centers. When `propcenter=NULL` (the default), then propcenter = a*10, where a is the cell size for the study area grid, and each cell has (at most) approximately 300 neighbors. - `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. - `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). - `sigma_bounds`: Positive vector of length 2 for the lower and upper bounds for the [sigma_scr] ~ Uniform(sigma_bounds[1], sigma_bounds[2]) (or [sqrt(lambda)] when ```detection=``exponential''```) prior for the detection function term sigma_scr = sqrt(sigma2_scr) (or sqrt(lambda)). When `sigma_bounds = NULL` (the default), then `sigma_bounds =c(1.e-6,max(diff(range(studyArea[,"x"])),diff(range(studyArea[,"y"]))))`. - `mu0`: Scaler or vector (of length k) specifying mean of pbeta[j] ~ Normal(mu0[j], sigma2_mu0[j]) prior. If `mu0` is a scaler, then this value is used for all j = 1, ..., k. Default is `mu0 = 0`. - `sigma2_mu0`: Scaler or vector (of length k) specifying variance of pbeta[j] ~ Normal(mu0[j], sigma2_mu0[j]) prior. If `sigma2_mu0` is a scaler, then this value is used for all j = 1, ..., k. Default is `sigma2_mu0 = 1.75`. - `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`", "`N`", "`delta_1`", "`delta_2`", "`alpha`", "`sigma2_scr`", "`centers`", and "`psi`"), initial values can be specified for the initial latent history frequencies ("`x`") and initial individual encounter history indices ("`H`"). - `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. - `scalemax`: Upper bound for internal re-scaling of grid cell centroid coordinates. Default is `scalemax=10`, which re-scales the centroids to be between 0 and 10. Re-scaling is done internally to avoid numerical overflows during model fitting. Ignored unless `mms=NULL`. - `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`. See `make.design.data`. ## Returns 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.delta**: Model formula for conditional probability of type 1 or type 2 encounter, given detection (as specified by `mod.delta` above). - **mod.det**: Model formula for detection function (as specified by `detection` above). - **DM**: A list of design matrices for detection probability generated for model `mod.p`, where DM$p is the design matrix for initial capture probability (p) and DM$c is the design matrix for recapture probability (c). - **initial.values**: A list containing the parameter and latent variable values at iteration `iter` for each chain. Values are provided for "`pbeta`", "`N`", "`delta_1`", "`delta_2`", "`alpha`", "`sigma2_scr`", "`centers`", "`psi`", "`x`", and "`H`". - **mms**: An object of class `multimarkSCRsetup` ## Details The first time `multimarkSCRClosed` 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 `multimarkClosed`. Note that setting `parms="all"` is required for any `multimarkClosed` model output to be used in `multimodelClosed`. ## Examples ```r # This example is excluded from testing to reduce package check time # Example uses unrealistically low values for nchain, iter, and burnin #Generate object of class "multimarkSCRsetup" from simulated data sim.data<-simdataClosedSCR() Enc.Mat <- sim.data$Enc.Mat trapCoords <- sim.data$spatialInputs$trapCoords studyArea <- sim.data$spatialInputs$studyArea #Run single chain using the default model for simulated data example.dot<-multimarkClosedSCR(Enc.Mat,trapCoords,studyArea) #Posterior summary for monitored parameters summary(example.dot$mcmc) plot(example.dot$mcmc) ``` ## References Bonner, S. J., and Holmberg J. 2013. Mark-recapture with multiple, non-invasive marks. **Biometrics** 69: 766-775. Gopalaswamy, A.M., Royle, J.A., Hines, J.E., Singh, P., Jathanna, D., Kumar, N. and Karanth, K.U. 2012. Program SPACECAP: software for estimating animal density using spatially explicit capture-recapture models. **Methods in Ecology and Evolution** 3:1067-1072. King, R., McClintock, B. T., Kidney, D., and Borchers, D. L. 2016. Capture-recapture abundance estimation using a semi-complete data likelihood approach. **The Annals of Applied Statistics** 10: 264-285 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. Royle, J.A., Karanth, K.U., Gopalaswamy, A.M. and Kumar, N.S. 2009. Bayesian inference in camera trapping studies for a class of spatial capture-recapture models. **Ecology** 90: 3233-3244. ## See Also `processdataSCR`. ## Author(s) Brett T. McClintock

multimarkClosedSCR function