Prepared by Ben Goldstein.
What is nimbleEcology?
nimbleEcology is an auxiliary nimble package for ecologists.
nimbleEcology contains a set of distributions corresponding to some common ecological models. When the package is loaded, these distributions are registered to NIMBLE and can be used directly in models.
nimbleEcology contains distributions often used in modeling abundance, occupancy and capture-recapture studies.
Why use nimbleEcology?
Ecological models for abundance, occupancy and capture-recapture often involve many discrete latent states. Writing such models can be error-prone and in some cases can lead to slow MCMC mixing. We’ve put together a collection of distributions in nimble to make writing these models easier
- Easy to use. Using a nimbleEcology distribution is easier than writing out probabilities or hierarchical model descriptions.
- Minimize errors. You don’t have to lose hours looking for the misplaced minus sign; the distributions are checked and tested.
- Integrate over latent states. nimbleEcology implementations integrate or sum likelihoods over latent states. This eliminates the need for sampling these latent variables, which in some cases can provide efficiency gains, and allows maximum likelihood (ML) estimation methods with hierarchical models.
How to use
nimbleEcology can be installed directly from CRAN as follows.
install.packages("nimbleEcology")
Once nimbleEcology is installed, load it using library. It will also load nimble.
## Loading required package: nimble
## nimble version 0.10.0 is loaded.
## For more information on NIMBLE and a User Manual,
## please visit http://R-nimble.org.
##
## Attaching package: 'nimble'
## The following object is masked from 'package:stats':
##
## simulate
## Loading nimbleEcology.
## Registering the following user-defined functions:
## dOcc, dDynOcc, dCJS, dHMM, dDHMM
Note the message indicating which distribution families have been loaded.
Which distributions are available?
The following distributions are available in nimbleEcology.
- dOcc (occupancy model)
- dDynOcc (dynamic occupancy model)
- dHMM (hidden Markov model)
- dDHMM (dynamic hidden Markov model)
- dCJS (Cormack-Jolly-Seber or mark-recapture model)
- dNmixture (N-mixture model)
- dYourNewDistribution Do you have a custom distribution that would fit the package? Are we missing a distribution you need? Let us know! We actively encourage contributions through GitHub or direct communication.
Example code
The following code illustrates a NIMBLE model definition for an occupancy model using nimbleEcology. The model is specified, built, and used to simulate some data according to the occupancy distribution.
library(nimbleEcology)
occ_code <- nimbleCode({
psi ~ dunif(0, 1)
p ~ dunif(0, 1)
for (s in 1:nsite) {
x[s, 1:nvisit] ~ dOcc_s(probOcc = psi, probDetect = p,
len = nvisit)
}
})
occ_model <- nimbleModel(occ_code,
constants = list(nsite = 10, nvisit = 5),
inits = list(psi = 0.5, p = 0.5))
## setting data and initial values...
## running calculate on model (any error reports that follow may simply reflect missing values in model variables) ...
## checking model sizes and dimensions... This model is not fully initialized. This is not an error. To see which variables are not initialized, use model$initializeInfo(). For more information on model initialization, see help(modelInitialization).
## model building finished.
set.seed(94)
occ_model$simulate("x")
occ_model$x
## [,1] [,2] [,3] [,4] [,5]
## [1,] 0 0 0 0 0
## [2,] 0 0 0 0 0
## [3,] 0 0 0 0 0
## [4,] 0 0 0 0 0
## [5,] 1 1 1 0 1
## [6,] 0 0 0 1 0
## [7,] 0 0 0 0 0
## [8,] 0 0 0 0 1
## [9,] 1 1 1 0 0
## [10,] 0 1 0 0 0
How to learn more
Once the package is installed, you can check out the package vignette with vignette(“nimbleEcology”).
Documentation is available for each distribution family using the R syntax ?distribution, for example
For more detail on marginalization in these distributions, see the paper “One size does not fit all: Customizing MCMC methods for hierarchical models using NIMBLE” (Ponisio et al. 2020).