dOcc {nimbleEcology}

Occupancy distribution suitable for use in nimble models

Description

dOcc_* and rOcc_* provide occupancy model distributions that can be used directly from R or in nimble models.

Usage

dOcc_s(x, probOcc, probDetect, len = 0, log = 0)

dOcc_v(x, probOcc, probDetect, len = 0, log = 0)

rOcc_s(n, probOcc, probDetect, len = 0)

rOcc_v(n, probOcc, probDetect, len = 0)

Arguments

x

detection/non-detection vector of 0s (not detected) and 1s (detected).

probOcc

occupancy probability (scalar).

probDetect

detection probability (scalar for dOcc_s, vector for dOcc_v).

len

length of detection/non-detection vector (see below).

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.

Details

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

The probability of observation vector x depends on occupancy probability, probOcc, and detection probability, probDetect or probDetect[1:T].

The letter following the 'dOcc_' indicates whether detection probability is scalar (s, meaning probDetect is detection probability for every x[t]) or vector (v, meaning probDetect[t] is detection probability for x[t]).

When used directly from R, the len argument to dOcc_* 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 occupancy status and a separate scalar datum for each observation, use of these distributions allows one to directly sum (marginalize) over the discrete latent state and calculate the probability of all observations from one site 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,

detections[i, 1:T] ~ dOcc_s(occupancyProbability, detectionProbability, T)

declares that detections[i, 1:T] (detection history at site i, for example) follows an occupancy distribution with parameters as indicated, assuming all the parameters have been declared elsewhere in the model. This will invoke (something like) the following call to dOcc_s when nimble uses the model such as for MCMC:

dOcc_s(detections[i, 1:T], occupancyProbability, detectionProbability, len = T, log = TRUE)

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

If the detection probabilities are time-dependent, use:

detections[i, 1:T] ~ dOcc_v(occupancyProbability, detectionProbability[1:T], len = T)

Value

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

For rOcc_*: a simulated detection history, x.

Notes for use with automatic differentiation

The dOcc_* distributions should all work for models and algorithms that use nimble's automatic differentiation (AD) system. In that system, some kinds of values are "baked in" (cannot be changed) to the AD calculations from the first call, unless and until the AD calculations are reset. For the dOcc_* distributions, the lengths of vector inputs are baked in. These can be different for different iterations through a for loop (or nimble model declarations with different indices, for example), but the lengths for each specific iteration will be "baked in" after the first call. It is safest if one can assume that x are data and are not going to change.

Author(s)

Ben Goldstein, Perry de Valpine, and Lauren Ponisio

See Also

For dynamic occupancy models, see documentation for dDynOcc.

Examples

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


# Define code for a nimbleModel
nc <- nimbleCode({
  x[1:4] ~ dOcc_s(probOcc, probDetect, len = 4)
  probOcc ~ dunif(0,1)
  probDetect ~ dunif(0,1)
})

# Build the model, providing data and initial values
Occ_model <- nimbleModel(nc, data = list(x = dat),
                         inits = list(probOcc = probOcc,
                                      probDetect = probDetect))

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