diff --git a/NAMESPACE b/NAMESPACE index 976b546..322fa58 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -52,3 +52,4 @@ import(nimble) importFrom(stats,dbinom) importFrom(stats,rbinom) importFrom(stats,runif) +importFrom("stats", "dpois", "qpois", "rpois") diff --git a/man/dDHMM.Rd b/man/dDHMM.Rd index 8d04dfb..62a8523 100644 --- a/man/dDHMM.Rd +++ b/man/dDHMM.Rd @@ -5,7 +5,7 @@ \alias{dDHMMo} \alias{rDHMM} \alias{rDHMMo} -\title{Dynamic Hidden Markov Model distribution for use in NIMBLE models} +\title{Dynamic Hidden Markov Model distribution for use in \code{nimble} models} \usage{ dDHMM(x, init, probObs, probTrans, len, log = 0) @@ -52,7 +52,7 @@ For \code{rDHMM} and \code{rDHMMo}: a simulated detection history, \code{x}. } \description{ \code{dDHMM} and \code{dDHMMo} provide Dynamic hidden Markov model -distributions for NIMBLE models. +distributions for \code{nimble} models. } \details{ These nimbleFunctions provide distributions that can be used directly in R or diff --git a/man/dDynOcc.Rd b/man/dDynOcc.Rd index 44463a2..ec3ff78 100644 --- a/man/dDynOcc.Rd +++ b/man/dDynOcc.Rd @@ -26,7 +26,7 @@ \alias{rDynOcc_vss} \alias{rDynOcc_svs} \alias{rDynOcc_sss} -\title{Dynamic occupancy distribution for use in NIMBLE models +\title{Dynamic occupancy distribution for use in \code{nimble} models \code{dDynOcc_**} and \code{rDynOcc_**} provide dynamic occupancy model distributions that can be used directly from R or in \code{nimble} models.} @@ -122,7 +122,7 @@ of observation vector \code{x}. For \code{rDynOcc_***}: a simulated detection history, \code{x}. } \description{ -Dynamic occupancy distribution for use in NIMBLE models +Dynamic occupancy distribution for use in \code{nimble} models \code{dDynOcc_**} and \code{rDynOcc_**} provide dynamic occupancy model distributions that can be used directly from R or in \code{nimble} models. diff --git a/man/dHMM.Rd b/man/dHMM.Rd index 8df744f..5c8d6d5 100644 --- a/man/dHMM.Rd +++ b/man/dHMM.Rd @@ -5,7 +5,7 @@ \alias{dHMMo} \alias{rHMM} \alias{rHMMo} -\title{Hidden Markov Model distribution for use in NIMBLE models} +\title{Hidden Markov Model distribution for use in \code{nimble} models} \usage{ dHMM(x, init, probObs, probTrans, len = 0, log = 0) diff --git a/man/dNmixture.Rd b/man/dNmixture.Rd index cae9ce8..7e6e34a 100644 --- a/man/dNmixture.Rd +++ b/man/dNmixture.Rd @@ -6,7 +6,7 @@ \alias{dNmixture_v} \alias{rNmixture_s} \alias{rNmixture_v} -\title{N-mixture distribution for use in NIMBLE models} +\title{N-mixture distribution for use in \code{nimble} models} \usage{ dNmixture_v(x, lambda, prob, Nmin = -1, Nmax = -1, len, log = 0) @@ -17,22 +17,19 @@ rNmixture_v(n, lambda, prob, Nmin = -1, Nmax = -1, len) rNmixture_s(n, lambda, prob, Nmin = -1, Nmax = -1, len) } \arguments{ -\item{x}{count observation data. 0 and positive integers} +\item{x}{vector of integer counts from a series of sampling occasions.} \item{lambda}{expected value of the Poisson distribution of true abundance} -\item{prob}{observation probability for each X} +\item{prob}{detection probability (scalar for \code{dNmixture_s}, vector for \code{dNmixture_v}).} -\item{Nmin}{the minimum abundance to sum over. Set to -1 for distribution -to select based on lambda} +\item{Nmin}{minimum abundance to sum over for the mixture probability. Set to -1 to select automatically.} -\item{Nmax}{the maximum abundance to sum over. Set to -1 for distribution -to select based on lambda} +\item{Nmax}{maximum abundance to sum over for the mixture probability. Set to -1 to select automatically.} \item{len}{The length of the x vector} -\item{log}{TRUE or 1 to return log probability. FALSE or 0 to return probability. -Need not be specified in the model context.} +\item{log}{TRUE or 1 to return log probability. FALSE or 0 to return probability.} \item{n}{number of random draws, each returning a vector of length \code{len}. Currently only \code{n = 1} is supported, but the @@ -45,43 +42,58 @@ probability of observation vector \code{x}. For \code{rNmixture_s} and \code{rNmixture_v}: a simulated detection history, \code{x}. } \description{ -\code{dNmixture_s} and \code{dNmixture_v} provides dynamic occupancy model distributions for NIMBLE models. +\code{dNmixture_s} and \code{dNmixture_v} provide Poisson-Binomial mixture distributions of abundance ("N-mixture") for use in \code{nimble}a models. } \details{ -These nimbleFunctions provide distributions that can be used directly in R or -in \code{nimble} hierarchical models (via \code{\link[nimble]{nimbleCode}} -and \code{\link[nimble]{nimbleModel}}). - -N-mixture models describe abundance at a series of sites over many replicate observations. -The likelihood of an observation in site \code{s} at visit \code{t} depends on the -true abundance N, which is assumed to be drawn from a Poisson distribution with -mean \code{lambda}. It also depends on the probability of detecting an individual -(\code{prob} or \code{prob[t]}). The observed count \code{x[t]} has a probability -according to the Binomial distribution with size parameter N and probability \code{prob} +These nimbleFunctions provide distributions that can be + used directly in R or in \code{nimble} hierarchical models (via + \code{\link[nimble]{nimbleCode}} and + \code{\link[nimble]{nimbleModel}}). + +An N-mixture model defines a distribution for multiple counts +(typically of animals, typically made at a sequence of visits to +the same site). The latent number of animals available to be +counted, N, follows a Poisson distribution with mean \code{lambda}. +Each count, \code{x[i]} for visit \code{i}, #' follows a binomial +distribution with size (number of trials) N and probability of +success (being counted) \code{prob[i]} The distribution has two forms, \code{dNmixture_s} and -\code{dNmixture_v}. These differentiate whether the detection -probability \code{prob} is visit-dependent (a vector, \code{dNmixture_v}) -or visit-independent (a scalar, dNmixture_s). +\code{dNmixture_v}. With \code{dNmixture_s}, detection probability +is a scalar, independent of visit, so \code{prob[i]} should be +replaced with \code{prob} above. With \code{dNmixture_v}, +detection probability is a vector, with one element for each visit, +as written above. For more explanation, see \href{../doc/Introduction_to_nimbleEcology.html}{package vignette} (or \code{vignette("Introduction_to_nimbleEcology")}). Compared to writing \code{nimble} models with a discrete latent -state of abundance N and a separate scalar datum for each observation time, -use of these distributions allows one to directly sum (marginalize) over -the discrete latent state N and calculate the probability of all -observations for a site jointly. - -These are \code{nimbleFunction}s 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 -\href{https://r-nimble.org}{https://r-nimble.org}. - -When using these distributions in a \code{nimble} model, the left-hand side -will be used as \code{x}, and the user should not provide the \code{log} -argument. +state of abundance N and a separate scalar datum for each count, +use of these distributions allows one to directly sum (marginalize) +over the discrete latent state N and calculate the probability of +all observations for a site jointly. + +If one knows a reasonable range for summation over possible values +of N, the start and end of the range can be provided as \code{Nmin} +and \code{Nmax}. Otherwise one can set both to -1, in which case +values for \code{Nmin} and \code{Nmax} will be chosen based on the +0.0001 and 0.9999 quantiles of the marginal distributions of each +count, using the minimum over counts of the former and the maximum +over counts of the latter. + +The summation over N uses the efficient method given by Meehan et +al. (2017). + +These are \code{nimbleFunction}s 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 \href{https://r-nimble.org}{https://r-nimble.org}. + +When using these distributions in a \code{nimble} model, the +left-hand side will be used as \code{x}, and the user should not +provide the \code{log} argument. For example, in \code{nimble} model code, @@ -89,25 +101,26 @@ For example, in \code{nimble} model code, prob[i, 1:T], Nmin, Nmax, T)} -declares that the \code{observedCounts[i, 1:T]} (observed -counts for site \code{i}, for example) vector follows an -N-mixture model distribution with parameters as indicated, -assuming all the parameters have been declared elsewhere in the -model. As above, \code{lambda[i]} is the mean of the abundance distribution at site i, -\code{prob[i, 1:T]} is a vector of detection probabilities at site i, and -\code{T} is the number of observation occasions. This will invoke -(something like) the following call to \code{dNmixture_v} when -\code{nimble} uses the model such as for MCMC: +declares that the \code{observedCounts[i, 1:T]} (observed counts +for site \code{i}, for example) vector follows an N-mixture +distribution with parameters as indicated, assuming all the +parameters have been declared elsewhere in the model. As above, +\code{lambda[i]} is the mean of the abundance distribution at site +i, \code{prob[i, 1:T]} is a vector of detection probabilities at +site i, and \code{T} is the number of observation occasions. This +will invoke (something like) the following call to +\code{dNmixture_v} when \code{nimble} uses the model such as for +MCMC: \code{dNmixture_v(observedCounts[i, 1:T], lambda[i], prob[i, 1:T], -Nmin, Nmax, T)} +Nmin, Nmax, T, log = TRUE)} If an algorithm using a \code{nimble} model with this declaration needs to generate a random draw for \code{observedCounts[1:T]}, it will make a similar invocation of \code{rNmixture_v}, with \code{n = 1}. -If the observation probabilities are occasion-independent, one would use: +If the observation probabilities are visit-independent, one would use: \code{observedCounts[1:T] ~ dNmixture_s(observedCounts[i, 1:T], lambda[i], prob[i], @@ -123,7 +136,7 @@ prob <- c(0.2, 0.3, 0.2, 0.1, 0.4) # A vector of detection probabilities # Define code for a nimbleModel nc <- nimbleCode({ - x[1:5] ~ dNmixture_v(lambda, prob = [1:5], + x[1:5] ~ dNmixture_v(lambda, prob = prob[1:5], Nmin = -1, Nmax = -1, len = 5) lambda ~ dunif(0, 1000) @@ -147,6 +160,7 @@ nmix_model$calculate() 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 + T. Meehan, N. Michel and H. Rue. 2017. Estimating animal abundance with N-mixture models using the R-INLA package for R. arXiv. arXiv:1705.01581 } diff --git a/man/dOcc.Rd b/man/dOcc.Rd index 2d91d5f..2dc093a 100644 --- a/man/dOcc.Rd +++ b/man/dOcc.Rd @@ -6,7 +6,7 @@ \alias{dOcc_v} \alias{rOcc_s} \alias{rOcc_v} -\title{Occupancy distribution suitable for use in code{nimble} models} +\title{Occupancy distribution suitable for use in \code{nimble} models} \usage{ dOcc_s(x, probOcc, probDetect, len = 0, log = 0) @@ -49,7 +49,7 @@ These nimbleFunctions provide distributions that can be used directly in R or in \code{nimble} hierarchical models (via \code{\link[nimble]{nimbleCode}} and \code{\link[nimble]{nimbleModel}}). -The probability (or likelihood) of observation vector \code{x} depends on +The probability of observation vector \code{x} depends on occupancy probability, \code{probOcc}, and detection probability, \code{probDetect} or \code{probDetect[t]}.