dCJS: Cormack-Jolly-Seber distribution for use in 'nimble' models
In nimbleEcology: Distributions for Ecological Models in 'nimble'

Description Usage Arguments Details Value Author(s) References See Also Examples

dCJS_** and rCJS_** provide Cormack-Jolly-Seber capture-recapture distributions that can be used directly from R or in nimble models.

dCJS_ss(x, probSurvive, probCapture, len = 0, log = 0)

dCJS_sv(x, probSurvive, probCapture, len = 0, log = 0)

dCJS_vs(x, probSurvive, probCapture, len = 0, log = 0)

dCJS_vv(x, probSurvive, probCapture, len = 0, log = 0)

rCJS_ss(n, probSurvive, probCapture, len = 0)

rCJS_sv(n, probSurvive, probCapture, len = 0)

rCJS_vs(n, probSurvive, probCapture, len = 0)

rCJS_vv(n, probSurvive, probCapture, len = 0)

`x`	capture history vector of 0s (not captured) and 1s (captured). Include the initial capture, so `x[1]` should equal 1.
`probSurvive`	survival probability, either a time-independent scalar (for dCJS_s) or a time-dependent vector (for dCJS_v) with length `len - 1`.
`probCapture`	capture probability, either a time-independent scalar (for dCJS_s) or a time-dependent vector (for dCJS_v) with length `len`. If a vector, first element is ignored, as the total probability is conditioned on the capture at `t = 1`.
`len`	length of capture history. Should equal `length(x)`
`log`	TRUE or 1 to return log probability. FALSE or 0 to return probability.
`n`	number of random draws, each returning a vector of length `len`. Currently only `n = 1` is supported, but the argument exists for standardization of "`r`" functions.

These nimbleFunctions provide distributions that can be used directly in R or in nimble hierarchical models (via nimbleCode and nimbleModel).

The letters following the 'dCJS_' indicate whether survival and/or capture probabilities, in that order, are scalar (s, meaning the probability applies to every x[t]) or vector (v, meaning the probability is a vector aligned with x). When probCapture and/or probSurvive is a vector, they must be the same length as x.

It is important to use the time indexing correctly for survival. probSurvive[t] is the survival probabilty from time t to time t + 1. When a vector, probSurvive may have length greater than length(x) - 1, but all values beyond that index are ignored.

Time indexing for detection is more obvious: probDetect[t] is the detection probability at time t.

When called from R, the len argument to dCJS_** is not necessary. It will default to the length of x. When used in nimble model code (via nimbleCode), len must be provided (even though it may seem redundant).

For more explanation, see package vignette (vignette("Introduction_to_nimbleEcology")).

Compared to writing nimble models with a discrete latent state for true alive/dead status at each time and a separate scalar datum for each observation, use of these distributions allows one to directly sum (marginalize) over the discrete latent states and calculate the probability of the detection history for one individual jointly.

These are nimbleFunctions written in the format of user-defined distributions for NIMBLE's extension of the BUGS model language. More information can be found in the NIMBLE User Manual at https://r-nimble.org.

When using these distributions in a nimble model, the left-hand side will be used as x, and the user should not provide the log argument.

For example, in nimble model code,

captures[i, 1:T] ~ dCSJ_ss(survive, capture, T)

declares a vector node, captures[i, 1:T], (detection history for individual i, for example) that follows a CJS distribution with scalar survival probability survive and scalar capture probability capture (assuming survive and capture are defined elsewhere in the model).

This will invoke (something like) the following call to dCJS_ss when nimble uses the model such as for MCMC:

dCJS_ss(captures[i, 1:T], survive, capture, len = T, log = TRUE)

If an algorithm using a nimble model with this declaration needs to generate a random draw for captures[i, 1:T], it will make a similar invocation of rCJS_ss, with n = 1.

If both survival and capture probabilities are time-dependent, use

captures[i,1:T] ~ dCSJ_vv(survive[1:(T-1)], capture[1:T], T)

and so on for each combination of time-dependent and time-independent parameters.

For dCJS_**: the probability (or likelihood) or log probability of observation vector x.

For rCJS_**: a simulated capture history, x.

Ben Goldstein, Perry de Valpine, and Daniel Turek

D. Turek, P. de Valpine and C. J. Paciorek. 2016. Efficient Markov chain Monte Carlo sampling for hierarchical hidden Markov models. Environmental and Ecological Statistics 23:549–564. DOI 10.1007/s10651-016-0353-z

For multi-state or multi-event capture-recapture models, see dHMM or dDHMM.

# Set up constants and initial values for defining the model
dat <- c(1,1,0,0,0) # A vector of observations
probSurvive <- c(0.6, 0.3, 0.3, 0.1)
probCapture <- 0.4


# Define code for a nimbleModel
nc <- nimbleCode({
  x[1:4] ~ dCJS_vs(probSurvive[1:4], probCapture, len = 4)
  probCapture ~ dunif(0,1)
  for (i in 1:4) probSurvive[i] ~ dunif(0, 1)
})

# Build the model, providing data and initial values
CJS_model <- nimbleModel(nc, data = list(x = dat),
                         inits = list(probSurvive = probSurvive,
                                      probCapture = probCapture))

# Calculate log probability of data from the model
CJS_model$calculate()
# Use the model for a variety of other purposes...