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.