dDynOcc: Dynamic occupancy distribution for use in 'nimble' models...
In nimbleEcology: Distributions for Ecological Models in 'nimble'
dDynOcc R Documentation
Dynamic occupancy distribution for use in nimble models
dDynOcc_** and rDynOcc_** provide dynamic occupancy
model distributions that can be used directly from R or in nimble
models.
Description
Dynamic occupancy distribution for use in nimble models
dDynOcc_** and rDynOcc_** provide dynamic occupancy
model distributions that can be used directly from R or in nimble
models.
Usage
dDynOcc_vvm(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_vsm(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_svm(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_ssm(x, init, probPersist, probColonize, p, start, end, log = 0)
rDynOcc_vvm(n, init, probPersist, probColonize, p, start, end)
rDynOcc_vsm(n, init, probPersist, probColonize, p, start, end)
rDynOcc_svm(n, init, probPersist, probColonize, p, start, end)
rDynOcc_ssm(n, init, probPersist, probColonize, p, start, end)
dDynOcc_vvv(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_vsv(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_svv(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_ssv(x, init, probPersist, probColonize, p, start, end, log = 0)
rDynOcc_vvv(n, init, probPersist, probColonize, p, start, end)
rDynOcc_vsv(n, init, probPersist, probColonize, p, start, end)
rDynOcc_svv(n, init, probPersist, probColonize, p, start, end)
rDynOcc_ssv(n, init, probPersist, probColonize, p, start, end)
dDynOcc_vvs(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_vss(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_svs(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_sss(x, init, probPersist, probColonize, p, start, end, log = 0)
rDynOcc_vvs(n, init, probPersist, probColonize, p, start, end)
rDynOcc_vss(n, init, probPersist, probColonize, p, start, end)
rDynOcc_svs(n, init, probPersist, probColonize, p, start, end)
rDynOcc_sss(n, init, probPersist, probColonize, p, start, end)
Arguments
x
detection/non-detection matrix of 0s (not detected) and 1s
(detected). Rows represent primary sampling occasions (e.g. different
seasons). Columns are secondary sampling locations (e.g. replicate
visits within a season) that may be different for each row
init
probability of occupancy in the first sampling period
probPersist
persistence probability–probability an occupied
cell remains occupied. 1-extinction probability. Scalar for
dDynOcc_s**, vector for dDynOcc_v**. If vector,
should have length dim(x)[1] - 1 since no transition occurs
after the last observation
probColonize
colonization probability. Probability that
an unoccupied cell becomes occupied. Scalar for dDynOcc_*s*,
vector for dDynOcc_*v*. If vector, should have length
dim(x)[1] - 1 since no transition occurs after the last observation
p
Detection probabilities. Scalar for dDynOcc_**s,
vector for dDynOcc_**v, matrix for dDynOcc_**m.
If a matrix, dimensions should match x
start
indicates the column number of the first observation in each
row of x. A vector of length dim(x)[1]. This allows for different time
periods to have different numbers of sampling occasions
end
indicates the column number of the last observation in each
row of x. A vector of length dim(x)[1]. This allows for different time
periods to have different numbers of sampling occasions
log
TRUE (return log probability) or FALSE (return probability)
n
number of random draws, each returning a matrix of dimension
c(min(start), max(end)). 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 (or likelihood) of observation x[t, o] depends on
the occupancy status of the site at time t-1, the transitition
probability of persistence (probPersist or probPersist[t-1]),
colonization (probColonize or probColonize[t-1]), and a
detection probability (p, p[t], or p[t, o]).
The first two letters following the 'dDynOcc_' indicate whether the
probabilities of persistence and colonization are a constant scalar (s)
or time-indexed vector (v). For example, dDynOcc_svm takes scalar
persistence probability probPersist with a vector of colonization
probabilities probColonize[1:(T-1)].
When vectors, probColonize and probPersist may be of any
length greater than or equal to length(x) - 1. Only the first length(x) - 1
indices are used, each corresponding to the transition from time t to t+1
(e.g. probColonize[2] describes the transition probability from
t = 2 to t = 3). All extra values are ignored. This is to make it easier to
use one distribution for many sites, some requiring probabilities of length 1.
The third letter in the suffix indicates whether the detection probability
is a constant (scalar), time-dependent (vector), or both time-dependent and
dependent on observation occasion (matrix). For example, dDynOcc_svm
takes a matrix of detection probabilities p[1:T, 1:O].
The arguments start and end allow different time periods to
contain different numbers of sampling events. Suppose you have observations
for samples in three seasons; in the first two seasons, there are four
observations, but in the third, there are only three. The start
and end could be provided as start = c(1,1,1) and
end = c(4,4,3). In this case, the value of x[4,4] would
be ignored.
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[1:T, 1:O] ~ dDynOcc_ssm(init,
probPersist = persistence_prob,
probColonize = colonization_prob, p = p[1:T, 1:O],
start = start[1:T], end = end[1:T])
declares that the detections[1:T] vector follows a dynamic occupancy
model 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 dDynOcc_ssm when
nimble uses the model such as for MCMC:
dDynOcc_ssm(detections[1:T, 1:O], init,
probPersist = persistence_prob,
probColonize = colonization_prob, p = p[1:T, 1:O],
start = start[1:T], end = end[1:T], log = TRUE)
If an algorithm using a nimble model with this declaration
needs to generate a random draw for detections[1:T, 1:O], it
will make a similar invocation of rDynOcc_ssm, with n = 1.
If the colonization probabilities are time-dependent, one would use:
detections[1:T] ~ dDynOcc_svm(nrep, init = init_prob,
probPersist = persistence_prob,
probColonize = colonization_prob[1:(T-1)], p = p[1:T, 1:O])
Value
For dDynOcc_***: the probability (or likelihood) or log probability
of observation vector x.
For rDynOcc_***: a simulated detection history, x.
Notes for use with automatic differentiation
The dDynOcc_*** 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 dDynOcc_*** distributions, the lengths or dimensions of
vector and/or matrix inputs and the start and end values
themselves 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 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 basic occupancy models, see documentation for
dOcc.
Examples
# Set up constants and initial values for defining the model
x <- matrix(c(0,0,0,0,
1,1,1,0,
0,0,0,0,
0,0,1,0,
0,0,0,0), nrow = 4)
start <- c(1,1,2,1,1)
end <- c(5,5,5,4,5)
init <- 0.7
probPersist <- 0.5
probColonize <- 0.2
p <- matrix(rep(0.5, 20), nrow = 4)
# Define code for a nimbleModel
nc <- nimbleCode({
x[1:2, 1:5] ~ dDynOcc_vvm(init,
probPersist[1:2], probColonize[1:2], p[1:2,1:5],
start = start[1:4], end = end[1:4])
init ~ dunif(0,1)
for (i in 1:2) {
probPersist[i] ~ dunif(0,1)
probColonize[i] ~ dunif(0,1)
}
for (i in 1:2) {
for (j in 1:5) {
p[i,j] ~ dunif(0,1)
}
}
})
# Build the model, providing data and initial values
DynOcc_model <- nimbleModel(nc, data = list(x = x),
constants = list(start = start, end = end),
inits = list(p = p, probPersist = probPersist,
init = init, probColonize = probColonize))
# Calculate log probability of data from the model
DynOcc_model$calculate("x")
# 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.
| dDynOcc | R Documentation |
Dynamic occupancy distribution for use in nimble models
dDynOcc_** and rDynOcc_** provide dynamic occupancy
model distributions that can be used directly from R or in nimble
models.
Description
Dynamic occupancy distribution for use in nimble models
dDynOcc_** and rDynOcc_** provide dynamic occupancy
model distributions that can be used directly from R or in nimble
models.
Usage
dDynOcc_vvm(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_vsm(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_svm(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_ssm(x, init, probPersist, probColonize, p, start, end, log = 0)
rDynOcc_vvm(n, init, probPersist, probColonize, p, start, end)
rDynOcc_vsm(n, init, probPersist, probColonize, p, start, end)
rDynOcc_svm(n, init, probPersist, probColonize, p, start, end)
rDynOcc_ssm(n, init, probPersist, probColonize, p, start, end)
dDynOcc_vvv(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_vsv(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_svv(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_ssv(x, init, probPersist, probColonize, p, start, end, log = 0)
rDynOcc_vvv(n, init, probPersist, probColonize, p, start, end)
rDynOcc_vsv(n, init, probPersist, probColonize, p, start, end)
rDynOcc_svv(n, init, probPersist, probColonize, p, start, end)
rDynOcc_ssv(n, init, probPersist, probColonize, p, start, end)
dDynOcc_vvs(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_vss(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_svs(x, init, probPersist, probColonize, p, start, end, log = 0)
dDynOcc_sss(x, init, probPersist, probColonize, p, start, end, log = 0)
rDynOcc_vvs(n, init, probPersist, probColonize, p, start, end)
rDynOcc_vss(n, init, probPersist, probColonize, p, start, end)
rDynOcc_svs(n, init, probPersist, probColonize, p, start, end)
rDynOcc_sss(n, init, probPersist, probColonize, p, start, end)
Arguments
x |
detection/non-detection matrix of 0s (not detected) and 1s (detected). Rows represent primary sampling occasions (e.g. different seasons). Columns are secondary sampling locations (e.g. replicate visits within a season) that may be different for each row |
init |
probability of occupancy in the first sampling period |
probPersist |
persistence probability–probability an occupied
cell remains occupied. 1-extinction probability. Scalar for
|
probColonize |
colonization probability. Probability that
an unoccupied cell becomes occupied. Scalar for |
p |
Detection probabilities. Scalar for |
start |
indicates the column number of the first observation in each row of x. A vector of length dim(x)[1]. This allows for different time periods to have different numbers of sampling occasions |
end |
indicates the column number of the last observation in each row of x. A vector of length dim(x)[1]. This allows for different time periods to have different numbers of sampling occasions |
log |
TRUE (return log probability) or FALSE (return probability) |
n |
number of random draws, each returning a matrix of dimension
|
Details
These nimbleFunctions provide distributions that can be used directly in R or
in nimble hierarchical models (via nimbleCode
and nimbleModel).
The probability (or likelihood) of observation x[t, o] depends on
the occupancy status of the site at time t-1, the transitition
probability of persistence (probPersist or probPersist[t-1]),
colonization (probColonize or probColonize[t-1]), and a
detection probability (p, p[t], or p[t, o]).
The first two letters following the 'dDynOcc_' indicate whether the
probabilities of persistence and colonization are a constant scalar (s)
or time-indexed vector (v). For example, dDynOcc_svm takes scalar
persistence probability probPersist with a vector of colonization
probabilities probColonize[1:(T-1)].
When vectors, probColonize and probPersist may be of any
length greater than or equal to length(x) - 1. Only the first length(x) - 1
indices are used, each corresponding to the transition from time t to t+1
(e.g. probColonize[2] describes the transition probability from
t = 2 to t = 3). All extra values are ignored. This is to make it easier to
use one distribution for many sites, some requiring probabilities of length 1.
The third letter in the suffix indicates whether the detection probability
is a constant (scalar), time-dependent (vector), or both time-dependent and
dependent on observation occasion (matrix). For example, dDynOcc_svm
takes a matrix of detection probabilities p[1:T, 1:O].
The arguments start and end allow different time periods to
contain different numbers of sampling events. Suppose you have observations
for samples in three seasons; in the first two seasons, there are four
observations, but in the third, there are only three. The start
and end could be provided as start = c(1,1,1) and
end = c(4,4,3). In this case, the value of x[4,4] would
be ignored.
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[1:T, 1:O] ~ dDynOcc_ssm(init,
probPersist = persistence_prob,
probColonize = colonization_prob, p = p[1:T, 1:O],
start = start[1:T], end = end[1:T])
declares that the detections[1:T] vector follows a dynamic occupancy
model 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 dDynOcc_ssm when
nimble uses the model such as for MCMC:
dDynOcc_ssm(detections[1:T, 1:O], init,
probPersist = persistence_prob,
probColonize = colonization_prob, p = p[1:T, 1:O],
start = start[1:T], end = end[1:T], log = TRUE)
If an algorithm using a nimble model with this declaration
needs to generate a random draw for detections[1:T, 1:O], it
will make a similar invocation of rDynOcc_ssm, with n = 1.
If the colonization probabilities are time-dependent, one would use:
detections[1:T] ~ dDynOcc_svm(nrep, init = init_prob,
probPersist = persistence_prob,
probColonize = colonization_prob[1:(T-1)], p = p[1:T, 1:O])
Value
For dDynOcc_***: the probability (or likelihood) or log probability
of observation vector x.
For rDynOcc_***: a simulated detection history, x.
Notes for use with automatic differentiation
The dDynOcc_*** 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 dDynOcc_*** distributions, the lengths or dimensions of
vector and/or matrix inputs and the start and end values
themselves 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 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 basic occupancy models, see documentation for
dOcc.
Examples
# Set up constants and initial values for defining the model
x <- matrix(c(0,0,0,0,
1,1,1,0,
0,0,0,0,
0,0,1,0,
0,0,0,0), nrow = 4)
start <- c(1,1,2,1,1)
end <- c(5,5,5,4,5)
init <- 0.7
probPersist <- 0.5
probColonize <- 0.2
p <- matrix(rep(0.5, 20), nrow = 4)
# Define code for a nimbleModel
nc <- nimbleCode({
x[1:2, 1:5] ~ dDynOcc_vvm(init,
probPersist[1:2], probColonize[1:2], p[1:2,1:5],
start = start[1:4], end = end[1:4])
init ~ dunif(0,1)
for (i in 1:2) {
probPersist[i] ~ dunif(0,1)
probColonize[i] ~ dunif(0,1)
}
for (i in 1:2) {
for (j in 1:5) {
p[i,j] ~ dunif(0,1)
}
}
})
# Build the model, providing data and initial values
DynOcc_model <- nimbleModel(nc, data = list(x = x),
constants = list(start = start, end = end),
inits = list(p = p, probPersist = probPersist,
init = init, probColonize = probColonize))
# Calculate log probability of data from the model
DynOcc_model$calculate("x")
# 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.