dNmixture: dNmixture distribution for use in 'nimble' models
In nimbleEcology: Distributions for Ecological Models in 'nimble'
dNmixture R Documentation
dNmixture distribution for use in nimble models
Description
dNmixture_s and dNmixture_v provide Poisson-Binomial mixture
distributions of abundance ("N-mixture") for use in nimble models.
Overdispersion alternatives using the negative binomial distribution (for
the abundance submodel) and the beta binomial distribution (for the detection
submodel) are also provided.
Usage
dNmixture_v(x, lambda, prob, Nmin = -1, Nmax = -1, len, log = 0)
dNmixture_s(x, lambda, prob, Nmin = -1, Nmax = -1, len, log = 0)
rNmixture_v(n, lambda, prob, Nmin = -1, Nmax = -1, len)
rNmixture_s(n, lambda, prob, Nmin = -1, Nmax = -1, len)
dNmixture_BNB_v(x, lambda, theta, prob, Nmin = -1, Nmax = -1, len, log = 0)
dNmixture_BNB_s(x, lambda, theta, prob, Nmin = -1, Nmax = -1, len, log = 0)
dNmixture_BNB_oneObs(x, lambda, theta, prob, Nmin = -1, Nmax = -1, log = 0)
dNmixture_BBP_v(x, lambda, prob, s, Nmin = -1, Nmax = -1, len, log = 0)
dNmixture_BBP_s(x, lambda, prob, s, Nmin = -1, Nmax = -1, len, log = 0)
dNmixture_BBP_oneObs(x, lambda, prob, s, Nmin = -1, Nmax = -1, log = 0)
dNmixture_BBNB_v(x, lambda, theta, prob, s, Nmin = -1, Nmax = -1, len, log = 0)
dNmixture_BBNB_s(x, lambda, theta, prob, s, Nmin = -1, Nmax = -1, len, log = 0)
dNmixture_BBNB_oneObs(x, lambda, theta, prob, s, Nmin = -1, Nmax = -1, log = 0)
rNmixture_BNB_v(n, lambda, theta, prob, Nmin = -1, Nmax = -1, len)
rNmixture_BNB_s(n, lambda, theta, prob, Nmin = -1, Nmax = -1, len)
rNmixture_BNB_oneObs(n, lambda, theta, prob, Nmin = -1, Nmax = -1)
rNmixture_BBP_v(n, lambda, prob, s, Nmin = -1, Nmax = -1, len)
rNmixture_BBP_s(n, lambda, prob, s, Nmin = -1, Nmax = -1, len)
rNmixture_BBP_oneObs(n, lambda, prob, s, Nmin = -1, Nmax = -1)
rNmixture_BBNB_v(n, lambda, theta, prob, s, Nmin = -1, Nmax = -1, len)
rNmixture_BBNB_s(n, lambda, theta, prob, s, Nmin = -1, Nmax = -1, len)
rNmixture_BBNB_oneObs(n, lambda, theta, prob, s, Nmin = -1, Nmax = -1)
Arguments
x
vector of integer counts from a series of sampling occasions.
lambda
expected value of the Poisson distribution of true abundance
prob
detection probability (scalar for dNmixture_s, vector for
dNmixture_v).
Nmin
minimum abundance to sum over for the mixture probability. Set to
-1 to select automatically (not available for beta binomial variations; see
Details).
Nmax
maximum abundance to sum over for the mixture probability. Set to
-1 to select automatically (not available for beta binomial variations; see
Details).
len
The length of the x vector
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.
theta
abundance overdispersion parameter required for negative
binomial (*NB) N-mixture models. The negative binomial is parameterized
such that variance of x is lambda^2 * theta + lambda
s
detection overdispersion parameter required for beta binomial (BB*)
N-mixture models. The beta binomial is parameterized such that variance of
x is V(x) = N * prob * (1-prob) * (N + s) / (s + 1)
Details
These nimbleFunctions provide distributions that can be
used directly in R or in nimble hierarchical models (via
nimbleCode and
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 or
negative binomial distribution. Each count, x[i] for visit i,
follows a binomial or beta-binomial distribution. The N-mixture distributions
calculate the marginal probability of observed counts by summing over the
range of latent abundance values.
The basic N-mixture model uses Poisson latent abundance with mean
lambda and binomial observed counts with size (number of trials) N
and probability of success (being counted) prob[i]. This distribution
is available in two forms, dNmixture_s and dNmixture_v. With
dNmixture_s, detection probability is a scalar, independent of visit,
so prob[i] should be replaced with prob above. With
dNmixture_v, detection probability is a vector, with one element for
each visit, as written above.
We also provide three important variations on the traditional N-mixture
model: dNmixture_BNB, dNmixture_BBP, and dNmixture_BBNB.
These distributions allow you to replace the Poisson (P) abundance
distribution with the negative binomial (NB) and the binomial (B) detection
distribution with the beta binomial (BB).
Binomial-negative binomial: BNB N-mixture models use a binomial distribution
for detection and a negative binomial distribution for abundance with scalar
overdispersion parameter theta (0-Inf). We parameterize such that the
variance of the negative binomial is lambda^2 * theta + lambda, so
large theta indicates a large amount of overdisperison in abundance.
The BNB is available in three suffixed forms: dNmixture_BNB_v is used
if prob varies between observations, dNmixture_BNB_s is used if
prob is scalar (constant across observations), and
dNmixture_BNB_oneObs is used if only one observation is available at
the site (so both x and prob are scalar).
Beta-binomial-Poisson: BBP N-mixture uses a beta binomial distribution for
detection probabilities and a Poisson distribution for abundance. The beta
binomial distribution has scalar overdispersion parameter s (0-Inf). We
parameterize such that the variance of the beta binomial is N * prob
* (1-prob) * (N + s) / (s + 1), with greater s indicating less variance
(greater-than-binomial relatedness between observations at the site) and s ->
0 indicating the binomial. The BBP is available in three suffixed forms:
dNmixture_BBP_v is used if prob varies between observations,
dNmixture_BBP_s is used if prob is scalar (constant across
observations), and dNmixture_BBP_oneObs is used if only one
observation is available at the site (so both x and prob are scalar).
Beta-binomial-negative-binomial: dNmixture_BBNB is available using a negative
binomial abundance distribution and a beta binomial detection distribution.
dNmixture_BBNB is available with _s, _v, and
_oneObs suffixes as above and requires both arguments s and
theta as parameterized above.
The distribution dNmixture_oneObs is not provided as the probability given
by the traditional N-mixture distribution for length(x) = 1 is
equivalent to dpois(prob * lambda).
For more explanation, see package vignette
(vignette("Introduction_to_nimbleEcology")).
Compared to writing nimble models with a discrete latent 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 Nmin and Nmax.
Otherwise one can set both to -1, in which case values for Nmin and
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. (2020,
see Appendix B) for the basic Poisson-Binomial case, extended for the
overdispersion cases in Goldstein and de Valpine (2022).
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,
observedCounts[i, 1:T] ~ dNmixture_v(lambda[i],
prob[i, 1:T],
Nmin, Nmax, T)
declares that the observedCounts[i, 1:T] (observed counts
for site 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,
lambda[i] is the mean of the abundance distribution at site
i, prob[i, 1:T] is a vector of detection probabilities at
site i, and T is the number of observation occasions. This
will invoke (something like) the following call to
dNmixture_v when nimble uses the model such as for
MCMC:
dNmixture_v(observedCounts[i, 1:T], lambda[i],
prob[i, 1:T],
Nmin, Nmax, T, log = TRUE)
If an algorithm using a nimble model with this declaration
needs to generate a random draw for observedCounts[1:T], it
will make a similar invocation of rNmixture_v, with n = 1.
If the observation probabilities are visit-independent, one would use:
observedCounts[1:T] ~ dNmixture_s(observedCounts[i, 1:T], lambda[i],
prob[i],
Nmin, Nmax, T)
Value
For dNmixture_s and dNmixture_v: the probability (or likelihood) or log
probability of observation vector x.
For rNmixture_s and rNmixture_v: a simulated detection history, x.
Notes for use with automatic differentiation
The N-mixture distributions are the only ones in nimbleEcology for which
one must use different versions when AD support is needed. See
dNmixtureAD.
Author(s)
Ben Goldstein, Lauren Ponisio, and Perry de Valpine
References
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
Meehan, T. D., Michel, N. L., & Rue, H. 2020. Estimating Animal Abundance
with N-Mixture Models Using the R—INLA Package for R. Journal of Statistical
Software, 95(2). https://doi.org/10.18637/jss.v095.i02
Goldstein, B.R., and P. de Valpine. 2022. Comparing N-mixture Models and
GLMMs for Relative Abundance Estimation in a Citizen Science Dataset.
Scientific Reports 12: 12276. DOI:10.1038/s41598-022-16368-z
See Also
For occupancy models dealing with detection/nondetection data,
see dOcc.
For dynamic occupancy, see dDynOcc.
Examples
# Set up constants and initial values for defining the model
len <- 5 # length of dataset
dat <- c(1,2,0,1,5) # A vector of observations
lambda <- 10 # mean abundance
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 = prob[1:5],
Nmin = -1, Nmax = -1, len = 5)
lambda ~ dunif(0, 1000)
for (i in 1:5) {
prob[i] ~ dunif(0, 1)
}
})
# Build the model
nmix <- nimbleModel(nc,
data = list(x = dat),
inits = list(lambda = lambda,
prob = prob))
# Calculate log probability of data from the model
nmix$calculate()
# Use the model for a variety of other purposes...
nimbleEcology documentation built on June 27, 2024, 5:09 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| dNmixture | R Documentation |
dNmixture distribution for use in nimble models
Description
dNmixture_s and dNmixture_v provide Poisson-Binomial mixture
distributions of abundance ("N-mixture") for use in nimble models.
Overdispersion alternatives using the negative binomial distribution (for
the abundance submodel) and the beta binomial distribution (for the detection
submodel) are also provided.
Usage
dNmixture_v(x, lambda, prob, Nmin = -1, Nmax = -1, len, log = 0)
dNmixture_s(x, lambda, prob, Nmin = -1, Nmax = -1, len, log = 0)
rNmixture_v(n, lambda, prob, Nmin = -1, Nmax = -1, len)
rNmixture_s(n, lambda, prob, Nmin = -1, Nmax = -1, len)
dNmixture_BNB_v(x, lambda, theta, prob, Nmin = -1, Nmax = -1, len, log = 0)
dNmixture_BNB_s(x, lambda, theta, prob, Nmin = -1, Nmax = -1, len, log = 0)
dNmixture_BNB_oneObs(x, lambda, theta, prob, Nmin = -1, Nmax = -1, log = 0)
dNmixture_BBP_v(x, lambda, prob, s, Nmin = -1, Nmax = -1, len, log = 0)
dNmixture_BBP_s(x, lambda, prob, s, Nmin = -1, Nmax = -1, len, log = 0)
dNmixture_BBP_oneObs(x, lambda, prob, s, Nmin = -1, Nmax = -1, log = 0)
dNmixture_BBNB_v(x, lambda, theta, prob, s, Nmin = -1, Nmax = -1, len, log = 0)
dNmixture_BBNB_s(x, lambda, theta, prob, s, Nmin = -1, Nmax = -1, len, log = 0)
dNmixture_BBNB_oneObs(x, lambda, theta, prob, s, Nmin = -1, Nmax = -1, log = 0)
rNmixture_BNB_v(n, lambda, theta, prob, Nmin = -1, Nmax = -1, len)
rNmixture_BNB_s(n, lambda, theta, prob, Nmin = -1, Nmax = -1, len)
rNmixture_BNB_oneObs(n, lambda, theta, prob, Nmin = -1, Nmax = -1)
rNmixture_BBP_v(n, lambda, prob, s, Nmin = -1, Nmax = -1, len)
rNmixture_BBP_s(n, lambda, prob, s, Nmin = -1, Nmax = -1, len)
rNmixture_BBP_oneObs(n, lambda, prob, s, Nmin = -1, Nmax = -1)
rNmixture_BBNB_v(n, lambda, theta, prob, s, Nmin = -1, Nmax = -1, len)
rNmixture_BBNB_s(n, lambda, theta, prob, s, Nmin = -1, Nmax = -1, len)
rNmixture_BBNB_oneObs(n, lambda, theta, prob, s, Nmin = -1, Nmax = -1)
Arguments
x |
vector of integer counts from a series of sampling occasions. |
lambda |
expected value of the Poisson distribution of true abundance |
prob |
detection probability (scalar for |
Nmin |
minimum abundance to sum over for the mixture probability. Set to -1 to select automatically (not available for beta binomial variations; see Details). |
Nmax |
maximum abundance to sum over for the mixture probability. Set to -1 to select automatically (not available for beta binomial variations; see Details). |
len |
The length of the x vector |
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
|
theta |
abundance overdispersion parameter required for negative
binomial (*NB) N-mixture models. The negative binomial is parameterized
such that variance of x is |
s |
detection overdispersion parameter required for beta binomial (BB*)
N-mixture models. The beta binomial is parameterized such that variance of
x is |
Details
These nimbleFunctions provide distributions that can be
used directly in R or in nimble hierarchical models (via
nimbleCode and
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 or
negative binomial distribution. Each count, x[i] for visit i,
follows a binomial or beta-binomial distribution. The N-mixture distributions
calculate the marginal probability of observed counts by summing over the
range of latent abundance values.
The basic N-mixture model uses Poisson latent abundance with mean
lambda and binomial observed counts with size (number of trials) N
and probability of success (being counted) prob[i]. This distribution
is available in two forms, dNmixture_s and dNmixture_v. With
dNmixture_s, detection probability is a scalar, independent of visit,
so prob[i] should be replaced with prob above. With
dNmixture_v, detection probability is a vector, with one element for
each visit, as written above.
We also provide three important variations on the traditional N-mixture
model: dNmixture_BNB, dNmixture_BBP, and dNmixture_BBNB.
These distributions allow you to replace the Poisson (P) abundance
distribution with the negative binomial (NB) and the binomial (B) detection
distribution with the beta binomial (BB).
Binomial-negative binomial: BNB N-mixture models use a binomial distribution
for detection and a negative binomial distribution for abundance with scalar
overdispersion parameter theta (0-Inf). We parameterize such that the
variance of the negative binomial is lambda^2 * theta + lambda, so
large theta indicates a large amount of overdisperison in abundance.
The BNB is available in three suffixed forms: dNmixture_BNB_v is used
if prob varies between observations, dNmixture_BNB_s is used if
prob is scalar (constant across observations), and
dNmixture_BNB_oneObs is used if only one observation is available at
the site (so both x and prob are scalar).
Beta-binomial-Poisson: BBP N-mixture uses a beta binomial distribution for
detection probabilities and a Poisson distribution for abundance. The beta
binomial distribution has scalar overdispersion parameter s (0-Inf). We
parameterize such that the variance of the beta binomial is N * prob
* (1-prob) * (N + s) / (s + 1), with greater s indicating less variance
(greater-than-binomial relatedness between observations at the site) and s ->
0 indicating the binomial. The BBP is available in three suffixed forms:
dNmixture_BBP_v is used if prob varies between observations,
dNmixture_BBP_s is used if prob is scalar (constant across
observations), and dNmixture_BBP_oneObs is used if only one
observation is available at the site (so both x and prob are scalar).
Beta-binomial-negative-binomial: dNmixture_BBNB is available using a negative
binomial abundance distribution and a beta binomial detection distribution.
dNmixture_BBNB is available with _s, _v, and
_oneObs suffixes as above and requires both arguments s and
theta as parameterized above.
The distribution dNmixture_oneObs is not provided as the probability given
by the traditional N-mixture distribution for length(x) = 1 is
equivalent to dpois(prob * lambda).
For more explanation, see package vignette
(vignette("Introduction_to_nimbleEcology")).
Compared to writing nimble models with a discrete latent 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 Nmin and Nmax.
Otherwise one can set both to -1, in which case values for Nmin and
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. (2020, see Appendix B) for the basic Poisson-Binomial case, extended for the overdispersion cases in Goldstein and de Valpine (2022).
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,
observedCounts[i, 1:T] ~ dNmixture_v(lambda[i],
prob[i, 1:T],
Nmin, Nmax, T)
declares that the observedCounts[i, 1:T] (observed counts
for site 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,
lambda[i] is the mean of the abundance distribution at site
i, prob[i, 1:T] is a vector of detection probabilities at
site i, and T is the number of observation occasions. This
will invoke (something like) the following call to
dNmixture_v when nimble uses the model such as for
MCMC:
dNmixture_v(observedCounts[i, 1:T], lambda[i],
prob[i, 1:T],
Nmin, Nmax, T, log = TRUE)
If an algorithm using a nimble model with this declaration
needs to generate a random draw for observedCounts[1:T], it
will make a similar invocation of rNmixture_v, with n = 1.
If the observation probabilities are visit-independent, one would use:
observedCounts[1:T] ~ dNmixture_s(observedCounts[i, 1:T], lambda[i],
prob[i],
Nmin, Nmax, T)
Value
For dNmixture_s and dNmixture_v: the probability (or likelihood) or log
probability of observation vector x.
For rNmixture_s and rNmixture_v: a simulated detection history, x.
Notes for use with automatic differentiation
The N-mixture distributions are the only ones in nimbleEcology for which
one must use different versions when AD support is needed. See
dNmixtureAD.
Author(s)
Ben Goldstein, Lauren Ponisio, and Perry de Valpine
References
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
Meehan, T. D., Michel, N. L., & Rue, H. 2020. Estimating Animal Abundance with N-Mixture Models Using the R—INLA Package for R. Journal of Statistical Software, 95(2). https://doi.org/10.18637/jss.v095.i02
Goldstein, B.R., and P. de Valpine. 2022. Comparing N-mixture Models and GLMMs for Relative Abundance Estimation in a Citizen Science Dataset. Scientific Reports 12: 12276. DOI:10.1038/s41598-022-16368-z
See Also
For occupancy models dealing with detection/nondetection data,
see dOcc.
For dynamic occupancy, see dDynOcc.
Examples
# Set up constants and initial values for defining the model
len <- 5 # length of dataset
dat <- c(1,2,0,1,5) # A vector of observations
lambda <- 10 # mean abundance
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 = prob[1:5],
Nmin = -1, Nmax = -1, len = 5)
lambda ~ dunif(0, 1000)
for (i in 1:5) {
prob[i] ~ dunif(0, 1)
}
})
# Build the model
nmix <- nimbleModel(nc,
data = list(x = dat),
inits = list(lambda = lambda,
prob = prob))
# Calculate log probability of data from the model
nmix$calculate()
# Use the model for a variety of other purposes...
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.